sonyflake

package module
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Aug 3, 2023 License: MIT Imports: 12 Imported by: 0

README

Sonyflake

GoDoc Go Report Card

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

Sonyflake focuses on lifetime and performance on many host/core environment. So it has a different bit assignment from 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

As a result, Sonyflake has the following advantages and disadvantages:

  • The lifetime (174 years) is longer than that of Snowflake (69 years)
  • It can work in more distributed machines (2^16) than Snowflake (2^10)
  • It can generate 2^8 IDs per 10 msec at most in a single machine/thread (slower than Snowflake)

However, if you want more generation rate in a single host, you can easily run multiple Sonyflake ID generators concurrently using goroutines.

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.

Note: Sonyflake currently does not use the most significant bit of IDs, so you can convert Sonyflake IDs from uint64 to int64 safely.

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.

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.

View Source 
const (
	SonyflakeService_NextID_FullMethodName = "/sonyflake.SonyflakeService/NextID"
)

Variables

View Source 
var File_grpc_service_proto protoreflect.FileDescriptor
View Source 
var SonyflakeService_ServiceDesc = grpc.ServiceDesc{
	ServiceName: "sonyflake.SonyflakeService",
	HandlerType: (*SonyflakeServiceServer)(nil),
	Methods: []grpc.MethodDesc{
		{
			MethodName: "NextID",
			Handler:    _SonyflakeService_NextID_Handler,
		},
	},
	Streams:  []grpc.StreamDesc{},
	Metadata: "grpc_service.proto",
}

SonyflakeService_ServiceDesc is the grpc.ServiceDesc for SonyflakeService service. It's only intended for direct use with grpc.RegisterService, and not to be introspected or modified (even as a copy)

Functions

func Decompose 

func Decompose(id uint64) map[string]uint64

Decompose returns a set of Sonyflake ID parts.

func ElapsedTime 

func ElapsedTime(id uint64) time.Duration

ElapsedTime returns the elapsed time when the given Sonyflake ID was generated.

func MachineID 

func MachineID(id uint64) uint64

MachineID returns the machine ID of a Sonyflake ID.

func RegisterSonyflakeServiceServer 

func RegisterSonyflakeServiceServer(s grpc.ServiceRegistrar, srv SonyflakeServiceServer)

func SequenceNumber 

func SequenceNumber(id uint64) uint64

SequenceNumber returns the sequence number of a Sonyflake ID.

Types

type GrpcSonyflakeService 

type GrpcSonyflakeService struct {
	UnimplementedSonyflakeServiceServer
	Sf *Sonyflake
}

GrpcSonyflakeService implement SonyflakeServiceServer interface

func (*GrpcSonyflakeService) NextID 

func (rpcS *GrpcSonyflakeService) NextID(ctx context.Context, req *SonyFlakeRequest) (*SonyFlakeResponse, error)

NextID generate sequence

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 SonyFlakeRequest 

type SonyFlakeRequest struct {
	Num uint32 `protobuf:"varint,1,opt,name=num,proto3" json:"num,omitempty"`
	// contains filtered or unexported fields
}

func (*SonyFlakeRequest) Descriptor deprecated 

func (*SonyFlakeRequest) Descriptor() ([]byte, []int)

Deprecated: Use SonyFlakeRequest.ProtoReflect.Descriptor instead.

func (*SonyFlakeRequest) GetNum 

func (x *SonyFlakeRequest) GetNum() uint32

func (*SonyFlakeRequest) ProtoMessage 

func (*SonyFlakeRequest) ProtoMessage()

func (*SonyFlakeRequest) ProtoReflect 

func (x *SonyFlakeRequest) ProtoReflect() protoreflect.Message

func (*SonyFlakeRequest) Reset 

func (x *SonyFlakeRequest) Reset()

func (*SonyFlakeRequest) String 

func (x *SonyFlakeRequest) String() string

type SonyFlakeResponse 

type SonyFlakeResponse struct {
	Id        uint64 `protobuf:"varint,1,opt,name=id,proto3" json:"id,omitempty"`
	Msb       uint64 `protobuf:"varint,2,opt,name=msb,proto3" json:"msb,omitempty"`
	Time      uint64 `protobuf:"varint,3,opt,name=time,proto3" json:"time,omitempty"`
	Sequence  uint64 `protobuf:"varint,4,opt,name=sequence,proto3" json:"sequence,omitempty"`
	MachineID uint64 `protobuf:"varint,5,opt,name=machineID,proto3" json:"machineID,omitempty"`
	// contains filtered or unexported fields
}

func (*SonyFlakeResponse) Descriptor deprecated 

func (*SonyFlakeResponse) Descriptor() ([]byte, []int)

Deprecated: Use SonyFlakeResponse.ProtoReflect.Descriptor instead.

func (*SonyFlakeResponse) GetId 

func (x *SonyFlakeResponse) GetId() uint64

func (*SonyFlakeResponse) GetMachineID 

func (x *SonyFlakeResponse) GetMachineID() uint64

func (*SonyFlakeResponse) GetMsb 

func (x *SonyFlakeResponse) GetMsb() uint64

func (*SonyFlakeResponse) GetSequence 

func (x *SonyFlakeResponse) GetSequence() uint64

func (*SonyFlakeResponse) GetTime 

func (x *SonyFlakeResponse) GetTime() uint64

func (*SonyFlakeResponse) ProtoMessage 

func (*SonyFlakeResponse) ProtoMessage()

func (*SonyFlakeResponse) ProtoReflect 

func (x *SonyFlakeResponse) ProtoReflect() protoreflect.Message

func (*SonyFlakeResponse) Reset 

func (x *SonyFlakeResponse) Reset()

func (*SonyFlakeResponse) String 

func (x *SonyFlakeResponse) String() string

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.

type SonyflakeServiceClient 

type SonyflakeServiceClient interface {
	NextID(ctx context.Context, in *SonyFlakeRequest, opts ...grpc.CallOption) (*SonyFlakeResponse, error)
}

SonyflakeServiceClient is the client API for SonyflakeService service.

For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.

func NewSonyflakeServiceClient 

func NewSonyflakeServiceClient(cc grpc.ClientConnInterface) SonyflakeServiceClient

type SonyflakeServiceServer 

type SonyflakeServiceServer interface {
	NextID(context.Context, *SonyFlakeRequest) (*SonyFlakeResponse, error)
	// contains filtered or unexported methods
}

SonyflakeServiceServer is the server API for SonyflakeService service. All implementations must embed UnimplementedSonyflakeServiceServer for forward compatibility

type UnimplementedSonyflakeServiceServer 

type UnimplementedSonyflakeServiceServer struct {
}

UnimplementedSonyflakeServiceServer must be embedded to have forward compatible implementations.

func (UnimplementedSonyflakeServiceServer) NextID 

func (UnimplementedSonyflakeServiceServer) NextID(context.Context, *SonyFlakeRequest) (*SonyFlakeResponse, error)

type UnsafeSonyflakeServiceServer 

type UnsafeSonyflakeServiceServer interface {
	// contains filtered or unexported methods
}

UnsafeSonyflakeServiceServer may be embedded to opt out of forward compatibility for this service. Use of this interface is not recommended, as added methods to SonyflakeServiceServer will result in compilation errors.

Source Files

View all 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.
Package mock offers implementations of interfaces defined in types.go This allows complete control over input / output for any given method that consumes a given type
 Package mock offers implementations of interfaces defined in types.go This allows complete control over input / output for any given method that consumes a given type
Package Types defines type signatures used throughout SonyFlake.
 Package Types defines type signatures used throughout SonyFlake.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.