uid64

README

UID64

This uid64 package generates 64bit unique identifier, which is Sortable, Clock and Random number-based. Especially, UID can be DB's primary key as long-int(int64) directly.

This package is greatly inspired by go-scru128 and google/uuid. ( But it does NOT follow any RFC specification. )

If you like this package's feature but need more powerful facilities, consider to use go-scru128. It is awesome write up about UUID.

Usage

// Create a NewGenerator with a id that must be in rage 0~3.
g, err := NewGenerator(0)
handle(err)

// Call Gen() for thread-safe generation.
id1, err := g.Gen()
// Call GenDanger() for NOT thread-safe generation.
id2, err := g.GenDanger()

instance := Instance{id1, "test"}

// UID implements sql.Valuer, 
// it can be inserted to sql DB directly, 
// and can be ordered primary key as Long-Int(64bit).
err := db.Save(instance) 
handle(err)

// UID implements sql.Scanner,
// it also can be loaded from DB directly.

Features

Cases this repository is for

• Need Sortable, Clock, Random Unique Indentifier
• Need DB Insertion friendly ID ( orederd, native Long-Int)
• Want short string representation (Base36)
• Want Thread-safe, Unieque ID over all generators (up to 4)

Cases it's NOT for

• Will generate more than 128 per a milli-sec.
• Want more than 4 distributed generators.
• Want to follow RFC.

Benchmarks

With my laptop comparing ID-generation to google's UUID library, this repository is

• more than 5x faster
• 16x smaller allocation size
• same allocation count (1 times)

goos: linux
goarch: amd64
pkg: github.com/hitoshi44/go-uid64
cpu: AMD Ryzen 5 3500U with Radeon Vega Mobile Gfx  
BenchmarkGoogleUUIDNew-8   	 1963202	       621.9 ns/op	      16 B/op	       1 allocs/op
PASS
ok  	github.com/hitoshi44/go-uid64	1.813s

goos: linux
goarch: amd64
pkg: github.com/hitoshi44/go-uid64
cpu: AMD Ryzen 5 3500U with Radeon Vega Mobile Gfx  
BenchmarkUID64Gen-8   	 8579986	       122.7 ns/op	       1 B/op	       1 allocs/op
PASS
ok  	github.com/hitoshi44/go-uid64	1.206s

Documentation

Index

• Constants
• Variables
• func NewString() (string, error)
• type Generator
  • func NewGenerator(id int) (*Generator, error)
  • func (g *Generator) Gen() (UID, error)
  • func (g *Generator) GenDanger() (UID, error)
  • func (g *Generator) ID() int
  • func (g *Generator) SetID(newid int) error
• type UID
  • func FromInt(i int64) (UID, error)
  • func InitUID(timestamp int64, entropy, generatorID, counter uint8) (UID, error)
  • func New() (UID, error)
  • func Parse(str string) (UID, error)
  • func (uid UID) Counter() uint8
  • func (uid UID) Entropy() uint8
  • func (uid UID) GeneratorID() uint8
  • func (uid *UID) Scan(src interface{}) error
  • func (uid UID) String() string
  • func (uid UID) Timestamp() int64
  • func (uid UID) ToInt() int64
  • func (uid UID) Value() (driver.Value, error)
• type UID64Slice
  • func (x UID64Slice) Len() int
  • func (x UID64Slice) Less(i, j int) bool
  • func (x UID64Slice) Swap(i, j int)

Constants

const MaxTimestamp int64 = 0x8ffffff_ffffffff

Variables

var _, ErrDefaultGeneratorCreation = NewGenerator(0)

Functions

func NewString

func NewString() (string, error)

Types

type Generator

type Generator struct {
	// contains filtered or unexported fields
}

UID64 generator with generator-id

func NewGenerator

func NewGenerator(id int) (*Generator, error)

NewGenerator creates new *Generator with generator-id generator-id is IDentifier of Generator, for ditributed usage. It should be 0 <= id <= 3.

func (*Generator) Gen

func (g *Generator) Gen() (UID, error)

Gen generates new UID, can be called thread safely.

func (*Generator) GenDanger

func (g *Generator) GenDanger() (UID, error)

GenDanger generates new UID without using Mutex. (thus, Not-threadsafe)

func (*Generator) ID

func (g *Generator) ID() int

ID shows generator's id

func (*Generator) SetID

func (g *Generator) SetID(newid int) error

SetID can set generator id to the generator.

type UID

type UID uint64

A UID is a 64 bit (8byte) Unique IDentifier

• 6 byte Unix-Milli Timestamp
• 1 byte Entropy from /dev/urandom
• 1 byte for Counter & GeneratorID (6bit counter & 2bit id)

func FromInt

func FromInt(i int64) (UID, error)

FromInt restores UID from int64. This is used when it select UID from sql DB.

func InitUID

func InitUID(timestamp int64, entropy, generatorID, counter uint8) (UID, error)

Initialize UID from timestamp, random uint8, and genID, and counter. For ordinary case, you don't have to call this method, call Generater.Gen()/GenDanger() instead.

func New

func New() (UID, error)

func Parse

func Parse(str string) (UID, error)

Parse restores UID from Base36 string.

func (UID) Counter

func (uid UID) Counter() uint8

Counter returns 6bit counter field.

func (UID) Entropy

func (uid UID) Entropy() uint8

Entropy returns 8bit random field value.

func (UID) GeneratorID

func (uid UID) GeneratorID() uint8

GeneratorID returns 2bit generator-id field,

func (*UID) Scan

func (uid *UID) Scan(src interface{}) error

func (UID) String

func (uid UID) String() string

String retrun Base36 string representation.

func (UID) Timestamp

func (uid UID) Timestamp() int64

Timestamp returns 48 bit timestamp field value as int64, same to time.Unix().Milli.

func (UID) ToInt

func (uid UID) ToInt() int64

ToInt return int64 (casting from uint64). This is used when it insert UID into sql DB. For ordinary, you don't have to call this method directly.

func (UID) Value

func (uid UID) Value() (driver.Value, error)

Implementation for sql.driver interfaces.

type UID64Slice

type UID64Slice []UID

Implementation sort.Interface for convinience

func (UID64Slice) Len

func (x UID64Slice) Len() int

func (UID64Slice) Less

func (x UID64Slice) Less(i, j int) bool

func (UID64Slice) Swap

func (x UID64Slice) Swap(i, j int)