Skip navigation links

Package com.noctarius.snowcast

Introduction

See: Description

Package com.noctarius.snowcast Description

Introduction

Generating unique IDs in a distributed system is a commonly known hard problem to solve. It either is expensive, involves network traffic or might generate conflicting IDs without recognizing it.

snowcast solves these and some other problems:

snowcast uses 64bit wide data types to generate unique IDs. Where there is no unsigned long in Java, the IDs might be negative but internally are handled as unsigned anyways.

IDs are seen as a combination of 3 distinct sub-identifiers. That said a snowcast sequence ID, schema-wise, looks like the following example:

     | 41 bits                                | 13 bits    | 10 bits |
 

The first part of an ID defines the past milliseconds for a user defined epoch. 41 bits offer about 69 years of milliseconds for any of these epochs.

The second part is defined the logical node ID. It is not always 13 bits but ranges from 3 to 13 bits, depending on user preference. Looking at the example, 13 bits (2^13) offers access to snowcast sequence IDs on 8,192 logical nodes.

The third and last part is a counter. This counter is unique per logical node and millisecond. In this example it is 10 bits (2^10), offering 1,024 unique IDs per millisecond on each of the logical nodes.

The second and third part can be increased or decreased based on user preference. Please see Snowcast.createSequencer(java.lang.String, com.noctarius.snowcast.SnowcastEpoch, int).

Usage of snowcast

Since snowcast is built to work on top of Hazelcast, every snowcast instance is created by passing in a HazelcastInstance to the snowcast factory method.

     HazelcastInstance hazelcastInstance = getHazelcastInstance();
     Snowcast snowcast = SnowcastSystem.snowcast( hazelcastInstance );
 

As learned above the next step is to define a custom epoch which provides our base value for the milliseconds part of the snowcast sequence IDs. This is commonly done using the Java Calendar API:

     Calendar calendar = GregorianCalendar.getInstance();
     calendar.set( 2014, 1, 1, 0, 0, 0 );
     SnowcastEpoch epoch = SnowcastEpoch.byCalendar( calendar );
 

Our epoch is now configured to have the point-zero on midnight of Jan 1st, 2014.

Preparations are done by now. Creating a SnowcastSequencer using the Snowcast factory instance and the epoch, together with a reference name, is now as easy as the following snippet:

     SnowcastSequencer sequencer = snowcast.createSequencer( "sequencerName", epoch );
 

That's it, that is the sequencer. It is immediately available to be used to create IDs.

Generating the IDs is now as easy as calling a method on the given sequencer instance:

     long nextId = sequencer.next();
 

Eventually you either shutdown the Hazelcast cluster or you want to destroy a certain SnowcastSequencer explicitly. This is done by passing the sequencer instance to destroy to the Snowcast instance that created it:

     snowcast.destroySequencer( sequencer );
 

Destroying a sequencer is a cluster operation and will destroy all sequencers referred to by the same name on all nodes. After that point the existing SnowcastSequencer instances are in a destroyed state and cannot be used anymore.

Additional information

For more information please find the github based documentation at https://github.com/noctarius/snowcast.

Skip navigation links

Copyright © 2014-2017. All Rights Reserved.