README

Sonyflake

GoDoc Build Status Coverage Status Go Report Card

Sonyflake is a distributed unique ID generator inspired by Twitter's Snowflake.
A Sonyflake ID is composed of

39 bits for time in units of 10 msec
 8 bits for a sequence number
16 bits for a machine id

Installation

go get github.com/sony/sonyflake

Usage

The function NewSonyflake creates a new Sonyflake instance.

func NewSonyflake(st Settings) *Sonyflake

You can configure Sonyflake by the struct Settings:

type Settings struct {
	StartTime      time.Time
	MachineID      func() (uint16, error)
	CheckMachineID func(uint16) bool
}
  • StartTime is the time since which the Sonyflake time is defined as the elapsed time. If StartTime is 0, the start time of the Sonyflake is set to "2014-09-01 00:00:00 +0000 UTC". If StartTime is ahead of the current time, Sonyflake is not created.

  • MachineID returns the unique ID of the Sonyflake instance. If MachineID returns an error, Sonyflake is not created. If MachineID is nil, default MachineID is used. Default MachineID returns the lower 16 bits of the private IP address.

  • CheckMachineID validates the uniqueness of the machine ID. If CheckMachineID returns false, Sonyflake is not created. If CheckMachineID is nil, no validation is done.

In order to get a new unique ID, you just have to call the method NextID.

func (sf *Sonyflake) NextID() (uint64, error)

NextID can continue to generate IDs for about 174 years from StartTime. But after the Sonyflake time is over the limit, NextID returns an error.

AWS VPC and Docker

The awsutil package provides the function AmazonEC2MachineID that returns the lower 16-bit private IP address of the Amazon EC2 instance. It also works correctly on Docker by retrieving instance metadata.

AWS VPC is assigned a single CIDR with a netmask between /28 and /16. So if each EC2 instance has a unique private IP address in AWS VPC, the lower 16 bits of the address is also unique. In this common case, you can use AmazonEC2MachineID as Settings.MachineID.

See example that runs Sonyflake on AWS Elastic Beanstalk.

License

The MIT License (MIT)

See LICENSE for details.

Expand ▾ Collapse ▴

Documentation

Overview

    Package sonyflake implements Sonyflake, a distributed unique ID generator inspired by Twitter's Snowflake.

    A Sonyflake ID is composed of

    39 bits for time in units of 10 msec
     8 bits for a sequence number
    16 bits for a machine id
    

    Index

    Constants

    View Source
    const (
    	BitLenTime      = 39                               // bit length of time
    	BitLenSequence  = 8                                // bit length of sequence number
    	BitLenMachineID = 63 - BitLenTime - BitLenSequence // bit length of machine id
    )

      These constants are the bit lengths of Sonyflake ID parts.

      Variables

      This section is empty.

      Functions

      func Decompose

      func Decompose(id uint64) map[string]uint64

        Decompose returns a set of Sonyflake ID parts.

        Types

        type Settings

        type Settings struct {
        	StartTime      time.Time
        	MachineID      func() (uint16, error)
        	CheckMachineID func(uint16) bool
        }

          Settings configures Sonyflake:

          StartTime is the time since which the Sonyflake time is defined as the elapsed time. If StartTime is 0, the start time of the Sonyflake is set to "2014-09-01 00:00:00 +0000 UTC". If StartTime is ahead of the current time, Sonyflake is not created.

          MachineID returns the unique ID of the Sonyflake instance. If MachineID returns an error, Sonyflake is not created. If MachineID is nil, default MachineID is used. Default MachineID returns the lower 16 bits of the private IP address.

          CheckMachineID validates the uniqueness of the machine ID. If CheckMachineID returns false, Sonyflake is not created. If CheckMachineID is nil, no validation is done.

          type Sonyflake

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

            Sonyflake is a distributed unique ID generator.

            func NewSonyflake

            func NewSonyflake(st Settings) *Sonyflake

              NewSonyflake returns a new Sonyflake configured with the given Settings. NewSonyflake returns nil in the following cases: - Settings.StartTime is ahead of the current time. - Settings.MachineID returns an error. - Settings.CheckMachineID returns false.

              func (*Sonyflake) NextID

              func (sf *Sonyflake) NextID() (uint64, error)

                NextID generates a next unique ID. After the Sonyflake time overflows, NextID returns an error.

                Source Files

                Directories

                Path Synopsis
                Package awsutil provides utility functions for using Sonyflake on AWS.
                Package awsutil provides utility functions for using Sonyflake on AWS.