Module me.ahoo.cosid.core
Package me.ahoo.cosid.segment

Class SegmentGenerator

java.lang.Object
me.ahoo.cosid.segment.SegmentGenerator
All Implemented Interfaces:
AutoCloseable, IdGenerator
public final class SegmentGenerator extends Object implements IdGenerator, AutoCloseable
Issues the values of ranges reserved from a RangeStore (04-segment.md §2): one atomic increment on the hot path, refills off the lock and single-flight, reservation size adapted to a time budget.

The hot path reads the current cursor once and takes a value from it. Only when the cursor is used up, expired or closed does a caller take the switch lock (spinning briefly first, since another caller usually switches within microseconds), move to the next ready range, and start a refill when the ready values fall below the lookahead budget. The switch lock never covers I/O: reservations run on the refill executor, single-flight, and a caller with no value left waits for the one in flight outside the lock, at most BatchPolicy.reserveTimeout(), or makes it itself (still outside the lock) if the executor has not started it. A reservation that completes after its waiters gave up still delivers its range. After a failed reservation no new one starts for a backoff that doubles from 100ms up to 5s; meanwhile callers with no value left fail at once.

Its public constructors are the assembly entry CosIdRuntime uses (R2-core-03): they keep their signatures, and a new parameter comes only through a builder or a static factory, never as one more positional overload (api-freeze.md §4.2).

  • Field Details

  • Constructor Details

    • SegmentGenerator

      public SegmentGenerator(String name, String key, RangeStore store, BatchPolicy policy, Executor refillExecutor, TimeSource time, GeneratorListener listener)
      A segment generator. It reserves nothing until the first generate().
      Parameters:
      name - the generator name, for events and errors
      key - the range key
      store - the range store
      policy - the batch policy
      refillExecutor - runs the reservations; the runtime's own executor by default
      time - the time source
      listener - the event listener

    • SegmentGenerator

      public SegmentGenerator(String name, String key, String storeName, RangeStore store, BatchPolicy policy, Executor refillExecutor, TimeSource time, GeneratorListener listener)
      A segment generator on a named store. It reserves nothing until the first generate().
      Parameters:
      name - the generator name, for events and errors
      key - the range key
      storeName - the store name, for GeneratorListener.onStoreTimeout(java.lang.String, java.lang.String) when a caller waits for a refill longer than the reserve timeout
      store - the range store
      policy - the batch policy
      refillExecutor - runs the reservations; the runtime's own executor by default
      time - the time source
      listener - the event listener

  • Method Details

    • name

      public String name()

    • key

      public String key()

    • policy

      public BatchPolicy policy()

    • generate

      public long generate()
      Issues the next value.
      Specified by:
      generate in interface IdGenerator
      Returns:
      the value
      Throws:
      RangeUnavailableException - if no range arrives within the reserve timeout, or a refill is backing off after a failure
      RangeSealedException - if the key is sealed
      RangeExhaustedException - if the key has no values left
      IllegalStateException - if the generator is closed

    • held

      public long held()
      The values at hand, for describe().
      Returns:
      the rest of the current range plus the ready ranges

    • batch

      public long batch()
      The size of the next reservation, for describe().
      Returns:
      the batch size the rate estimate gives now

    • close

      public void close()
      Stops issuing, cancels the refill in flight and drops the ready ranges (S4 allows the gap). Closing again does nothing.
      Specified by:
      close in interface AutoCloseable