Skip to content

Revise event ID generation #30

@ddrcode

Description

@ddrcode

Status

Ready for implementation. As it introduces breaking change - should wait for 0.3.0
Decision whether it should be implemented is still open.

Summary

Replace EventId from u128 (UUID v4) to u64 (process-global monotonic AtomicU64 counter). Drop the uuid
dependency.

Motivation

  • Uuid::new_v4() calls the OS CSPRNG (~50-80ns per event) — cryptographic randomness is unnecessary for
    in-process uniqueness
  • UUID-based IDs have no natural ordering, forcing EventChain to sort via a HashMap<EventId, u64> timestamp
    lookup
  • u128 is wider than needed for a single-process runtime
  • The uuid crate is Maiko's only non-essential dependency

Design

Process-global counter

  // meta.rs
  static NEXT_ID: AtomicU64 = AtomicU64::new(0);

Meta::new() stays self-contained — no shared state passed through Context or Supervisor. Multiple supervisors in
the same process share the global automatically.

id: NEXT_ID.fetch_add(1, Ordering::Relaxed)

Relaxed ordering is sufficient — uniqueness comes from atomicity, not memory ordering. On x86 this is a single
lock xadd (~2-5ns).

Replay support

Add a second constructor for replaying recorded events with their original IDs:

  // Normal path
  Meta::new(actor_id, correlation_id)

  // Replay path — preserves original ID from recorded event log
  Meta::with_id(id, actor_id, correlation_id)

New events generated in response to replayed events get fresh counter-based IDs. Correlation chains are
preserved because correlation_id references the original (replayed) IDs.

Cross-process uniqueness

EventId is an internal routing identifier, not a distributed tracing ID. Cross-process identity is the IPC
layer's responsibility (planned for 0.4's maiko-actors crate). When events cross process boundaries, the
transport creates new envelopes with local IDs and uses correlation_id to reference the originals.

API changes

  • pub type EventId = u128 → pub type EventId = u64
  • Meta::with_id(id, actor_id, correlation_id) — new constructor
  • Drop uuid from [dependencies]

Side benefits

  • ~20-40x faster ID generation
  • EventChain can sort by ID directly — remove timestamp-based sorting workaround
  • Better HashMap<EventId, _> cache locality (sequential vs random keys)
  • One fewer dependency
  • Monotonic IDs simplify debugging (event 47 happened before event 48)

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions