README
¶
Flake
A fork from https://github.com/sony/sonyflake
Flake is a distributed unique ID generator inspired by Twitter's Snowflake.
Differences from the original Sonyflake:
- panic instead of returning errors, as these errors are mostly non actionable and should never occur:
NextID() uint64 - time units are 1 msec instead of 10
- 16 bits for a machine id,
- 6 bits for a sequence number (64 per 1 ms)
- 41 bits for time in units of 1 msec
As a result, Flake has the following advantages and disadvantages:
- The lifetime (69 years) is similar to that of Snowflake (69 years)
- It can work on more distributed machines (2^16) than Snowflake (2^10)
- It can generate 2^6 IDs per 1 msec at most in a single machine/thread
Installation
go get github.com/effective-security/xdb/pkg/flake
Usage
The function NewIDGenerator creates a new IDGenerator instance.
func NewIDGenerator(st Settings) IDGenerator
You can configure Flake by the struct Settings:
type Settings struct {
StartTime time.Time
MachineID func() (uint16, error)
CheckMachineID func(uint16) bool
}
-
StartTime is the time since which the Flake time is defined as the elapsed time. If StartTime is 0, the start time of the Sonyflake is set to "2021-01-01 00:00:00 +0000 UTC". If StartTime is ahead of the current time, Flake is not created.
-
MachineID returns the unique ID of the Flake instance. If MachineID returns an error, Flake will panic. If MachineID is nil, default MachineID is used. Default MachineID returns the lower 8 bits of the private IP address.
-
CheckMachineID validates the uniqueness of the machine ID. If CheckMachineID returns false, Flake will panic. If CheckMachineID is nil, no validation is done.
In order to get a new unique ID, you just have to call the method NextID.
func (sf *Flake) NextID() uint64
License
The MIT License (MIT)
Documentation
¶
Overview ¶
Package flake implements Snowflake, a distributed unique ID generator inspired by Twitter's Snowflake.
A Flake ID is composed of
39 bits for time in units of 10 msec 8 bits for a sequence number 16 bits for a machine id
Index ¶
Constants ¶
const ( BitLenMachineID = 16 // bit length of machine id, 2^16 BitLenSequence = 6 // bit length of sequence number BitLenTime = 63 - BitLenMachineID - BitLenSequence // bit length of time MaskSequence16 = uint16(1<<BitLenSequence - 1) MaskSequence = uint64(MaskSequence16) << BitLenMachineID MaskMachineID = uint64(1<<BitLenMachineID - 1) FlakeTimeUnit = int64(1 * time.Millisecond) )
These constants are the bit lengths of Flake ID parts.
Variables ¶
var DefaultStartTime = time.Date(2021, 1, 1, 0, 0, 0, 0, time.UTC).UTC()
DefaultStartTime provides default start time for the Flake
var NowFunc = time.Now
NowFunc returns the current time; it's overridden in tests.
Functions ¶
func FirstID ¶
func FirstID(g IDGenerator) uint64
FirstID returns the first ID generated by the generator.
func IDTime ¶
func IDTime(g IDGenerator, id uint64) time.Time
IDTime returns the timestamp of the flake ID.
func IsTestRun ¶
func IsTestRun() bool
IsTestRun returns true if the program is running in the test.
func LastID ¶
func LastID(g IDGenerator) uint64
LastID returns the last ID generated by the generator.
Types ¶
type Flake ¶
type Flake struct {
// contains filtered or unexported fields
}
Flake is a distributed unique ID generator.
type IDGenerator ¶
type IDGenerator interface {
// NextID generates a next unique ID.
NextID() uint64
}
IDGenerator defines an interface to generate unique ID accross the cluster
var DefaultIDGenerator IDGenerator
DefaultIDGenerator for the app
func NewIDGenerator ¶
func NewIDGenerator(st Settings) IDGenerator
NewIDGenerator returns a new Flake configured with the given Settings. NewIDGenerator panics in the following cases: - Settings.StartTime is ahead of the current time. - Settings.MachineID returns an error. - Settings.CheckMachineID returns false.
type Settings ¶
type Settings struct {
StartTime time.Time
MachineID func() (uint16, error)
CheckMachineID func(uint16) bool
}
Settings configures Flake:
StartTime is the time since which the Flake time is defined as the elapsed time. If StartTime is 0, the start time of the Flake is set to "2021-01-01 00:00:00 +0000 UTC". If StartTime is ahead of the current time, Flake is not created.
MachineID returns the unique ID of the Flake instance. If MachineID returns an error, Flake is not created. If MachineID is nil, default MachineID is used. Default MachineID returns the lower 8 bits of the private IP address,
CheckMachineID validates the uniqueness of the machine ID. If CheckMachineID returns false, Flake is not created. If CheckMachineID is nil, no validation is done.
Source Files