Crate infallible_sonyflake

This file implements SonyFlake distributed id generate algorithm and some extensions. SonyFlake

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.

Usage

The function NewSonyFlake creates a new SonyFlake instance.

You can configure SonyFlake by the struct Settings:

Install

Add the following to your Cargo.toml:

[dependencies]
infallible-sonyflake = "0.1"

Quickstart

1. Fallible SonyFlake Sonyflake may fail to generate a unique ID when we call next_id if time overflows.

   use infallible_sonyflake::{SonyFlake, Settings};
   use chrono::Utc;
   
   fn main() {
       let now = Utc::now();
       let mut sf = Settings::new().set_start_time(now).into_sonyflake().unwrap();
       let next_id = sf.next_id().unwrap();
       println!("{}", next_id);
   }

2. Infallible SonyFlake InfallibleSonyFlake will always generate a unique ID when we call next_id if time overflow happens, it will refresh the start_time to the current time.

   use infallible_sonyflake::{InfallibleSonyFlake, Settings};
   use chrono::Utc;
   
   fn main() {
       let now = Utc::now();
       let mut sf = Settings::new().set_start_time(now).into_infallible_sonyflake().unwrap();
       let next_id = sf.next_id();
       println!("{}", next_id);
   }

3. Custom machine ID and machine ID checker

   use infallible_sonyflake::{InfallibleSonyFlake, Settings, MachineID, MachineIDChecker, IDParts, Error};
   use chrono::Utc;
   
   struct CustomMachineID {
       counter: u64,
       id: u16,
   }
   
   impl MachineID for CustomMachineID {
       fn machine_id(&mut self) -> Result<u16, Box<dyn std::error::Error + Send + Sync + 'static>> {
           self.counter += 1;
           if self.counter % 2 != 0 {
               Ok(self.id)
           } else {
               Err(Box::new("NaN".parse::<u32>().unwrap_err()))
           }
       }
   }
   
   struct CustomMachineIDChecker;
   
   impl MachineIDChecker for CustomMachineIDChecker {
       fn check_machine_id(&self, id: u16) -> bool {
           if id % 2 != 0 {
               true
           } else {
               false
           }
       }
   }
   
   fn main() {
       let mut sf = Settings::new()
           .set_machine_id(Box::new(CustomMachineID { counter: 0, id: 1 }))
           .set_check_machine_id(Box::new(CustomMachineIDChecker {}))
           .into_infallible_sonyflake().unwrap();
       let id = sf.next_id();
       let parts = IDParts::decompose(id);
       assert_eq!(parts.get_machine_id(), 1);
   
       let err = Settings::new()
           .set_machine_id(Box::new(CustomMachineID { counter: 0, id: 2 }))
           .set_check_machine_id(Box::new(CustomMachineIDChecker {}))
           .into_infallible_sonyflake().unwrap_err();
   
       assert_eq!(format!("{}", err), Error::InvalidMachineID(2).to_string());
   }

• 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 “2021-08-06 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.

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. Or, you can use InfallibleSonyFlake, InfallibleSonyFlake will always generate a unique ID when we call next_id if time overflow happens, it will refresh the start_time to the current time.

Structs

IDParts

IDParts contains the bit parts for an ID.

InfallibleSonyFlake

InfallibleSonyFlake is a distributed unique ID generator, which will always generate a unique id. If time overflows, it will refresh the start time to current time.

Settings

A builder to build a SonyFlake generator.

SonyFlake

SonyFlake is a distributed unique ID generator, may fail to generate unique id if time overflows.

Enums

Error

The Error type for this crate.

Traits

MachineID

MachineID is for custom machine id generator.

MachineIDChecker

MachineIDChecker is for custom machine id checker.

Functions

decompose

decompose returns a set of SonyFlake ID parts.