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

Class PeriodicSegmentGenerator

java.lang.Object
me.ahoo.cosid.segment.PeriodicSegmentGenerator
All Implemented Interfaces:
AutoCloseable, GroupedIdGenerator
public final class PeriodicSegmentGenerator extends Object implements GroupedIdGenerator, AutoCloseable
Segments grouped by period (D5, 04-segment.md §3): at most two SegmentGenerators, the current period's and the next one's, at the store keys {key}/{period}.

The hot path reads the time once and compares it with a precomputed instant; before it, the id comes from the current period's generator. From PeriodicPolicy.prewarm() before the period ends the next period's generator is created and starts its first reservation, so that crossing the boundary needs no synchronous store call. At the boundary the old period's generator is closed; its key is sealed only PeriodicPolicy.sealAfter() after the period ended, on the refill executor. Periods only move forward: a generator never returns to a period it left, and a sealed key fails with RangeSealedException rather than being recreated (S6).

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).

  • Constructor Details

    • PeriodicSegmentGenerator

      public PeriodicSegmentGenerator(String name, String key, Period period, ZoneId zone, RangeStore store, BatchPolicy policy, PeriodicPolicy periodic, Executor refillExecutor, TimeSource time, GeneratorListener listener)
      A periodic segment generator. It reserves nothing until the first generate().
      Parameters:
      name - the generator name, for events and errors
      key - the range key the period keys are appended to
      period - the period
      zone - the time zone the periods follow
      store - the range store
      policy - the batch policy of each period
      periodic - the periodic policy
      refillExecutor - runs the reservations
      time - the time source
      listener - the event listener

    • PeriodicSegmentGenerator

      public PeriodicSegmentGenerator(String name, String key, String storeName, Period period, ZoneId zone, RangeStore store, BatchPolicy policy, PeriodicPolicy periodic, Executor refillExecutor, TimeSource time, GeneratorListener listener)
      A periodic 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 the period keys are appended to
      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
      period - the period
      zone - the time zone the periods follow
      store - the range store
      policy - the batch policy of each period
      periodic - the periodic policy
      refillExecutor - runs the reservations
      time - the time source
      listener - the event listener

  • Method Details

    • name

      public String name()
      The generator name.
      Returns:
      the name

    • generate

      public GroupedId generate()
      Issues the next id of the current period.
      Specified by:
      generate in interface GroupedIdGenerator
      Returns:
      the id with its period
      Throws:
      RangeSealedException - if the period's key is already sealed (a lagging clock)
      RangeUnavailableException - if the period's generator has no range in time
      IllegalStateException - if the generator is closed

    • currentPeriod

      public String currentPeriod()
      The period being issued, for describe().
      Returns:
      the period key, empty before the first id

    • held

      public long held()
      The values at hand in the period being issued, for describe().
      Returns:
      the rest of its current range plus its ready ranges; 0 before the first id

    • batch

      public long batch()
      The size of the next reservation in the period being issued, for describe().
      Returns:
      the batch size the rate estimate gives now; the step before the first id

    • close

      public void close()
      Closes the generators of the current and the next period. Keys not sealed yet stay unsealed. Closing again does nothing.
      Specified by:
      close in interface AutoCloseable