README

MonoLexID

MonoLexID is a time-ordered and sortable Universally Unique Identifier (UUID) generator for Object Pascal (Lazarus/Free Pascal), producing identifiers structurally compatible with the RFC 9562 UUIDv7 layout while privileging intra-millisecond monotonicity.

Generation Policy

• Lexicographic Monotonicity: Identifiers are time-ordered at millisecond precision, ensuring natural sequential sorting, preventing index fragmentation and optimising database insertion performance.
• Time Integrity: The generator privileges chronological truth (clock-dependent). Should the system exhaust the sequence counter (4,096 allocations per millisecond) or detect a retrograde clock shift, generation is suspended via a CPU spin-wait loop. It yields (pauses) until physical time advances, so that identifiers are not generated with a fictitious-future time.
• Cryptographic Uniqueness: To preclude collisions in distributed environments, the remainder of the string payload is populated using OS-native, cryptographically secure pseudorandom number generators to minimise collision risk.

Structure

MonoLexID generates a 36-character string (xxxxxxxx-xxxx-7xxx-xxxx-xxxxxxxxxxxx), which breaks down as follows:

• Chars 1-8: UNIX Timestamp in Milliseconds (Part 1)
• Char 9: Hyphen -
• Chars 10-13: UNIX Timestamp in Milliseconds (Part 2)
• Char 14: Hyphen -
• Chars 15-18: Version Identifier (7) + 12-bit Sequence Counter
• Char 19: Hyphen -
• Chars 20-23: Variant Identifier (8, 9, a, or b) + Random Data
• Char 24: Hyphen -
• Chars 25-36: Secure Random Data

Usage

MonoLexID is contained entirely within a single unit with no external dependencies. To integrate it, download the latest version from the Releases page, include uLibMonoLex.pas in the project directory, and add it to the uses clause.

uses
  uLibMonoLex;

var
  NewID: String;
begin
  // Generate a standard 36-character string format
  NewID := MonoLexID; 
  
  // Alternatively, retrieve the raw 16-byte array
  // var RawBytes: TMonoLexBytes;
  // RawBytes := MonoLexIDBytes;
end;

Thread Safety Configuration

By default, MonoLexID uses threadvar for state management, which is efficient for single-threaded or thread-local generation.

If an application requires a strict, globally monotonic sequence across multiple threads, global locking can be enabled by uncommenting the MONOLEX_GLOBAL_MONOTONIC directive at the top of the implementation section in uLibMonoLex.pas:

// {$DEFINE MONOLEX_THREAD_LOCAL}
{$DEFINE MONOLEX_GLOBAL_MONOTONIC}

Compatibility

MonoLexID compiles and functions under:

• Windows (32-bit & 64-bit)
• Linux/macOS (Requires BaseUnix and /dev/urandom)
• Free Pascal 3.2.2/Lazarus

Acknowledgements

This project has benefitted significantly from Google Gemini 3’s assistance for ideation, code generation, and refactoring.

License

This project is licensed under the BSD 3-Clause License and is provided as-is, without any warranties. Please see the LICENSE file for details.