lab/snowflake
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Document Custom Format options

Browse Source
This commit is contained in:
Bruce Marriner 2018-03-19 21:20:30 +00:00
parent a685984f2e
commit f613937295
1 changed files with 24 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
README.md
View File

@ -24,14 +24,28 @@ By default, the ID format follows the original Twitter snowflake format.
* 12 bits are used to store a sequence number - a range from 0 through 4095. * 12 bits are used to store a sequence number - a range from 0 through 4095.
### Custom Format ### Custom Format
Coming soon.. ish. I plan to find the best way to modify the existing package to allow altering the number of bits used for Node ID's and Sequence Numbers. The goal is to implement this without breaking the API (1/31/18) You can alter the number of bits used for the node id and step number (sequence)
by setting the snowflake.NodeBits and snowflake.StepBits values. Remember that
There is a maximum of 22 bits available that can be shared between these two
values. You do not have to use all 22 bits.
### Custom Epoch
By default this package uses the Twitter Epoch of 1288834974657 or Nov 04 2010 01:42:54.
You can set your own epoch value by setting snowflake.Epoch to a time in milliseconds
to use as the epoch.
### Custom Notes
When setting custom epoch or bit values you need to set them prior to calling
any functions on the snowflake package, including NewNode(). Otherwise the
custom values you set will not be applied correctly.
### How it Works. ### How it Works.
Each time you generate an ID, it works, like this. Each time you generate an ID, it works, like this.
* A timestamp with millisecond precision is stored in the first 41 bits of the ID. * A timestamp with millisecond precision is stored using 41 bits of the ID.
* Then the NodeID is added in subsequent bits. * Then the NodeID is added in subsequent bits.
* Then the Sequence Number is added, starting at 0 and incrementing for each ID generated in the same millisecond. If you generate enough IDs in the same millisecond that the sequence would roll over or overfill then the generate function will pause until the next millisecond. * Then the Sequence Number is added, starting at 0 and incrementing for each ID generated in the same millisecond. If you generate enough IDs in the same millisecond that the sequence would roll over or overfill then the generate function will pause until the next millisecond.
The default Twitter format shown below.
``` ```
+--------------------------------------------------------------------------+ +--------------------------------------------------------------------------+
| 1 Bit Unused | 41 Bit Timestamp | 10 Bit NodeID | 12 Bit Sequence ID | | 1 Bit Unused | 41 Bit Timestamp | 10 Bit NodeID | 12 Bit Sequence ID |
@ -54,8 +68,10 @@ go get github.com/bwmarrin/snowflake
### Usage ### Usage
Import the package into your project then construct a new snowflake Node using a Import the package into your project then construct a new snowflake Node using a
unique node number from 0 to 1023. With the node object call the Generate() unique node number. The default settings permit a node number range from 0 to 1023.
method to generate and return a unique snowflake ID. If you have set a custom NodeBits value, you will need to calculate what your
node number range will be. With the node object call the Generate() method to
generate and return a unique snowflake ID.
Keep in mind that each node you create must have a unique node number, even Keep in mind that each node you create must have a unique node number, even
across multiple servers. If you do not keep node numbers unique the generator across multiple servers. If you do not keep node numbers unique the generator
@ -107,9 +123,10 @@ func main() {
### Performance ### Performance
This snowflake generator should be sufficiently fast enough on most systems to With default settings, this snowflake generator should be sufficiently fast
generate 4096 unique ID's per millisecond. This is the maximum that the enough on most systems to generate 4096 unique ID's per millisecond. This is
snowflake ID format supports. That is, around 243-244 nanoseconds per operation. the maximum that the snowflake ID format supports. That is, around 243-244
nanoseconds per operation.
Since the snowflake generator is single threaded the primary limitation will be Since the snowflake generator is single threaded the primary limitation will be
the maximum speed of a single processor on your system. the maximum speed of a single processor on your system.