Skip to main content

FSDK UID

fsdk_uid allows generation of globally unique identifiers locally without coordination in either simple or multi-threaded and scalable solutions, preventing duplication and collision between the identifiers without any kind of connection between all FSUID Nodes.

Glossary​

FSUID - Globally unique 64 signed bits identifier generated by fsdk_uid library, containing the FSUID Timestamp Delta, FSUID Node Identifier and FSUID Node Counter.

FSUID Node - Represents a thread, a process, a application, a machine or a datacenter with a unique FSUID Node Identifier

Unix Timestamp - Represents the datetime of 01/01/1970 00:00:00.00 UTC

FSUID Timestamp Delta - Miliseconds passed since the Unix Timestamp represented in 48 signed bits when the FSUID was generated

FSUID Node Identifier - Unique identification number of each FSUID Node represnted in 8 unsigned bits, used in order to avoid collisions/duplicated FSUID's when 2 or more FSUID Node tries to generate a FSUID within the same milisecond

FSUID Node Counter - 8 bit unsigned counter which is incremented at each FSUID generation within a FSUID Node in order to avoid collisions/duplicated FSUID's when a multi-thread or multi-process solution tries to generate a FSUID. When this value is exausted the generator overflows to zero and waits a millisecond before trying to generate a new FSUID

FSUID Example​

Considering 0b11111111 11111111 11111111 11111111 11111111 11111111 00000001 00000011 as an FSUID generated at 31/12/1969 23:59:59.99 UTC in the node 1 and was the 4th FSUID generated at that milisecond

FSUID (i64)11111111 11111111 11111111 11111111 11111111 111111110000000100000011
FSUID FieldFSUID Timestamp DeltaFSUID Node IdentifierFSUID Node Counter

Converting to human readable decimal number this would be -65277

Note: In real production systems the number will be always positive because the datetime will be greater than 01/01/1970 00:00:00.00 UTC

API​

FsdkUidGenerator​

Constructor: FsdkUidGenerator.new(node_identifier: u8) -> FsdkUidGenerator

Method Generate FSUID (i64 format): FsdkUidGenerator.generate_i64() -> i64

Method Generate FSUID (FSUID format): FsdkUidGenerator.generate_fsuid() -> FsdkUid

Destructor: FsdkUidGenerator.dispose() -> Null

FsdkUid​

Constructor: FsdkUid.new(fsuid: i64) -> FsdkUid

Property Get FSUID i64 FsdkUid.i64 -> i64

Property Get FSUID Generation UTC DateTime FsdkUid.utc_datetime -> UtcDateTime

Property Get FSUID Timestamp Delta FsdkUid.timestamp_delta -> i48

Property Get FSUID Node Identifier FsdkUid.node_identifier -> u8

Property Get FSUID Node Counter FsdkUid.node_counter -> u8

Destructor: FsdkUid.dispose() -> Null

Example Usage​

REST API (Demo Shared Node)​

We provide a free demo node exposed through a REST API at https://fsdk-api.futurize.pt/uid/v1/generate which allows you to generate a FSUID with FSUID Node Identifier 0 concurrently with other users (we internally only use numbers from 1 to 255).

This node doesn't have load balancing so it's expected to have more downtime than other Futurize Studios services, doesn't require any authentication and it's rate-limited by IP Address at 5 requests per second.

To test either open https://fsdk-api.futurize.pt/uid/v1/generate in your web browser or open a command prompt and run this curl command:

curl -X GET "https://fsdk-api.futurize.pt/uid/v1/generate"

After you run this command or open https://fsdk-api.futurize.pt/uid/v1/generate in your web browser it should return status code 201, with the header Content:text/plain and the FSUID generated in the body

You mustn't use this node in your production solutions since it is very rate-limited and the library is more performant since it runs on your hardware and isn't shared with other users.

Python 3​

Generate FSUID for production solutions​

# Import FSUID Generator from fsdk_uid library
from fsdk_uid import FsdkUidGenerator

# Instance the FSUID Generator, considering the current node has the identifier 0
fsuid_generator = FsdkUidGenerator(node_identifier=0)

# Generates a FSUID in format i64, designed for production use (it works in single-threaded and multi-threaded environments)
fsuid = fsuid_generator.generate_i64()

# Print the FSUID (i64 format)
print(f"Generated FSUID: {fsuid}")

Generate FSUID and parse information​

# Import FSUID Generator from fsdk_uid library
from fsdk_uid import FsdkUidGenerator, FsdkUid

# Instance the FSUID Generator, considering the current node has the identifier 0
fsuid_generator = FsdkUidGenerator(node_identifier=0)

# Generates a FSUID in format FSUID, designed for reading the fields of it easily
fsuid: FsdkUid = fsuid_generator.generate_fsuid()

# Print the FSUID i64 format and the python serialized UTC DateTime when it was generated
print(f"Generated FSUID: {fsuid.i64} at {fsuid.utc_datetime}")

# Print the FSUID Timestamp Delta as int
print(f"Generated FSUID Timestamp Delta: {fsuid.timestamp_delta}")

# Print the FSUID Node Identifier as int
print(f"Generated FSUID Node Identifier: {fsuid.node_identifier}")

# Print the FSUID Node Counter as int
print(f"Generated FSUID Node Counter: {fsuid.node_counter}")

Parse information from i64 FSUID​

# Import FSUID type from fsdk_uid library
from fsdk_uid import FsdkUid

# Converts a i64 or bytes to FSUID
fsuid: FsdkUid = FsdkUid(fsuid=-65277)
# fsuid: FsdkUid = FsdkUid(fsuid=0b1111111111111111111111111111111111111111111111110000000100000011)

# Print the FSUID i64 format and the python serialized UTC DateTime when it was generated
print(f"Parsed FSUID: {fsuid.i64} at {fsuid.utc_datetime}")

# Print the FSUID Timestamp Delta as int
print(f"Parsed FSUID Timestamp: {fsuid.timestamp_delta}")

# Print the FSUID Node Identifier as int
print(f"Parsed FSUID Node Identifier: {fsuid.node_identifier}")

# Print the FSUID Node Counter as int
print(f"Parsed FSUID Node Counter: {fsuid.node_counter}")

Rust​

Generate FSUID for production solutions​

// Import FSUID Generator from fsdk_uid library
use fsdk_uid::{FsdkUidGenerator};

fn main() {
    
    // Instance the FSUID Generator, considering the current node has the identifier 0
    let fsuid_generator = FsdkUidGenerator::new(0);

    // Generates a FSUID in format i64, designed for production use (it works in single-threaded and multi-threaded environments)
    let fsuid = fsuid_generator.generate_i64();

    // Print the FSUID (i64 format)
    println!("Generated FSUID: {}", fsuid);
}

Parse information from i64 FSUID​

// Import FSUID Generator from fsdk_uid library
use fsdk_uid::{FsdkUidGenerator};

fn main() {
    
    // Converts a i64 to FSUID
    let fsuid = FsdkUid::new(-65277);

    // Print the FSUID i64 format
    println!("Parsed FSUID: {}", fsuid.i64());
    // Print the FSUID Timestamp Delta as int
    println!("Parsed FSUID Timestamp Delta: {}", fsuid.timestamp_delta());
    // Print the FSUID Node Identifier as int
    println!("Parsed FSUID Node Identifier: {}", fsuid.node_identifier());
    // Print the FSUID Node Counter as int
    println!("Parsed FSUID Node Counter: {}", fsuid.node_counter());
    // Print the FSUID UTC DateTime when it was generated
    println!("Parsed FSUID UTC DateTime: {}", fsuid.utc_datetime());
}