Enum TraceEvent 

pub enum TraceEvent {
    TaskSpawned {
        id: u64,
        parent: Option<u64>,
        scope: String,
    },
    TaskCompleted {
        id: u64,
        cpu: Duration,
    },
    TaskCancelled {
        id: u64,
    },
    HostCall {
        task: u64,
        module: String,
        op: String,
        capability: String,
        wait: Duration,
        granted: bool,
        args: Vec<RecordedValue>,
        outcome: Option<HostOutcome>,
    },
    HeapCollected {
        task: u64,
        allocated: u64,
        freed: u64,
        live_objects: u64,
        live_bytes: u64,
        pause: Duration,
    },
    HeapSummary {
        collections: u64,
        object_count: Option<u64>,
        allocated_bytes: Option<u64>,
        live_bytes: Option<u64>,
        peak_bytes: Option<u64>,
        pause: Option<Duration>,
        allocated_words: Option<u64>,
        capacity_words: Option<u64>,
        live_words: Option<u64>,
    },
    EntryEnter {
        module: String,
        function: String,
    },
    EntryExit {
        module: String,
        function: String,
        cpu: Duration,
        wait: Duration,
    },
    RunEnded {
        outcome: RunOutcome,
        message: Option<String>,
    },
}

One recorded runtime event.

Variants

TaskSpawned

A task was created in scope, as a child of parent (or none, for a root task).

Fields

id: u64

parent: Option<u64>

scope: String

TaskCompleted

A task ran to completion, having spent cpu executing (not waiting on a host call).

Fields

id: u64

cpu: Duration

TaskCancelled

A task was cancelled before it completed.

Fields

id: u64

HostCall

A Host API call was dispatched (granted: true) or rejected (granted: false), after waiting wait for the host to respond. For a rejected call, wait is the time spent deciding to reject it, which is ordinarily negligible.

args are the arguments the program passed, and outcome is what the host answered — None for a call that never reached a host, so there was nothing to answer. Together they are what makes the call reproducible.

task is the task that made the call, which is what lets a trace of a run with concurrent tasks be grouped by whose I/O each call was. The entry made its own calls under crate::runtime::ENTRY_TASK.

Fields

task: u64

module: String

op: String

capability: String

wait: Duration

granted: bool

args: Vec<RecordedValue>

outcome: Option<HostOutcome>

HeapCollected

One task’s heap was collected.

ADR 0001 asks a trace to make allocation and memory pressure visible, and ADR 0011 makes this the event that does it. Allocation is reported as the count since the previous collection rather than as one event per object: an event per allocation would be most of the trace, and would tell a reader less about pressure than the pair of numbers that bracket it — what was allocated, and what survived.

A heap belongs to one task, so this event says whose it was, and two tasks collecting at the same time produce two independent events.

Fields

task: u64

The task whose heap this was, or crate::runtime::ENTRY_TASK for the entry’s own.

allocated: u64

Objects allocated since the previous collection.

freed: u64

Objects this collection reclaimed.

live_objects: u64

Objects live after it.

live_bytes: u64

Bytes live after it.

pause: Duration

How long the task was stopped.

HeapSummary

What every heap in the run did, recorded once as the run ends.

Every figure but collections is optional, and that is issue #240’s decision rather than laxity. The two evaluators do not have the same kind of heap: the interpreter’s is a set of Rc-ed objects and it counts objects and the bytes they asked for, while the linear-memory backend’s is a run of eight-byte words and it counts words. Neither figure can be derived from the other — an inline struct is words in one and no object at all in the other — so the event carries both families and a machine leaves None in the ones it does not count. A zero there would read as a measurement of nothing rather than as the absence of a measurement, which is the same distinction cove run --stats draws.

Fields

collections: u64

How many collections ran, over every heap of the run.

The one figure both machines count, and the one that is not optional: a collection is a collection whatever the heap holds.

object_count: Option<u64>

Collectable objects allocated over the whole run, by every task.

allocated_bytes: Option<u64>

Bytes those allocations asked for.

live_bytes: Option<u64>

Bytes live when the run ended. Every heap is swept once more as it is retired, so this is what the entry was still holding after its own last sweep — usually nothing.

peak_bytes: Option<u64>

The largest live set any one collection measured.

pause: Option<Duration>

Total time tasks were stopped for collection, summed over threads, so a run with four tasks collecting at once can report more pause than it took wall-clock time.

allocated_words: Option<u64>

Words handed out over the whole run, reuse counted each time.

Cumulative rather than present: it is what the run asked the allocator for, so a loop that allocates and drops shows the work it did rather than the nothing it kept.

capacity_words: Option<u64>

Words the heap region occupies, free blocks included.

live_words: Option<u64>

Words held by objects that survived the run’s last collection, and None when no collection ran, because there is then nothing that measured it.

EntryEnter

A host-selected entry function began running.

Fields

module: String

function: String

EntryExit

A host-selected entry function finished, having spent cpu executing and wait waiting on host calls.

Fields

module: String

function: String

cpu: Duration

wait: Duration

RunEnded

The run ended, and this is how. The last event of every trace.

TraceEvent::EntryExit says what an entry that got as far as running spent; this says how the whole run came out, including for a run that never reached its entry at all. There is one per run because there is one entry per run: a task that ends is already three events of its own, and a task’s failure does not decide the run’s — it reaches whoever joined it, and either stops the run, which this event then reports with that task’s own message, or is handled, in which case no terminal classification would have been true of it.

Fields

outcome: RunOutcome

message: Option<String>

Why, for an outcome that has a why: the Error the entry returned, or the message of the error that stopped the run. None for a run that succeeded.

Trait Implementations

impl Clone for TraceEvent

fn clone(&self) -> TraceEvent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for TraceEvent

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

Formats the value using the given formatter.