commonware_runtime/tokio/
mod.rs

1//! A production-focused runtime based on [Tokio](https://tokio.rs) with
2//! secure randomness and storage backed by the local filesystem.
3//!
4//! # Panics
5//!
6//! Unless configured otherwise, any task panic will lead to a runtime panic.
7//! This includes panics raised while dropping a task's future or output,
8//! after which a handle still awaiting the task resolves to
9//! [crate::Error::Closed].
10//!
11//! # Storage
12//!
13//! [crate::Runner::start] holds the storage directory (an advisory lock on its
14//! `.hold` file) until the run's storage and every operation it dispatched have
15//! finished. A start on a directory another run still holds blocks, with a
16//! warning, until then. A `Context`, `Storage`, or `Blob` kept past `start`
17//! keeps the hold.
18//!
19//! Before user code starts, Linux flushes the storage filesystem. Other
20//! platforms synchronize the storage directory, then each existing partition
21//! before its first scan or open. These directory flushes make inherited
22//! partition and blob removals durable before a scan or open observes their
23//! absence. Creation and removal synchronize subsequent directory changes.
24//!
25//! Other platforms also flush existing blobs individually on their first open.
26//! Directory synchronization covers names. This separate flush covers file
27//! data. On macOS, both use `F_FULLFSYNC` through [`std::fs::File::sync_all`].
28//!
29//! Failures while synchronizing blob contents, including during
30//! [SYNC](crate::WriteOptions::SYNC) writes, are retained across opens of the
31//! blob, even after every handle is dropped. Creation failures are retained
32//! when the header is complete. Removing or recreating the blob clears its
33//! retained error. A new runtime instance starts without the error record and
34//! still requires normal storage recovery.
35//!
36//! # Example
37//!
38//! ```rust
39//! use commonware_runtime::{Spawner, Runner, Supervisor, tokio, Metrics};
40//!
41//! let executor = tokio::Runner::default();
42//! executor.start(|context| async move {
43//!     println!("Parent started");
44//!     let result = context.child("child").spawn(|_| async move {
45//!         println!("Child started");
46//!         "hello"
47//!     });
48//!     println!("Child result: {:?}", result.await);
49//!     println!("Parent exited");
50//! });
51//! ```
52
53mod runtime;
54pub use runtime::*;
55pub mod telemetry;
56pub mod tracing;
commonware_runtime/tokio/mod.rs

commonware_runtime/tokio/
mod.rs
