README
¶
Flaki - Das kleine Generator 
Flaki is an unique ID generator inspired by Snowflake. It generates 64-bit unique IDs of type uint64 or string. The string IDs are simply the uint64 IDs represented as a string. Each ID is composed of
| 42-bit timestamp | 2-bit node ID | 5-bit component ID | 15-bit sequence |
|---|
The node ID and component ID are configured during the creation of the Flaki generator and do not change afterwards. The 42-bit timestamp is the number of millisecond elapsed from the start epoch. If several IDs are requested during the same millisecond, the sequence is incremented to obtain a unique ID every time. There is a mechanism that does not let the sequence overflow. If it happen, we wait till the next millisecond to return new IDs. This ensure the IDs uniqueness.
Usage
Create a new Flaki generator.
var flaki, err = New()
if err != nil {
// handle error
}
You can configure the Flaki's node ID, component ID and start epoch by submitting options to the call to New. New takes a variable number of options as parameter. If no option is given, the following default parameters are used:
- 0 for the node ID
- 0 for the component ID
- 01.01.2017 for the epoch
If you want to modify any of the default parameter, use the corresponding option in the call to New.
- ComponentID(uint64)
- NodeID(uint64)
- StartEpoch(time.Time)
var cID uint64 = ...
var nID uint64 = ..
var e time.Time = ...
var flaki, err = New(ComponentID(cID), NodeID(nID), StartEpoch(e))
if err != nil {
// handle error
}
To obtain IDs, flaki provides two methods: NextID() (uint64, error), NextIDString() (string, error), NextValidID() uint64 and NextValidIDString() string.
var id uint64
var err error
id, err = flaki.NextID()
id = flaki.NextValidID()
var idStr string
idStr, err = flaki.NextIDString()
idStr = flaki.NextValidIDString()
NextID returns either a unique ID or an error if the clock moves backward.
Unlike NextID, NexValidID always returns a valid ID, never an error. If the clock moves backward, it wait until the situation goes back to normal before returning new IDs.
Limitations
Flaki won't generate valid IDs after the year 2262.
This is due to the fact that the UnixNano function of the package time
returns undefined result if the Unix time in nanoseconds cannot be represented by an int64, i.e.
a date before the year 1678 or after 2262.
Documentation
¶
Overview ¶
Package flaki provides the implementation of Flaki - Das kleine Generator. Flaki is a distributed unique IDs generator inspired by Snowflake (https://github.com/twitter/snowflake). It returns unique IDs of type uint64 or string. The ID is composed of: 5-bit component ID, 2-bit node ID, 15-bit sequence number, and 42-bit time's milliseconds since the epoch. Unique IDs will be generated until 139 years 4 months and a few days after the epoch. After that, there will be an overflow and the newly generated IDs won't be unique anymore.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Flaki ¶
type Flaki struct {
// contains filtered or unexported fields
}
Flaki is the unique ID generator.
func New ¶
New returns a new unique IDs generator.
If you do not specify options, Flaki will use the following default parameters: 0 for the node ID, 0 for the component ID, and 01.01.2017 as start epoch.
To change the default settings, use the options in the call to New, i.e. New(logger, ComponentID(1), NodeID(2), StartEpoch(startEpoch))
func (*Flaki) NextID ¶
NextID returns a new unique ID, or an error if the clock moves backward.
Example ¶
This example demonstrates the use of NextID to obtain a unique uint64 ID.
flaki, err := New()
if err != nil {
log.Fatalf("could not create flaki generator: %v", err)
}
id, err := flaki.NextID()
if err != nil {
log.Fatalf("could not generate ID: %v", err)
}
fmt.Printf("Unique ID: %d", id)
Output:
func (*Flaki) NextIDString ¶
NextIDString returns the NextID as a string.
Example ¶
This example demonstrates the use of NextIDString to obtain a unique string ID.
flaki, err := New()
if err != nil {
log.Fatalf("could not create flaki generator: %v", err)
}
id, err := flaki.NextIDString()
if err != nil {
log.Fatalf("could not generate ID: %v", err)
}
fmt.Printf("Unique ID: %s", id)
Output:
func (*Flaki) NextValidID ¶
NextValidID always returns a new unique ID, it never returns an error. If the clock moves backward, it waits until the situation goes back to normal and then returns the valid ID.
Example ¶
This example demonstrates the use of NextID to obtain a unique uint64 ID.
flaki, err := New()
if err != nil {
log.Fatalf("could not create flaki generator: %v", err)
}
id := flaki.NextValidID()
if err != nil {
log.Fatalf("could not generate ID: %v", err)
}
fmt.Printf("Unique ID: %d", id)
Output:
func (*Flaki) NextValidIDString ¶
NextValidIDString returns the NextValidID as a string.
Example ¶
This example demonstrates the use of NextIDString to obtain a unique string ID.
flaki, err := New()
if err != nil {
log.Fatalf("could not create flaki generator: %v", err)
}
id := flaki.NextValidIDString()
if err != nil {
log.Fatalf("could not generate ID: %v", err)
}
fmt.Printf("Unique ID: %s", id)
Output:
type Option ¶
Option type is use to configure the Flaki generator. It takes one argument: the Flaki we are operating on.
func ComponentID ¶
ComponentID is the option used to set the component ID.
func StartEpoch ¶
StartEpoch is the option used to set the epoch.
Source Files