Package me.ahoo.cosid.segment

Class IdSegmentChain

java.lang.Object
me.ahoo.cosid.segment.IdSegmentChain
All Implemented Interfaces:
Comparable<IdSegment>, Grouped, IdSegment
public class IdSegmentChain extends Object implements IdSegment
Chained ID segment for lock-free segment chain ID generation.

This class chains multiple ID segments together, allowing for seamless transition between segments without blocking. When one segment is exhausted, the next segment in the chain is used.

  • Field Details

    • ROOT_VERSION

      public static final int ROOT_VERSION
      Version number for the root chain.
      See Also:

    • NOT_SET

      public static final IdSegmentChain NOT_SET
      Sentinel value indicating next has not been set.

  • Constructor Details

    • IdSegmentChain

      public IdSegmentChain(IdSegmentChain previousChain, IdSegment idSegment, boolean allowReset)
      Creates a new chain segment linked to a previous chain.
      Parameters:
      previousChain - the previous chain in the link
      idSegment - the ID segment for this chain
      allowReset - whether reset is allowed

    • IdSegmentChain

      public IdSegmentChain(long version, IdSegment idSegment, boolean allowReset)
      Creates a new chain segment with explicit version.
      Parameters:
      version - the version number
      idSegment - the ID segment for this chain
      allowReset - whether reset is allowed

  • Method Details

    • trySetNext

      public boolean trySetNext(Function<IdSegmentChain,IdSegmentChain> idSegmentChainSupplier) throws NextIdSegmentExpiredException
      Attempts to set the next segment in the chain.

      If next is already set, returns false without modifying.

      Parameters:
      idSegmentChainSupplier - supplier that creates the next segment based on this
      Returns:
      true if set successfully, false if next was already set
      Throws:
      NextIdSegmentExpiredException - if the provided segment has expired

    • setNext

      public void setNext(IdSegmentChain nextIdSegmentChain)
      Sets the next segment in the chain.
      Parameters:
      nextIdSegmentChain - the next segment

    • ensureSetNext

      public IdSegmentChain ensureSetNext(Function<IdSegmentChain,IdSegmentChain> idSegmentChainSupplier) throws NextIdSegmentExpiredException
      Ensures the next segment is set, retrying until successful.
      Parameters:
      idSegmentChainSupplier - supplier that creates the next segment
      Returns:
      the chain that has next set
      Throws:
      NextIdSegmentExpiredException - if all segments expire

    • getNext

      public IdSegmentChain getNext()
      Gets the next segment in the chain.
      Returns:
      the next segment or null if not yet set

    • getIdSegment

      public IdSegment getIdSegment()
      Gets the ID segment for this chain.
      Returns:
      the ID segment

    • group

      public GroupedKey group()
      Description copied from interface: Grouped
      Gets the grouping key for this object.

      Default implementation returns GroupedKey.NEVER, indicating this object should not be grouped.

      Specified by:
      group in interface Grouped
      Returns:
      the grouping key

    • getVersion

      public long getVersion()
      Gets the version number of this chain.
      Returns:
      the version

    • gap

      public int gap(IdSegmentChain end, long step)
      Calculates the gap between this chain's sequence and another's max ID.
      Parameters:
      end - the end chain
      step - the step size
      Returns:
      the number of IDs between sequences

    • newRoot

      public static IdSegmentChain newRoot(boolean allowReset)
      Creates a new root chain.
      Parameters:
      allowReset - whether reset is allowed
      Returns:
      a new root chain

    • getFetchTime

      public long getFetchTime()
      Description copied from interface: IdSegment
      Get the time when this segment was fetched.

      This timestamp is used for expiration calculations and represents when the segment was allocated from the central distributor.

      Unit: TimeUnit.SECONDS

      Specified by:
      getFetchTime in interface IdSegment
      Returns:
      The fetch time in seconds

    • getTtl

      public long getTtl()
      Description copied from interface: IdSegment
      Get the time-to-live for this segment.

      This determines how long the segment remains valid before it should be refreshed or replaced. A value of IdSegment.TIME_TO_LIVE_FOREVER indicates the segment never expires.

      Unit: TimeUnit.SECONDS

      Specified by:
      getTtl in interface IdSegment
      Returns:
      The time-to-live in seconds

    • getMaxId

      public long getMaxId()
      Description copied from interface: IdSegment
      Get the maximum ID in this segment.

      This is the upper bound of the ID range allocated to this segment. IDs generated from this segment will not exceed this value.

      Specified by:
      getMaxId in interface IdSegment
      Returns:
      The maximum ID in this segment

    • getOffset

      public long getOffset()
      Description copied from interface: IdSegment
      Get the offset (starting ID) of this segment.

      This is the lower bound of the ID range allocated to this segment. The first ID generated from this segment will typically be this value or slightly higher depending on the step size.

      Specified by:
      getOffset in interface IdSegment
      Returns:
      The offset of this segment

    • getSequence

      public long getSequence()
      Description copied from interface: IdSegment
      Get the current sequence number within this segment.

      This represents the next ID that will be allocated from this segment, or IdSegment.SEQUENCE_OVERFLOW if the segment has been exhausted.

      Specified by:
      getSequence in interface IdSegment
      Returns:
      The current sequence number

    • getStep

      public long getStep()
      Description copied from interface: IdSegment
      Get the step size for ID allocation.

      This determines how much the sequence number is incremented each time an ID is allocated. A step size of 1 allocates consecutive IDs, while larger step sizes can be used for sharding or other purposes.

      Specified by:
      getStep in interface IdSegment
      Returns:
      The step size for ID allocation

    • incrementAndGet

      public long incrementAndGet()
      Description copied from interface: IdSegment
      Atomically increment the sequence and return the new value.

      This method provides thread-safe allocation of the next ID from this segment. If the segment has been exhausted, it returns IdSegment.SEQUENCE_OVERFLOW.

      Specified by:
      incrementAndGet in interface IdSegment
      Returns:
      The next allocated ID, or IdSegment.SEQUENCE_OVERFLOW if exhausted

    • toString

      public String toString()
      Overrides:
      toString in class Object