flake

package
Version: v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 25, 2020 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// SequenceBits53 is the # of bits used for 53-MSB sequence #'s
	SequenceBits53 uint64 = 12
	// MSBMask53 represents 2^53-1
	MSBMask53 = 0x1FFFFFFFFFFFFF
)
View Source
const (
	// DefaultSequenceBits is the default # of bits used for sequence #'s
	DefaultSequenceBits uint64 = 16
)
View Source
const MACAddressLength = 6

MACAddressLength is the length, in bytes, of a Network MAC address

View Source
const OvertFlakeIDLength = 16

OvertFlakeIDLength is the length, in bytes, of an Overt-flake ID

View Source
const OvertoneEpochMs = int64(1483228800000)

OvertoneEpochMs represents the number of milliseconds that elapsed between the UnixEpoch (1/1/1970) and the Overtone Epoch, Sunday, January 1st, 2017 (2017-01-01 00:00:00 +0000 UTC)

This is the default epoch used by overt-flake

View Source
const SnowflakeEpochMs = int64(1288834974657)

SnowflakeEpochMs is the number of milliseconds elapsed between the Unix Epoch (1/1/19070) and the Twitter Snowflake Epoch (2010-11-04 01:42:54 +0000 UTC ??)

View Source
const UnixEpochMs = int64(0)

UnixEpochMs is the number of milliseconds elapsed since the Unix Epoch (which is none)

Variables

View Source
var ErrBufferTooSmall = errors.New("the buffer is too small to hold an overt-flake ID")

ErrBufferTooSmall occurs when the user passes in a buffer that is too small to fit a single overt-flake ID

View Source
var ErrInvalidSizeForHardwareAddress = errors.New("The requested size of the hardware ID is not supported by the provider")

ErrInvalidSizeForHardwareAddress occurs when the request size of the hardwardID is incompatible with the hardwaredID provider

View Source
var ErrNoHardwareAddresses = errors.New("No Hardware Adresses are available")

ErrNoHardwareAddresses occurs in the odd case where there are network interfaces but none of them have hardware addresses

View Source
var ErrNoNetworkInterfaces = errors.New("No network interfaces are available")

ErrNoNetworkInterfaces occurs in the odd case where there are no network interfaces

View Source
var ErrTimeIsMovingBackwards = errors.New("time is moving backwards. Cannot resume until last time is reached")

ErrTimeIsMovingBackwards occurs when the clock moves backwards putting us into a position where we could produce duplicate ids. That is obviously bad, and ID generation cannot resume until time catches up to where we were

View Source
var ErrTooManyRequested = errors.New("The # of ids requested exceeds the maximum amount for 1 request")

ErrTooManyRequested occurs when the count passed to the Generate.Generate(int) func exceeds the maximum allowed The maximum allowed is generally related to the maximum sequence number

Functions

This section is empty.

Types

type Generator

type Generator interface {
	IDGenerator

	// Synthesizer is the component that synthesizes flake ids from raw
	// components
	IDGenerator() IDGenerator

	// LastAllocatedTime is the last Unix Epoch value that one or more ids
	// are known to have been generated
	LastAllocatedTime() int64

	// Generate generates count overt-flake identifiers
	Generate(count int) ([]byte, error)

	// GenerateAsStream allocates and returns ids in chunks (based on the size of buffer) via a callback
	GenerateAsStream(count int, buffer []byte, callback func(int, []byte) error) (totalAllocated int, err error)
}

Generator is the base interface for flake ID generators and as a convienence is a superset of IDGenerator. A typical Generator implementation will act as a proxy and forward all IDGenerator methods to its underlying IDGenerator

func NewOvertFlakeGenerator

func NewOvertFlakeGenerator(epoch int64, hardwareID HardwareID, processID int, waitForTime int64) Generator

NewOvertFlakeGenerator creates an instance of generator which implements Generator

func NewOvertFlakeGenerator53

func NewOvertFlakeGenerator53(hardwareID HardwareID, processID int, waitForTime int64) Generator

NewOvertFlakeGenerator53 creates an instance of generator which implements Generator

func NewOvertFlakeGeneratorWithBits

func NewOvertFlakeGeneratorWithBits(epoch int64, hardwareID HardwareID, processID int, waitForTime int64, seqBits uint64) Generator

NewOvertFlakeGeneratorWithBits creates an instance of generator (which implements Generator.) this "constructor" allows the # of sequence bits to be specified

Notes

Setting a value of seqBits > 22 will result in unacceptable time truncation

func NewOvertoneEpochGenerator

func NewOvertoneEpochGenerator(hardwareID HardwareID) Generator

NewOvertoneEpochGenerator creates an instance of generator using the Overtone Epoch

func NewTwitterGenerator

func NewTwitterGenerator(machineID, dataCenterID, waitForTime int64) Generator

NewTwitterGenerator creates an instance of generator (which implements Generator.)

type HardwareID

type HardwareID []byte

HardwareID is an alias for []byte

type HardwareIDProvider

type HardwareIDProvider interface {
	GetHardwareID(byteSize int) ([]byte, error)
}

HardwareIDProvider is a provider that generates a hardware identifier for use by an overt-flake Generator

func NewFixedHardwareIDProvider

func NewFixedHardwareIDProvider(hardwareID HardwareID) HardwareIDProvider

NewFixedHardwareIDProvider creates an instance of fixedHardwareIDProvider

func NewMacHardwareIDProvider

func NewMacHardwareIDProvider() HardwareIDProvider

NewMacHardwareIDProvider creates a new instance of macHardwareIDProvider which implements HardwareIDProvider

func NewSimpleMacHardwareIDProvider

func NewSimpleMacHardwareIDProvider() HardwareIDProvider

NewSimpleMacHardwareIDProvider creates a new instance of simpleMacHardwareIDProvider which implements HardwareIDProvider

type IDGenerator

type IDGenerator interface {
	SynthesizeID(buffer []byte, index int, time int64, sequence uint64) int

	// Epoch returns the epoch used for the identifers created by the generator
	Epoch() int64

	// Get the size, in bytes, of IDs created by the generator
	IDSize() int

	// SequenceBitCount returns the # of bits used for the sequence #
	// For over-flake style identifiers, values in the range 12-22 make
	// sense with 16 being the default.
	SequenceBitCount() uint64

	// SequenceBitMask returns the bitmask for SequenceBitCount() and also
	// acts as the maximum value for a sequence #
	//
	// The mask can be calculated as follows:
	// uint64(int64(-1) ^ (int64(-1) << gen.SequenceBitCount()))
	SequenceBitMask() uint64

	// MaxSequenceNumber is an alias for SequenceBitMask that is used when we
	// want to refer to it as an absolute # rather than a mask. For readability
	MaxSequenceNumber() uint64
}

IDGenerator encapsulates the data and functionality that is specific to ID generation, and is used by a Generator to create actual flake IDs.

func NewTwitterFlakeIDSynthesizer

func NewTwitterFlakeIDSynthesizer(machineID, dataCenterID int64) IDGenerator

NewTwitterFlakeIDSynthesizer creates an instance of generator (which implements Generator) and allows the # of sequence bits to be specified (16 is standard)

type OvertFlakeID

type OvertFlakeID interface {
	// Timestamp is when the ID was generated, and is the # of milliseconds since
	// the generator Epoch
	Timestamp() uint64
	// SequenceID represents the Nth value created during a time interval (0 for the 1st)
	SequenceID() uint16

	// HardwareID is the HardwareID assigned by the generator
	HardwareID() HardwareID
	// ProcessID is the processID assigned by the generator
	ProcessID() uint16
	// MachineID is the uint64 representation of HardwareID and ProcessID and is == Lower()
	MachineID() uint64

	// Upper is the upper (most-signficant) bytes of the id represented as a uint64
	Upper() uint64
	// Lower is the lower (least-signficant) bytes of the id represented as a uint64
	Lower() uint64

	// Bytes is the []byte representation of the ID
	Bytes() []byte

	// ToBigInt converts the ID to a *big.Int
	ToBigInt() *big.Int

	// String returns the big.Int string representation of the ID
	String() string
}

OvertFlakeID is an interface that provides access to the components and alternate representations of an overt-flake identifier

func NewOvertFlakeID

func NewOvertFlakeID(id []byte) OvertFlakeID

NewOvertFlakeID creates an instance of overtFlakeID which implements OvertFlakeID

type OvertFlakeIDGenerator

type OvertFlakeIDGenerator interface {
	IDGenerator

	// HardwareID returns the hardware identifier used for overt-flake identifiers
	HardwareID() HardwareID
	// ProcessID returns the process id hosting the overt-flake Generator
	ProcessID() int
}

OvertFlakeIDGenerator extends IDGenerator adding overt-flake identifier specific concepts

func NewOvertFlakeID53Synthesizer

func NewOvertFlakeID53Synthesizer(hardwareID HardwareID, processID int) OvertFlakeIDGenerator

NewOvertFlakeID53Synthesizer creates an instance of generator (which implements Generator) and restricts the most-significant 8 bytes to use 53 bits (float64 precision), with 41 bytes for time, and 12 bytes for sequence #. Epoch is always OvertoneEpochMs to maximize the range of the 41 bits to 127 years

func NewOvertFlakeIDSynthesizer

func NewOvertFlakeIDSynthesizer(epoch int64, sequenceBits uint64, hardwareID HardwareID, processID int) OvertFlakeIDGenerator

NewOvertFlakeIDSynthesizer creates an instance of generator (which implements Generator) and allows the # of sequence bits to be specified (16 is standard)

Notes

Setting a value of sequenceBits > 22 will result in unacceptable time truncation

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL