libdd_shared_runtime/
lib.rs

1// Copyright 2026-Present Datadog, Inc. https://www.datadoghq.com/
2// SPDX-License-Identifier: Apache-2.0
3#![cfg_attr(not(test), deny(clippy::panic))]
4#![cfg_attr(not(test), deny(clippy::unwrap_used))]
5#![cfg_attr(not(test), deny(clippy::expect_used))]
6#![cfg_attr(not(test), deny(clippy::todo))]
7#![cfg_attr(not(test), deny(clippy::unimplemented))]
8
9//! A shared tokio runtime for running background workers across multiple components.
10//!
11//! Components such as the trace exporter can share one runtime instead of each creating their
12//! own, reducing thread and resource overhead.
13//!
14//! # Choosing a runtime
15//!
16//! | Runtime             | Target | Threads | Fork-safe           | `block_on` | When to use                                                                                                                                 |
17//! |---------------------|--------|---------|---------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------|
18//! | [`ForkSafeRuntime`] | native | multi   | yes — full protocol | yes        | Default for native code that may run in a forking process (e.g. Ruby, Python runtimes).                                                     |
19//! | [`BasicRuntime`]    | native | multi*  | no                  | yes        | Native code where `fork()` is not a concern; optionally share an existing `Arc<tokio::runtime::Runtime>` via [`BasicRuntime::from_handle`]. |
20//! | [`LocalRuntime`]    | wasm32 | single  | n/a                 | no         | WebAssembly; spawns via `wasm_bindgen_futures::spawn_local`.                                                                                |
21//!
22//! \* [`BasicRuntime::new`] and [`BasicRuntime::with_worker_threads`] build a multi-thread runtime;
23//! [`BasicRuntime::from_handle`] accepts any `Arc<tokio::runtime::Runtime>`, including
24//! single-thread ones.
25//!
26//! ## Fork protocol ([`ForkSafeRuntime`] only)
27//!
28//! Call these around every `fork()` to prevent deadlocks in child processes:
29//!
30//! 1. [`ForkSafeRuntime::before_fork`] — pauses workers
31//! 2. `fork()`
32//! 3. parent: [`ForkSafeRuntime::after_fork_parent`] — resumes workers
33//! 4. child: [`ForkSafeRuntime::after_fork_child`] — restarts workers on a fresh runtime
34
35pub mod shared_runtime;
36mod weak_waker;
37pub mod worker;
38
39// Top-level re-exports for convenience
40#[cfg(not(target_arch = "wasm32"))]
41pub use shared_runtime::BasicRuntime;
42#[cfg(not(target_arch = "wasm32"))]
43pub use shared_runtime::BlockOnTimeoutError;
44#[cfg(not(target_arch = "wasm32"))]
45pub use shared_runtime::BlockingRuntime;
46#[cfg(not(target_arch = "wasm32"))]
47pub use shared_runtime::ForkSafeRuntime;
48#[cfg(target_arch = "wasm32")]
49pub use shared_runtime::LocalRuntime;
50pub use shared_runtime::{SharedRuntime, SharedRuntimeError, WorkerHandle, WorkerHandleError};
51pub use worker::Worker;
libdd_shared_runtime/lib.rs

libdd_shared_runtime/
lib.rs
