Highly scalable, single/multi node, predictable and incremental 64 bits (8 bytes) unique id generator with zero allocation magic. It is using snowflake idea with flexible options.
If you are interested in 16 bytes ids with optional sequencers, checkout the monoton package.
Via go packages:
go get github.com/mustafaturan/monoflake
The method names and arities/args are stable now. No change should be expected
on the package for the version 1.x.x except any bug fixes.
Create a new package like below, and then call Next() method:
package uniqid
// Import packages
import (
"github.com/mustafaturan/monoflake"
)
var m *monoflake.MonoFlake
// On init configure the monoflake
func init() {
m = newIDGenerator()
}
func newIDGenerator() *monoflake.MonoFlake {
// Fetch your node id from a config server or generate from MAC/IP address
node := uint16(0)
// If we want to init the time with 2024-06-01 00:00:00 UTC (min allowed)
epoch := time.Unix(1717200000, 0)
// Configure monoflake with a node and epoch
m, err = monoflake.New(node, monoflake.WithEpoch(epoch))
if err != nil{
panic(err)
}
return m
}
func Generate() int64 {
return m.Next().Int64()
}
func GeneateBytes() []byte {
return m.Next().Bytes()
}
func GeneateString() string {
return m.Next().String()
}In any other package generate the ids like below:
import (
"fmt"
"uniqid" // your local uniqid package from your project
)
func main() {
for i := 0; i < 100; i++ {
fmt.Println(uniqid.Generate())
}
}package main
// Import packages
import (
"fmt"
"github.com/mustafaturan/monoflake"
)
func NewIDGenerator() *monoflake.MonoFlake {
// Fetch your node id from a config server or generate from MAC/IP address
node := uint16(0)
// Configure monoflake with a sequencer and the node
m, err := monoflake.New(node)
if err != nil{
panic(err)
}
return m
}
func main() {
g := NewIDGenerator()
for i := 0; i < 100; i++ {
fmt.Println(g.Next())
}
}# monoflake.WithNodeBits sets the max node bits to 8 which modules the node id with 256 limits the val to [0, 256).
# maximum node bits allowed is 2^13, you can go up to 13 by setting it
# You can set node id between 8 to 13 bits inclusive, the rest will be automatically used for sequencer.
monoflake.New(node, monoflake.WithNodeBits(13), ...)
# monoflake.WithEpoch sets the epoch start time, minimum epoch value is 2024-06-01 00:00:00 UTC.
epoch := time.Unix(...)
monoflake.New(node, monoflake.WithEpoch(epoch), ...)
Default bit allocations
[1 bit(reserved) | 40 bits (time in milliseconds) | 13 bits (sequencer) | 10 bits (node id)]
[ [0, 1) | up to 34 years in milliseconds | [0, 8192) | [0, 1024) ]
When the sequencer reaches to maximum value in the same milliseconds then milliseconds increased automatically and the sequence set to 0.
Thread safety achieved with mutex locks.
The monoflake package provides sequences based on the monotonic time which
represents the absolute elapsed wall-clock time since some arbitrary, fixed
point in the past. It isn't affected by changes in the system time-of-day clock.
Epoch time value opens space for time value by subtracting the given value from the time sequence.
It comes with String() method which encodes the ids into base62 as string and allows padded with zeros to 11 bytes.
Bytes() method allows converting the id directly into static 11 bytes.
The monoflake package can be used on single/multiple nodes without the need for
machine coordination. It uses configured node identifier to generate ids by
attaching the node identifier to the end of the sequences.
Zero allocation magic with blazing fast results.
Command:
go test -benchtime 10000000x -benchmem -run=^$ -bench=. github.com/mustafaturan/monoflake
Results:
goos: darwin
goarch: arm64
pkg: github.com/mustafaturan/monoflake
cpu: Apple M2
BenchmarkNext-8 10000000 49.09 ns/op 0 B/op 0 allocs/op
BenchmarkNextWithEpoch-8 10000000 29.28 ns/op 0 B/op 0 allocs/op
BenchmarkNextCompare-8 10000000 93.40 ns/op 0 B/op 0 allocs/op
BenchmarkNextBase62-8 10000000 54.45 ns/op 0 B/op 0 allocs/op
BenchmarkNextBase62WithEpoch-8 10000000 33.21 ns/op 0 B/op 0 allocs/op
BenchmarkNextBytes-8 10000000 52.82 ns/op 0 B/op 0 allocs/op
BenchmarkNextBytesWithEpoch-8 10000000 31.72 ns/op 0 B/op 0 allocs/op
BenchmarkNextBigEndianBytes-8 10000000 48.40 ns/op 0 B/op 0 allocs/op
BenchmarkNextBigEndianBytesWithEpoch-8 10000000 31.73 ns/op 0 B/op 0 allocs/op
PASS
ok github.com/mustafaturan/monoflake 4.427s
All contributors should follow Contributing Guidelines before creating pull requests.
Apache License 2.0
Copyright (c) 2024 Mustafa Turan
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.