sansio_executor/
lib.rs

1//! # SansIO Executor - Tokio-based Executor
2//!
3//! `sansio-executor` provides a tokio-based local executor for the sansio ecosystem.
4//!
5//! ## Features
6//!
7//! - **Tokio LocalSet**: Built on tokio's LocalSet for single-threaded task execution
8//! - **CPU Pinning**: Pin executor threads to specific CPU cores
9//! - **Thread Naming**: Name executor threads for debugging
10//! - **Task Management**: Spawn, detach, and cancel tasks
11//!
12//! ## Quick Start
13//!
14//! ```toml
15//! [dependencies]
16//! sansio-executor = "0.0.7"
17//! ```
18//!
19//! ```rust,no_run
20//! use sansio_executor::LocalExecutorBuilder;
21//!
22//! LocalExecutorBuilder::default()
23//!     .run(async {
24//!         println!("Running on tokio!");
25//!     });
26//! ```
27//!
28//! ## CPU Pinning
29//!
30//! ```rust,no_run
31//! use sansio_executor::LocalExecutorBuilder;
32//! use core_affinity::CoreId;
33//!
34//! LocalExecutorBuilder::new()
35//!     .name("my-executor")
36//!     .core_id(CoreId { id: 0 })
37//!     .run(async {
38//!         println!("Running on CPU core 0!");
39//!     });
40//! ```
41//!
42//! ## Spawning Local Tasks
43//!
44//! ```rust,no_run
45//! use sansio_executor::{LocalExecutorBuilder, spawn_local};
46//!
47//! LocalExecutorBuilder::default().run(async {
48//!     let task1 = spawn_local(async {
49//!          println!("Task 1");
50//!          42
51//!     });
52//!
53//!     let task2 = spawn_local(async {
54//!          println!("Task 2");
55//!          100
56//!     });
57//!
58//!     let result1 = task1.await.unwrap();
59//!     let result2 = task2.await.unwrap();
60//!
61//!     println!("Results: {}, {}", result1, result2);
62//! });
63//! ```
64//!
65//! ## API
66//!
67//! The main exports are:
68//!
69//! - [`LocalExecutorBuilder`]: Builder for configuring and creating executors
70//! - [`spawn_local()`]: Spawn a task on the current executor, returns a [`Task`]
71//! - [`yield_local()`]: Yield to other tasks
72//! - [`Task<T>`]: A handle to a spawned task, implements `Future<Output = Result<T, TaskError>>`
73//! - [`TaskError`]: Error type returned when a task fails (panic or cancellation)
74//!
75//! ## Task Execution
76//!
77//! Tasks spawned with [`spawn_local()`] return a [`Task<T>`] handle that can be awaited:
78//!
79//! ```rust,no_run
80//! use sansio_executor::{LocalExecutorBuilder, spawn_local};
81//!
82//! LocalExecutorBuilder::default().run(async {
83//!     let task = spawn_local(async { 42 });
84//!
85//!     // Task implements Future<Output = Result<T, TaskError>>
86//!     match task.await {
87//!         Ok(result) => println!("Task completed: {}", result),
88//!         Err(e) => eprintln!("Task failed: {}", e),
89//!     }
90//! });
91//! ```
92//!
93//! ## Detaching Tasks
94//!
95//! Tasks can be detached to run in the background without awaiting them:
96//!
97//! ```rust,no_run
98//! use sansio_executor::{LocalExecutorBuilder, spawn_local};
99//!
100//! LocalExecutorBuilder::default().run(async {
101//!     let task = spawn_local(async {
102//!         println!("Running in background");
103//!     });
104//!
105//!     // Detach - task continues running even though we don't await it
106//!     task.detach();
107//! });
108//! ```
109//!
110//! ## Error Handling
111//!
112//! Tasks can fail if they panic or are cancelled/aborted. The [`TaskError`] type
113//! wraps tokio's `JoinError` and provides error information.
114
115#![doc(
116    html_logo_url = "https://raw.githubusercontent.com/webrtc-rs/sansio/master/doc/sansio-white.png"
117)]
118#![warn(rust_2018_idioms)]
119#![allow(dead_code)]
120#![warn(missing_docs)]
121
122mod tokio;
123pub use tokio::*;
sansio_executor/lib.rs

sansio_executor/
lib.rs
