Crate commonware_runtime 

Execute asynchronous tasks with a configurable scheduler.

This crate provides a collection of runtimes that can be used to execute asynchronous tasks in a variety of ways. For production use, the tokio module provides a runtime backed by Tokio. On Linux, the iouring module provides a runtime backed by io_uring. Each worker in its pool drives its tasks and I/O together on its own ring, and the first runs on the calling thread. The mimalloc feature exports mimalloc’s allocator statistics as runtime metrics when the process’s global allocator is commonware_allocator::mimalloc::MiMalloc. For testing and simulation, the deterministic module provides a runtime that allows for deterministic execution of tasks (given a fixed seed).

Terminology

Each runtime is typically composed of an Executor and a Context. The Executor implements the Runner trait and drives execution of a runtime. The Context implements any number of the other traits to provide core functionality.

Status

Stability varies by primitive. See README for details.

Re-exports

pub use iobuf::Builder as IoBufsBuilder;

pub use iobuf::IoBuf;

pub use iobuf::IoBufMut;

pub use iobuf::IoBufs;

pub use iobuf::IoBufsMut;

pub use utils::*;

Modules

benchmarks

Utilities for running benchmarks.

deterministic

A deterministic runtime that randomly selects tasks to run based on a seed

iobuf

Buffer types for I/O operations.

iouring

Task execution and I/O on Linux io_uring.

mocks

Mock implementations of runtime primitives for testing.

telemetry

Utilities for collecting and reporting telemetry data.

tokio

A production-focused runtime based on Tokio with secure randomness and storage backed by the local filesystem.

utils

Utility functions for interacting with any runtime.

Macros

spawn_cell

Spawn a task using a Cell by taking its context, restoring the context synchronously in the spawned closure, and returning the provided future directly to the runtime.

spawn_metrics

Prepare metrics for a spawned task.

Structs

BlobVersion

Application-owned version of a Blob’s contents.

Name

The full identity of a Supervisor handle.

Quota

Re-export of governor::Quota for rate limiting configuration. A rate-limiting quota.

ReadOptions

Options that alter one Blob::read_at, Blob::read_at_buf, or Blob::read_many operation.

WriteOptions

Options that alter one Blob::write_at operation.

Enums

BlobLayout

Runtime-owned layout of a Blob.

Error

Errors that can occur when interacting with the runtime.

Constants

BLOB_PAGE_SIZE

Size in bytes of a blob page, the smallest unit in which storage is expected to read and persist Blob data.

DEFAULT_BLOB_LAYOUT

Latest supported BlobLayout, used to create new Blobs unless the runtime restricts layouts to an older range.

DEFAULT_BLOB_VERSION

Default application-owned Blob contents version used by Storage::open.

Traits

Blob

Interface to read and write to a blob.

Buf

Re-export of Buf and BufMut traits for usage with I/O buffers. Read bytes from a buffer.

BufMut

Re-export of Buf and BufMut traits for usage with I/O buffers. A trait for values that provide sequential write access to bytes.

Clock

Interface that any task scheduler must implement to provide time-based operations.

Listener

Interface that any runtime must implement to handle incoming network connections.

Metrics

Interface to register and encode metrics.

Network

Interface that any runtime must implement to create network connections.

Resolver

Interface for DNS resolution.

Runner

Interface that any task scheduler must implement to start running tasks.

Sink

Interface that any runtime must implement to send messages over a network connection.

Spawner

Interface that any task scheduler must implement to spawn tasks.

Storage

Interface to interact with storage.

Strategizer

Interface that runtimes implement to provide parallel execution strategies.

Stream

Interface that any runtime must implement to receive messages over a network connection.

Supervisor

Interface to track task hierarchy and identity.

Type Aliases

KeyedRateLimiter

A rate limiter keyed by K using the provided governor::clock::Clock C.

ListenerOf

Syntactic sugar for the type of Listener used by a given Network N.

RateLimiter

A direct (non-keyed) rate limiter using the provided governor::clock::Clock C.

SinkOf

Syntactic sugar for the type of Sink used by a given Network N.

StreamOf

Syntactic sugar for the type of Stream used by a given Network N.