Crate snowcloud

Snowcloud

a small library for implementing custom ids based on timestamps, static ids, and sequence counters. the module provides 2 types of generators, a thread safe and non thread safe version. they allow for different types of waiting for ids if you want specific behavior. each generator is capable of using different snowflake types to allow for different snowflake formats.

examples of using snowflakes with i64 base types

// 43 bit timestamp, 8 bit primary id, 12 bit sequence
type MyFlake = snowcloud::i64::SingleIdFlake<43, 8, 12>;
type MyCloud = snowcloud::Generator<MyFlake>;

// 2023/03/23 9:00:00 in milliseconds, timestamps will start from this
// date
const START_TIME: u64 = 1679587200000;

let mut cloud = MyCloud::new(START_TIME, 1)
    .expect("failed to create MyCloud");
let flake = cloud.next_id()
    .expect("failed to create snowflake");

println!("{}", flake.id());

creating a snowflake with two id segments

// 43 bit timestamp, 4 bit primary id, 4 bit secondary id, 12 bit sequence
type MyFlake = snowcloud::i64::DualIdFlake<43, 4, 4, 12>;
type MyCloud = snowcloud::Generator<MyFlake>;

// 2023/03/23 9:00:00 in milliseconds, timestamps will start from this
// date
const START_TIME: u64 = 1679587200000;

let mut cloud = MyCloud::new(START_TIME, (1, 1))
    .expect("failed to create MyCloud");
let flake = cloud.next_id()
    .expect("failed to create snowflake");

println!("{}", flake.id());

Behavior

sync::MutexGenerator is a thread safe implementation for sharing between threads on a system. it uses an Arc Mutex to handle sharing the sequence count and prev_time. the only time it will block is when acquiring the mutex and will not wait if a valid snowflake cannot be acquired. if a generator is unable to create a snowflake because the max sequence number has been reached an error will be returned providing an estimated duration to the next millisecond. how you want to wait can be decided by the user.

Generator is similar in most aspects to sync::MutexGenerator expect next_id is a mutating call and sequence count with prev_time are not stored in an Arc Mutext. THIS IS NOT THREAD SAFE.

Traits

to help with using a generator in other situations, traits are provided and implemented for the base types (more can be added later if necessary/desired).

• IdGenerator describes the basic layout of an id generator. requiring an Error, Id, and Output type to be specified along with the next_id method.
• IdGeneratorMut is similar to IdGenerator except the next_id call allows for mutating the object
• NextAvailId describes an object that is capable of returing a duraiton to the next available millisecond. check blocking_next_id for example implementation.
• Id describes base methods for what an Id requires. currently just handles turning a snowflake into its base type like an i64.

Timestamps

all snowflakes use timestamps of milliseconds with the generators using SystemTime to track the provided epoch and generate new timestamps for snowflakes. the start date must be in the future of UNIX_EPOCH and cannot be a date in the future, now >= start_time >= UNIX_EPOCH.

// the current example date is 2023/03/23 9:00:00.
const VALID_START_DATE: u64 =   1679587200000;

// if a date that is after the current system time is provided the
// snowcloud will return an error. 2077/10/23 9:00:00
const INVALID_START_DATE: u64 = 3402205200000;

below is a table with various bit values and how many years you can get out of a timestamp. you will probably get diminishing returns with lower bit values if this is to be used over a long duration of time.

bits	max value	years
43	8796093022207	278
42	4398046511103	139
41	2199023255551	69
40	1099511627775	34
39	549755813887	17
38	274877906943	8
37	137438953471	4
36	68719476735	2
35	34359738367	1

De/Serialize

snowflakes support serde Serialize and Deserialize to there internal types with an addtional option to de/serailize to a string. see serde_ext for additional methods of de/serialization

Modules

• i64
  provides i64 based snowflakes
• sync
• traits
  base traits for implementing helper code
• u64
  provides u64 based snowflakes;
• wait
  methods for waiting on the next available id from a snowcloud

Structs

• Generator
  simple snowflake generator
• Segments
  container for storing id segments

Enums

• Error
  possible errors for Snowclouds/Snowflakes