Package me.ahoo.cosid.segment

Interface IdSegment

All Superinterfaces:
Comparable<IdSegment>, Grouped
All Known Implementing Classes:
DefaultIdSegment, IdSegmentChain, MergedIdSegment
@ThreadSafe public interface IdSegment extends Comparable<IdSegment>, Grouped
ID segment representing a contiguous block of IDs allocated for generation.

An ID segment is a range of IDs that has been allocated to a specific generator instance for local generation. It contains metadata about the segment's state and provides thread-safe ID allocation within the segment.

Key concepts:

  • Offset: The starting ID of the segment
  • Max ID: The ending ID of the segment
  • Sequence: The next available ID within the segment
  • Step: The increment size for ID allocation

Segments implement expiration and overflow detection to ensure proper lifecycle management and prevent ID conflicts.

SegmentId

Implementations of this interface are expected to be thread-safe and can be used concurrently across multiple threads.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final long
    SEQUENCE_OVERFLOW
    Special sequence value indicating overflow.
    static final long
    TIME_TO_LIVE_FOREVER
    Special TTL value indicating the segment never expires.

  • Method Summary

    Modifier and Type
    Method
    Description
    default int
    compareTo(IdSegment other)
    Compare this segment to another segment based on offset.
    default void
    ensureNextIdSegment(IdSegment nextIdSegment)
    Ensure that the next segment is valid relative to this segment.
    long
    getFetchTime()
    Get the time when this segment was fetched.
    long
    getMaxId()
    Get the maximum ID in this segment.
    long
    getOffset()
    Get the offset (starting ID) of this segment.
    long
    getSequence()
    Get the current sequence number within this segment.
    long
    getStep()
    Get the step size for ID allocation.
    default long
    getTtl()
    Get the time-to-live for this segment.
    long
    incrementAndGet()
    Atomically increment the sequence and return the new value.
    default boolean
    isAvailable()
    Check if this segment is available for ID generation.
    default boolean
    isExpired()
    Check if this segment has expired.
    default boolean
    isOverflow()
    Check if this segment has overflowed.
    default boolean
    isOverflow(long nextSeq)
    Check if the specified sequence number represents an overflow.

    Methods inherited from interface me.ahoo.cosid.segment.grouped.Grouped

    group

  • Field Details

    • SEQUENCE_OVERFLOW

      static final long SEQUENCE_OVERFLOW
      Special sequence value indicating overflow.

      This constant is used to signal that a segment has been exhausted and no more IDs can be allocated from it.

      See Also:

    • TIME_TO_LIVE_FOREVER

      static final long TIME_TO_LIVE_FOREVER
      Special TTL value indicating the segment never expires.

      This constant is used for segments that should remain valid indefinitely, avoiding the need for expiration checks.

      See Also:

  • Method Details

    • getFetchTime

      long getFetchTime()
      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

      Returns:
      The fetch time in seconds

    • getMaxId

      long getMaxId()
      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.

      Returns:
      The maximum ID in this segment

    • getOffset

      long getOffset()
      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.

      Returns:
      The offset of this segment

    • getSequence

      long getSequence()
      Get the current sequence number within this segment.

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

      Returns:
      The current sequence number

    • getStep

      long getStep()
      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.

      Returns:
      The step size for ID allocation

    • getTtl

      default long getTtl()
      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 TIME_TO_LIVE_FOREVER indicates the segment never expires.

      Unit: TimeUnit.SECONDS

      Returns:
      The time-to-live in seconds

    • isExpired

      default boolean isExpired()
      Check if this segment has expired.

      An expired segment should no longer be used for ID generation and should be refreshed or replaced with a new segment.

      Segments with TIME_TO_LIVE_FOREVER never expire, avoiding the performance cost of clock checks for permanent segments.

      Returns:
      true if the segment has expired, false otherwise

    • isOverflow

      default boolean isOverflow()
      Check if this segment has overflowed.

      An overflowed segment has exhausted its ID range and cannot allocate any more IDs. A new segment should be requested when this occurs.

      Returns:
      true if the segment has overflowed, false otherwise

    • isOverflow

      default boolean isOverflow(long nextSeq)
      Check if the specified sequence number represents an overflow.

      This method checks if a specific sequence number indicates that the segment has been exhausted, either by matching the overflow constant or by exceeding the maximum ID.

      Parameters:
      nextSeq - The sequence number to check
      Returns:
      true if the sequence number indicates overflow, false otherwise

    • isAvailable

      default boolean isAvailable()
      Check if this segment is available for ID generation.

      A segment is available if it has not expired and has not overflowed. Available segments can be used for generating new IDs.

      Returns:
      true if the segment is available, false otherwise

    • incrementAndGet

      long incrementAndGet()
      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 SEQUENCE_OVERFLOW.

      Returns:
      The next allocated ID, or SEQUENCE_OVERFLOW if exhausted

    • compareTo

      default int compareTo(IdSegment other)
      Compare this segment to another segment based on offset.

      Segments are ordered by their offset values, which represents their position in the global ID space. This ordering is used to ensure proper sequence of segments and detect expired segments.

      Specified by:
      compareTo in interface Comparable<IdSegment>
      Parameters:
      other - The segment to compare to
      Returns:
      A negative integer, zero, or a positive integer as this segment's offset is less than, equal to, or greater than the specified segment's offset

    • ensureNextIdSegment

      default void ensureNextIdSegment(IdSegment nextIdSegment) throws NextIdSegmentExpiredException
      Ensure that the next segment is valid relative to this segment.

      This method validates that the next segment has a higher offset than this segment, preventing the use of expired or duplicate segments that could cause ID conflicts.

      Parameters:
      nextIdSegment - The next segment to validate
      Throws:
      NextIdSegmentExpiredException - if the next segment is invalid