fastid

README

FastID -- Snowflake ID generating in Go

FastID is a pluggable unique ID generator in Go.

• Under 64 bits (Long Integer)
• K-Ordered
• Lock-free (using atomic CAS)
• Decentralized

Installation

go get github.com/beinan/fastid

Quick Start

Generate an ID

import (
  "fmt"
  "github.com/beinan/fastid"
)

func ExampleGenInt64ID() {
  id := fastid.CommonConfig.GenInt64ID()
  fmt.Printf("id generated: %v", id)
}

Recommended Settings

• 40 bits timestamp (34 years from 2018-06-01)
• 16 bits machine ID (using lower 16 bits of IP v4 addr as default)
• 7 bits sequence number

With this setting, FastID is able to generate 128(2^7) unique IDs per millisecond (1.048576 millisecond, 2^10 nanosecond).

Customized Settings

See the examples in GoDoc

Benchmarks

Benchmark Settings

• 40 bits timestamp (34 years from 2018-06-01)
• 8 bits machine ID
• 15 bits sequence number

go test -bench=.
goos: linux
goarch: amd64
pkg: github.com/beinan/fastid
BenchmarkGenID-4        20000000                79.7 ns/op
BenchmarkGenIDP-4       20000000               141 ns/op
PASS
ok      github.com/beinan/fastid        4.779s

Documentation

Overview

Package fastid is a distributed, k-ordered unique ID generator.

Under 64 bits (Long Integer)
Lock-free (using atomic CAS)
Decentralized and no coordination needed
Docker friendly

Index

• Constants
• Variables
• type Config
  • func ConstructConfig(timeBits, seqBits, machineBits uint) *Config
  • func ConstructConfigWithMachineID(timeBits, seqBits, machineBits uint, machineID int64) *Config
  • func (c *Config) GenInt64ID() int64
  • func (c *Config) GetSeqFromID(id int64) int64
  • func (c *Config) GetTimeFromID(id int64) int64

Examples

• Config (CustomizedSettings)
• Config (RecommendedSettings)

Constants

const (
	//StartTimeEnvName is the env key for ID generating start time
	StartTimeEnvName = "FASTID_START_TIME"
	//MachineIDEnvName is the env key for machine id
	MachineIDEnvName = "FASTID_MACHINE_ID"
)

Variables

var BenchmarkConfig = ConstructConfig(40, 15, 8)

BenchmarkConfig is a high performance setting for benchmark

40 bits timestamp
15 bits seq
8  bits machine id

var CommonConfig = ConstructConfig(40, 7, 16)

CommonConfig is the recommended setting for most applications

40 bits timestamp
7  bits seq
16 bits machine id

Types

type Config

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

Config maintains the settings for id generating

Example (CustomizedSettings)

config := ConstructConfigWithMachineID(40, 11, 12, 2)
id := config.GenInt64ID()
fmt.Printf("id generated: %v", id)

Example (RecommendedSettings)

id := CommonConfig.GenInt64ID()
fmt.Printf("id generated: %v", id)

func ConstructConfig

func ConstructConfig(timeBits, seqBits, machineBits uint) *Config

ConstructConfig creates an instance of FastIDConfig with the given settings

func ConstructConfigWithMachineID

func ConstructConfigWithMachineID(timeBits, seqBits, machineBits uint, machineID int64) *Config

ConstructConfigWithMachineID creates an config with machine id, in case you don't want to use the lower 16 bits of the IP address.

func (*Config) GenInt64ID

func (c *Config) GenInt64ID() int64

GenInt64ID generates unique int64 IDs with the setting in the methond owner

func (*Config) GetSeqFromID

func (c *Config) GetSeqFromID(id int64) int64

GetSeqFromID extracts seq number from an existing ID

func (*Config) GetTimeFromID

func (c *Config) GetTimeFromID(id int64) int64

GetTimeFromID extracts timestamp from an existing ID