Package com.hazelcast.flakeidgen

Interface FlakeIdGenerator

All Superinterfaces:
DistributedObject
public interface FlakeIdGenerator extends DistributedObject
A cluster-wide unique ID generator. Generated IDs are long primitive values and are k-ordered (roughly ordered). IDs are in the range from 0 to Long.MAX_VALUE (they can be negative in a special case if you set the epoch start to a future instant in the Flake ID Generator configuration on the member side).

The IDs contain a timestamp component and a node ID component, which is assigned when the member joins the cluster. This allows the IDs to be ordered and unique without any coordination between members, which makes the generator safe even in split-brain scenario.

The layout of the generate IDs is as follows (starting from most significant bits):

  • timestamp bits (41 by default)
  • sequence bits (6 by default)
  • node ID bits (16 by default)
You can configure the number of sequence bits and of node ID bits on the member side. Timestamp bits are assigned in a way that all three components add to 63. It is an error to assign sequence and node ID bits that exceed 63.

You can tweak bits assigned to each component according to your use case using Flake ID Generator configuration on the member side:

Timestamp bits

The number of bits assigned to this component determines the lifespan of the generator. For example the 41 bits assigned by default allow the generator to generate IDs during about 70 years (or 140 years, if you can tolerate negative IDs). Along with epoch start, which is at the beginning of 2018 by default and is also configurable, you can determine when the generator will run out. By default, it runs out slightly before the end of 2088.

Sequence bits

The number of bits assigned to the sequence component determines how many IDs can be generated per millisecond. The default value of 6, for example, allows to generate 64 IDs per millisecond (2^6). That is 64000 IDs per second. If you don't need this many IDs, you can reduce the sequence bits and allocate more for node ID or timestamp.

If more than 64 IDs are requested in a single millisecond, IDs will gracefully overflow to the next millisecond and uniqueness is guaranteed in this case. The implementation does not allow overflowing by more than certain number of seconds, 15 by default; if IDs are requested at a higher rate, the call will block. Note, however, that clients might be able to generate faster because each call goes to a different (random) member and the 64 IDs/ms limit is for a single member.

Node ID bits

This component determines mostly how many changes in the cluster we can tolerate. Default node ID component has 16 bits. Members with member list join version higher than 2^16 won't be able to generate IDs, but functionality will be preserved by forwarding to another member. It is possible to generate IDs on any member or client as long as there is at least one member with join version smaller than 2^16 in the cluster. The only remedy is to restart the cluster: nodeId will be assigned from zero again. Uniqueness after the restart will be preserved thanks to the timestamp component.

Since:
3.10

  • Method Details

    • newId

      long newId()
      Generates and returns a cluster-wide unique ID.

      Operation on a member is always local, if the member has valid node ID, otherwise it's remote. On client, this method goes to a random member and gets a batch of IDs, which will then be returned locally for limited time. The pre-fetch size and the validity time can be configured for each client and member, see member config and see ClientConfig.addFlakeIdGeneratorConfig() for client config.

      Note: Values returned from this method may be not strictly ordered.

      Returns:
      new cluster-wide unique ID
      Throws:
      HazelcastException - thrown if:
      • node ID for all members in the cluster is out of valid range. See "Node ID overflow" in class documentation for more details.
      • if the lifespan of the generator is over