README
¶
zflake
Package zflake is a distributed unique ID generator inspired by
Twitter's Snowflake.
The zflake was created mainly to be able to generate great number of unique
int64 IDs in bursts. In fact the number of distributed generators
was less important than the ability to create a lot of IDs in a short time.
The zflake bit assignment in int64 is as follows:
1 bit (most significant) reserved
38 bits for time in units of 10 msec
13 bits for a sequence number
12 bits for a generator ID (GID)
zflake properties:
- The lifetime of ~87 years since the start of
zflakeepoch. - Can generate at most 2^13 (8192) IDs per 10ms for each generator ID.
- 2^12 (4096) generators.
- Ability to generate Base62 string representations of int64 IDs.
Installation
go get github.com/rzajac/zflake
Usage
To create zflake generator with default configuration (GID 0, epoch starting
at 2020-01-01T00:00:00Z) call constructor function without options:
func NewGen() *Gen
You can customize zflake using constructor option functions:
func GID(gid byte) // Set generator ID.
func Epoch(epoch time.Time) // Set epoch.
Example:
gen := zflake.NewGen(zflake.GID(42), zflake.Epoch(time.Date(2021, 1, 1, 0, 0, 0, 0, time.UTC)))
fid := gen.NextFID() // Generate unique int64 ID.
sid := gen.NextSID() // Generate unique Base62 encoded ID.
By default zflake uses 2020-01-01T00:00:00Z as an epoch.
When 39 bit space for time buckets (10ms) runs out NextFID and NextSID
will panic.
Decode zflake ID
parts := zflake.DecodeFID(134362890512629802)
fmt.Println(parts) // map[fid:134362890512629802 gid:42 msb:0 seq:0 tim:4004326180]
Benchmark
Benchmark_zflake
Benchmark_zflake_fid-12 1973349 608 ns/op 0 B/op 0 allocs/op
Benchmark_zflake_sid-12 1967682 610 ns/op 16 B/op 1 allocs/op
License
BSD-2-Clause, see LICENSE for details.
Documentation
¶
Overview ¶
Package zflake implements distributed unique ID generator inspired by Twitter's Snowflake.
A zflake ID is composed of
1 bit (most significant) reserved 38 bits for time in units of 10 msec 13 bits for a sequence number 12 bits for a generator ID (GID)
Above bit assigment dictate following zflake properties:
- The lifetime of ~87 years since the start of `zflake` epoch. - Can generate at most 2^13 (8192) IDs per 10ms for each generator ID. - 2^12 (4096) generators. - Ability to generate Base62 string representations of int64 IDs.
Index ¶
Constants ¶
const ( // BucketLen defines the length of zflake time bucket in nanoseconds. BucketLen = int64(10 * time.Millisecond) // BitLenTim number of bits assigned to time buckets. BitLenTim = 38 // BitLenSeq number of bits assigned to sequence number. BitLenSeq = 13 // BitLenGID number of bits assigned to generator ID (GID). BitLenGID = 63 - BitLenTim - BitLenSeq // DefaultEpoch represents default zflake epoch 2020-01-01T00:00:00Z as // nanoseconds since Unix epoch (1970-01-01T00:00:00Z). DefaultEpoch int64 = 1577836800000000000 // DefaultGID represents default generator ID. DefaultGID uint16 = 0 )
Variables ¶
This section is empty.
Functions ¶
func Clock ¶
Clock is Flake constructor option injecting custom clock.
This option is mostly used to test zflake behaviour.
func DecodeSID ¶ added in v0.2.0
DecodeSID decodes Base62 representation of the zflake ID back to int64.
Types ¶
type Gen ¶
type Gen struct {
// contains filtered or unexported fields
}
Gen represents distributed unique ID generator.
func NewGen ¶
NewGen returns a new generator with default configuration. NewGen returns nil if epoch is set ahead of the current time.
Source Files
Directories