Struct topo::CallId

pub struct CallId { /* fields omitted */ }

Identifies the scope of a nested function call in a way that can be deterministically reproduced across multiple executions.

The CallId::current for a function call is the combined product of:

• a callsite: the std::panic::Location where the function was called
• a parent: the CallId::current which was active when calling the function
• a slot: a value indicating the call's "index" within the parent call

When a nested call returns or unwinds, it reverts CallId::current to the parent CallId.

Example

use topo::{call, root, CallId};

let returns_two_ids = || {
    let first = call(|| CallId::current());
    let second = call(|| CallId::current());
    assert_ne!(first, second, "these are always distinct calls");
    (first, second)
};

// running the closure as a nested call(...) gives different siblings
assert_ne!(call(returns_two_ids), call(returns_two_ids));

// a call to root(...) gives each of these closure calls an identical parent CallId
assert_eq!(root(returns_two_ids), root(returns_two_ids));

Creation

Every CallId is created by calling one of:

• a function marked nested
• a function passed to call
• a function and slot passed to call_in_slot

Slots

Slots are used to differentiate between repeated calls at the same callsite and define the "index" of a child call within its parent. By default (and in call) the slot is populated by the number of times the current callsite has been called in this parent. Users can provide their own slot with call_in_slot or using #[topo::nested(slot = "...")]:

See call_in_slot and nested for examples.

Roots

The topmost parent or "root" of a callgraph can be defined in two ways:

1. a call or call_in_slot invocation with no parent implicitly creates its own root
2. an explicit call to root creates a new subgraph regardless of the current parent

See root for examples.

CallId and multiple threads

The illicit environment used for tracking the current CallId is thread-local, but values used to track slots are interned in a global cache. This means that two different threads calling an identical chain of nested functions can observe identical CallIds:

use std::{
    sync::mpsc::{channel, Sender},
    thread,
};

let (send_ids, recv_ids) = channel();

let spawn_worker = |sender: Sender<(CallId, CallId)>| {
    thread::spawn(move || sender.send(root(returns_two_ids)).unwrap())
};
let first_thread = spawn_worker(send_ids.clone());
let second_thread = spawn_worker(send_ids);

first_thread.join().unwrap();
second_thread.join().unwrap();

// the two worker threads "did the same work"
assert_eq!(recv_ids.recv()?, recv_ids.recv()?);

Implementations

impl CallId

pub fn current() -> Self

Returns the current CallId.

Trait Implementations

impl Clone for CallId

fn clone(&self) -> CallId

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for CallId

impl Debug for CallId

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

Formats the value using the given formatter.

impl Eq for CallId

impl Hash for CallId

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, 

Feeds a slice of this type into the given [Hasher].

impl PartialEq<CallId> for CallId

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl StructuralEq for CallId

impl StructuralPartialEq for CallId