Package org.agrona.concurrent

Class SnowflakeIdGenerator

java.lang.Object
org.agrona.concurrent.SnowflakeIdGenerator
All Implemented Interfaces:
IdGenerator
public final class SnowflakeIdGenerator extends Object implements IdGenerator
Generate unique identifiers based on the Twitter Snowflake algorithm.

This implementation is lock-less resulting in greater throughput plus less contention and latency jitter.

Note: ntpd, or alternative clock source, should be setup correctly to ensure the clock does not go backwards.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    EPOCH_BITS
    Number of bits used for the timestamp giving 69 years from timestampOffsetMs().
    static final int
    MAX_NODE_ID_AND_SEQUENCE_BITS
    Total number of bits used to represent the distributed node and the sequence within a millisecond.
    static final int
    NODE_ID_BITS_DEFAULT
    Default number of bits used to represent the distributed node or application which is 10 bits allowing for 1024 nodes (0-1023).
    static final int
    SEQUENCE_BITS_DEFAULT
    Default number of bits used to represent the sequence within a millisecond which is 12 bits supporting 4,096,000 ids per-second per-node.
    static final int
    UNUSED_BITS
    High order 2's compliment bit which is unused.

  • Constructor Summary

    Constructors
    Constructor
    Description
    SnowflakeIdGenerator(int nodeIdBits, int sequenceBits, long nodeId, long timestampOffsetMs, EpochClock clock)
    Construct a new Snowflake id generator for a given node with a provided offset and EpochClock.
    SnowflakeIdGenerator(long nodeId)
    Construct a new Snowflake id generator for a given node with a 0 offset from 1 Jan 1970 UTC and use SystemEpochClock.INSTANCE with NODE_ID_BITS_DEFAULT node ID bits and SEQUENCE_BITS_DEFAULT sequence bits.

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    maxNodeId()
    The max node identity value possible given the configured number of node ID bits.
    long
    maxSequence()
    The max sequence value possible given the configured number of sequence bits.
    long
    nextId()
    Generate the next id in sequence.
    long
    nodeId()
    Node identity which scopes the id generation.
    long
    timestampOffsetMs()
    Offset in milliseconds from Epoch of 1 Jan 1970 UTC which is subtracted to give 69 years of ids.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • UNUSED_BITS

      public static final int UNUSED_BITS
      High order 2's compliment bit which is unused.
      See Also:

    • EPOCH_BITS

      public static final int EPOCH_BITS
      Number of bits used for the timestamp giving 69 years from timestampOffsetMs().
      See Also:

    • MAX_NODE_ID_AND_SEQUENCE_BITS

      public static final int MAX_NODE_ID_AND_SEQUENCE_BITS
      Total number of bits used to represent the distributed node and the sequence within a millisecond.
      See Also:

    • NODE_ID_BITS_DEFAULT

      public static final int NODE_ID_BITS_DEFAULT
      Default number of bits used to represent the distributed node or application which is 10 bits allowing for 1024 nodes (0-1023).
      See Also:

    • SEQUENCE_BITS_DEFAULT

      public static final int SEQUENCE_BITS_DEFAULT
      Default number of bits used to represent the sequence within a millisecond which is 12 bits supporting 4,096,000 ids per-second per-node.
      See Also:

  • Constructor Details

    • SnowflakeIdGenerator

      public SnowflakeIdGenerator(int nodeIdBits, int sequenceBits, long nodeId, long timestampOffsetMs, EpochClock clock)
      Construct a new Snowflake id generator for a given node with a provided offset and EpochClock.
      Parameters:
      nodeIdBits - number of bits used to represent the distributed node or application.
      sequenceBits - number of bits used to represent the sequence within a millisecond.
      nodeId - for the node generating ids.
      timestampOffsetMs - to adjust the base offset from 1 Jan 1970 UTC to extend the 69-year range.
      clock - to provide timestamps.

    • SnowflakeIdGenerator

      public SnowflakeIdGenerator(long nodeId)
      Construct a new Snowflake id generator for a given node with a 0 offset from 1 Jan 1970 UTC and use SystemEpochClock.INSTANCE with NODE_ID_BITS_DEFAULT node ID bits and SEQUENCE_BITS_DEFAULT sequence bits.
      Parameters:
      nodeId - for the node generating ids.

  • Method Details

    • nodeId

      public long nodeId()
      Node identity which scopes the id generation. This is limited to maxNodeId().
      Returns:
      the node identity which scopes the id generation.

    • timestampOffsetMs

      public long timestampOffsetMs()
      Offset in milliseconds from Epoch of 1 Jan 1970 UTC which is subtracted to give 69 years of ids.

      To offset from 1 Jan 2015 UTC then 1420070400000 can be used.

      Returns:
      offset in milliseconds from Epoch of 1 Jan 1970 UTC which is subtracted to give 69 years of ids.

    • maxNodeId

      public long maxNodeId()
      The max node identity value possible given the configured number of node ID bits.
      Returns:
      max node identity value.

    • maxSequence

      public long maxSequence()
      The max sequence value possible given the configured number of sequence bits.
      Returns:
      max sequence value.

    • nextId

      public long nextId()
      Generate the next id in sequence. If maxSequence() is reached within the same millisecond then this implementation will busy spin until the next millisecond using Thread.onSpinWait() and checking for Thread.isInterrupted().
      Specified by:
      nextId in interface IdGenerator
      Returns:
      the next unique id for this node.