The highest tagged major version is
README
¶
ONEID - Distributable Unique numeric IDS
Features Summary
- Thread-safe concurrent Numeric IDs.
- Support upto 1024 servers with upto 32 processes each by default.
- Partially-sortable time-based IDs.
- Trivially customizable to support even more.
- Uses only builtin Golang stdlib with no external dependencies.
- Fully testable.
- go.mod support.
You will love it if:
- You believe numbers are IDs :)
- You believe IDs creation should be wired to the app with no dependencies on any external ID servers.
Installation
- The usal way, get it:
go get github.com/coderme/oneid/v2
Usage
- Generation of uint32 Id on a simple server with single process is as simple as:
id := oneid.Uint32(1,1 &oneid.DefaultUint32Config)
- or better an uint64 if your database supports it
id := oneid.Uint64(1,1 &oneid.DefaultUint64Config)
Advanced Usage
- You can Create a custom config in order to support upto 16,384 servers with 32 processes each.
conf := oneid.NewUint64Config(14, 5, 20)
id, err := EnvUint64()
if err != nil {
// deal with the error
}
Documentation
¶
Overview ¶
Package oneid provides utility functions for generating unique numeric IDs concurrently and
safely distributable across multiple servers.
Generating IDs:
IDs generated are partially time-sortable, guaranteed to be unique only if the program is running by one
process and on a single server. On cluster of servers or multiple processes per server, further configuration
is needed.
Uint32(serverID, processID, Config) and Uint64(serverID, processID, config) can be used to generate IDS with
fixed serverID and processID on simple setups.
For more two servers or more, there are os nviroment depenedant which lookup up serverID is environment
SERVER_ID and processID in environment variable PROCESS_ID
Arguments:
Both ServerID and ProcessID accept positive numbers olny as valid values, besides processID accepts zero
as valid value too which indicates the function to use the current dynamic system process id (pid).
Default Configurations:
The default configration supports upto 1024 servers and upto 32 processes per each one.
To support more than 1024 servers, or more than 32 processes, consider customizing processBits and serverBits
by using NewUint32Config() and NewUint64Config() for Uint32(), EnvUint32() and its uint64 equivalent Uint64()
EnvUint64() functions respectively.
Configurations are thread-safe and should be reused across multiple goroutines.
Limitations:
Duplicate id maybe generated on heavly-loaded setups, to minimize the possibility of generating
duplicates:
* One server with multiple processes:
= Consider using processes manager like systemd, in order to decrease the os dynamic process sid
aka (pid) gap, large gaps between pid increase the likelihood of exhasting processbits.
= A better solution would be use static processID as environment variable available for a single
process each. Then use EnvUint32 and EnvUint64.
* Multiple servers with multiple processe:
= Avoid out of range server ids.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var DefaultUint32Config = NewUint32Config(defaultUint32ProcessBits, defaultUint32ServerBits, defaultUint32SequenceBits)
DefaultUint32Config sets: processBits to 5, which supports upto 32 processes per server serverBits: 10, which supports upto 1024 servers sequenceBits: 12, which supports upto 4096 ids per time instance.
var DefaultUint64Config = NewUint64Config(defaultUint64ProcessBits, defaultUint64ServerBits, defaultUint64SequenceBits)
DefaultUint64Config sets: processBits to 5, which supports upto 32 processes per server serverBits: 10, which supports upto 1024 servers sequenceBits: 24, which supports upto 16,777,216 ids per time instance.
Functions ¶
func EnvUint32 ¶
func EnvUint32(c *Uint32Config) (uint32, error)
EnvUint32 generates an uint32 id from envirment variables SERVER_ID: unique numeric value represents this server PROCESS_ID: unique numeric value represents this process.
func EnvUint64 ¶
func EnvUint64(c *Uint64Config) (uint64, error)
EnvUnt64 generates an uint64 id from envirment variables SERVER_ID: unique numeric value represents this server PROCESS_ID: unique numeric value represents this process.
func Uint32 ¶
func Uint32(serverID, processID uint32, c *Uint32Config) uint32
Uint32 generates an uint32 id using serverID, processID and config if processID is zero, then the system pid will be used.
func Uint64 ¶
func Uint64(serverID, processID uint64, c *Uint64Config) uint64
Uint64 generates uint64 id using using serverID, processID and config if processID is zero, then the system pid will be used.
Types ¶
type Uint32Config ¶
type Uint32Config struct {
Epoch,
CustomEpoch,
LastTime,
Sequence,
ProcessBits,
ServerBits,
SequenceBits uint32
*sync.Mutex
}
Uint32Config is cocurrently-safe stateful configuration for raceless uint32 id generatation.
func NewUint32Config ¶
func NewUint32Config(serverBits, processBits, sequenceBits uint32) Uint32Config
NewUint32Config makes reasonable Uint32Config from the arguments provided,
sequenceBits is greedy parameter and will be set to the maximum value when possible.
Examples:
- Horizontal scaling: processBits: 5, serverBits: 10, sequenceBits 12 This will support upto 32 processes and 1024 servers.
- Vertical scaling: processBits: 6, serverBits: 1, sequenceBits: 20 This will support upto 64 processes.
type Uint64Config ¶
type Uint64Config struct {
Epoch,
CustomEpoch,
LastTime,
Sequence,
ProcessBits,
ServerBits,
SequenceBits uint64
*sync.Mutex
}
Uint64Config is cocurrently-safe stateful configuration for raceless uint64 id generatation.
func NewUint64Config ¶
func NewUint64Config(serverBits, processBits, sequenceBits uint64) Uint64Config
NewUint64Config makes reasonable Unt64Config from the arguments passed,
sequenceBits is greedy parameter and will be set to the maximum value when possible.
Examples:
- Horizontal scaling: processBits: 5, serverBits: 10, sequenceBits 24 This will support upto 32 processes and 1024 servers.
- Vertical scaling: processBits: 6, serverBits: 1, sequenceBits: 20 This will support upto 64 processes.
Source Files