Struct SequenceId

pub struct SequenceId { /* private fields */ }

A hierarchical sequence identifier that exists within a shared universe.

SequenceIds form a collision-free universe where each ID is represented as a vector of indices (e.g., [0, 1, 2]). The API design prevents collisions by only allowing new IDs to be created through controlled advancement or descent operations.

Hierarchy and Ordering

IDs are hierarchical and lexicographically ordered:

• [0] < [0, 0] < [0, 1] < [1] < [1, 0]
• A parent ID like [0, 1] can spawn children [0, 1, 0], [0, 1, 1], etc.
• Sibling IDs are created by advancing: [0, 0] → [0, 1] → [0, 2]

Drop Ordering

When a SequenceId is dropped, it may wake futures waiting for ordering guarantees. The collapse() method leverages this to provide deterministic ordering of recursively created sequence IDs.

Implementations

impl SequenceId

pub fn root() -> SequencePointer

Creates a new root sequence universe starting with ID [0].

Each call to root() creates an independent universe with no ordering guarantees between separate root instances. Within a single universe, all IDs are strictly ordered.

pub fn descend(self) -> SequencePointer

Creates a child sequence by descending one level in the hierarchy.

If this SequenceId has ID [1, 2], this method creates the first child [1, 2, 0] and returns a SequencePointer that can generate siblings [1, 2, 1], [1, 2, 2], etc.

Ownership

This method consumes self, as the parent ID is no longer needed once we’ve descended to work with its children.

pub async fn collapse(self) -> SegmentId

Waits until all SequenceIds with IDs lexicographically smaller than this one are dropped.

This async method provides ordering guarantees by ensuring all “prior” sequences in the universe have been dropped before returning. Combined with the collision-free API, this guarantees that for this universe no sequences lexicographically smaller than this one will ever be created again.

Ordering Guarantee

Once collapse() returns, you can be certain that:

• All sequences with smaller IDs have been dropped
• No new sequences with smaller IDs can ever be created (due to collision prevention)
• The returned SegmentId is monotonically increasing within this universe

Use Cases

This is particularly useful for ordering recursively created work:

• Recursive algorithms that spawn child tasks
• Ensuring deterministic processing order across concurrent operations
• Converting hierarchical sequence identifiers to linear segment identifiers

Returns

A monotonically increasing SegmentId that can be used for ordered storage or processing. Each successful collapse within a universe produces a larger SegmentId than the previous one.

Trait Implementations

impl Debug for SequenceId

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for SequenceId

fn drop(&mut self)

Executes the destructor for this type.

impl Hash for SequenceId

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for SequenceId

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for SequenceId

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for SequenceId

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Eq for SequenceId