README
¶
idmint
Overview
idmint is a Go module for minting unique, time-sortable, IDs in a distributed system without coordination between
nodes.
Usage
Creating a minter
As per the Go proverb, the zero value of the idmint.Minter is useful, and you can simply create
an idmint.Minter as follows and begin using it:
var minter idmint.Minter
However, if you have multiple nodes that will be minting IDs, you must create an idmint.Minter using the
idmint.NewMinter function and pass a unique worker ID:
var workerID uint64
// ...
// compute a unique worker id
// ...
minter, err := idmint.NewMinter(workerID)
if err != nil {
// handle error
}
You can also configure the behaviour of an idmint.Minter by providing some idmint.Configurer's to the
idmint.NewMinter function. For example:
var workerID uint64
// ...
// compute a unique worker id
// ...
now := time.Now()
minter, err := idmint.NewMinter(
workerID,
idmint.WithStartOfMintingTime(now),
)
if err != nil {
// handle error
}
Minting an ID
Once you have created an idmint.Minter, you can call idmint.Minter.Mint to mint an ID:
var workerID uint64
// ...
// compute a unique worker id
// ...
minter, err := idmint.NewMinter(workerID)
if err != nil {
// handle error
}
id, err := minter.Mint()
if err != nil {
// handle error
}
fmt.Println(id) // e.g. 61898956800000
Documentation
Documentation for idmint can be found here.
Documentation
¶
Overview ¶
Package idmint is a Go module for minting unique, time-sortable IDs in a distributed system without coordination between nodes.
Index ¶
Constants ¶
const Version = "1.0.0"
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Configurer ¶
type Configurer interface {
// contains filtered or unexported methods
}
Configurer configures the behaviour of a Minter.
func WithClock ¶
func WithClock(clock Clock) Configurer
WithClock returns a Configurer that sets a custom Clock on a Minter.
func WithStartOfMintingTime ¶
func WithStartOfMintingTime(startOfMintingTime time.Time) Configurer
WithStartOfMintingTime returns a Configurer that the start of minting time on a Minter.
type CurrentTimeAfterEndOfMintingTimeError ¶
type CurrentTimeAfterEndOfMintingTimeError struct {
// contains filtered or unexported fields
}
CurrentTimeAfterEndOfMintingTimeError indicates that the current time is after the end of time.
func (CurrentTimeAfterEndOfMintingTimeError) Error ¶
func (e CurrentTimeAfterEndOfMintingTimeError) Error() string
type CurrentTimeBeforeStartOfMintingTimeError ¶
type CurrentTimeBeforeStartOfMintingTimeError struct {
// contains filtered or unexported fields
}
CurrentTimeBeforeStartOfMintingTimeError indicates that the current time is before the start of time.
func (CurrentTimeBeforeStartOfMintingTimeError) Error ¶
func (e CurrentTimeBeforeStartOfMintingTimeError) Error() string
type Minter ¶
type Minter struct {
// contains filtered or unexported fields
}
Minter mints unique, time-sortable, IDs whose 64-bit value is composed of:
- 42 bits representing the time, in milliseconds since the start, when the ID was minted.
- 10 bits that uniquely identify the worker that minted the ID.
- 12 bits the number of the ID in the sequence of IDs minted that millisecond.
This allows us to have 1024 workers each minting 4096 IDs per millisecond. It is safe for concurrent use.
type SequenceNumberTooLargeError ¶
type SequenceNumberTooLargeError struct{}
SequenceNumberTooLargeError indicates that a Minter has minted more than 4096 IDs in the same millisecond.
func (SequenceNumberTooLargeError) Error ¶
func (e SequenceNumberTooLargeError) Error() string
type TimeMovedBackwardsError ¶
type TimeMovedBackwardsError struct {
// contains filtered or unexported fields
}
TimeMovedBackwardsError indicates that the clock has moved backwards since the last ID was minted.
func (TimeMovedBackwardsError) Duration ¶
func (e TimeMovedBackwardsError) Duration() time.Duration
func (TimeMovedBackwardsError) Error ¶
func (e TimeMovedBackwardsError) Error() string
type WorkerIDTooLargeError ¶
type WorkerIDTooLargeError struct {
// contains filtered or unexported fields
}
WorkerIDTooLargeError indicates that the worker ID was larger than the maximum value.
func (WorkerIDTooLargeError) Error ¶
func (e WorkerIDTooLargeError) Error() string
Source Files