1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
//! Runtime lifecycle and structured ownership of persistent carrier threads.
#[path = "runtime_build.rs"]
mod runtime_build;
#[path = "runtime_lifecycle.rs"]
mod runtime_lifecycle;
#[path = "runtime_scope.rs"]
mod runtime_scope;
pub use runtime_lifecycle::ShutdownOutcome;
use crate::{Result, RuntimeBuilder, RuntimeConfig, RuntimeSnapshot, context, control::Shared};
use std::{fmt, sync::Arc};
/// An application lifecycle owner with one active root scope and persistent affine carriers.
/// Explicit supervisors may coexist with that root; independent roots use separate runtimes.
/// Task groups and supervisors share this runtime's workers, rather than creating new ones.
/// Each runtime owns `carriers + blocking_threads + 2` OS threads (five by default), plus
/// one process-shared lifecycle owner. See [`RuntimeBuilder`] for thread/stack costs and
/// [`crate::lifecycle::LIFECYCLE_CAPACITY`] for the fixed process admission bound.
///
/// Root callbacks run on their ordinary OS callers, not on runtime workers. Shutdown
/// reclaims runtime-owned children and joins workers, services and the coordinator;
/// a concurrent root callback may continue afterward. Its `run_scope` invocation
/// returns only when that callback returns. Shutdown cannot forcibly terminate it.
pub struct Runtime {
config: RuntimeConfig,
pub(crate) shared: Arc<Shared>,
shutdown_driver: runtime_lifecycle::ShutdownDriver,
#[cfg(feature = "runtime-evidence")]
evidence: std::sync::Mutex<Option<crate::diagnostics::evidence::EvidenceStream>>,
}
impl Runtime {
/// Returns a builder with bounded defaults and one persistent carrier.
pub fn builder() -> RuntimeBuilder {
RuntimeBuilder::default()
}
/// Creates a runtime with default configuration.
/// Native/OS initialization may block indefinitely; bounded service startup needs
/// a process-level watchdog. The readiness handshake has no wall-clock timeout.
/// Partial initialization is explicitly shut down. If both construction and cleanup
/// fail, [`crate::Error::ConstructionFailed`] retains both causes.
pub fn new() -> Result<Self> {
Self::builder().build()
}
/// Returns the process-unique runtime identity used by diagnostics.
pub fn id(&self) -> crate::diagnostics::RuntimeId {
self.shared.id
}
/// Returns the immutable runtime configuration.
pub fn config(&self) -> RuntimeConfig {
self.config
}
/// Returns a weakly consistent view of carrier state and retained task diagnostics.
/// Components can advance independently while this view is assembled. Task and
/// service observation does not hold the global admission/completion lock.
pub fn snapshot(&self) -> RuntimeSnapshot {
self.shared.snapshot()
}
/// Returns cumulative per-phase scheduler timings for controlled performance tests.
///
/// Read snapshots between scopes and subtract them with
/// [`crate::diagnostics::LifecycleProfile::checked_delta`] for one exact run. Clock reads
/// and atomic accounting add overhead, so this requires the opt-in `lifecycle-profiling`
/// feature and is not a substitute for an uninstrumented end-to-end measurement.
#[cfg(feature = "lifecycle-profiling")]
pub fn lifecycle_profile(&self) -> crate::diagnostics::LifecycleProfile {
self.shared.lifecycle_probe.snapshot()
}
/// Takes the single-consumer evidence stream when recording was configured.
/// Subsequent calls return `None`.
#[cfg(feature = "runtime-evidence")]
pub fn take_evidence(&self) -> Option<crate::diagnostics::evidence::EvidenceStream> {
crate::signal::lock(&self.evidence).take()
}
#[cfg(test)]
pub(crate) fn spawn<T: Send + 'static>(
&self,
scope: u64,
name: String,
entry: impl FnOnce() -> T + Send + 'static,
) -> Result<crate::JoinHandle<T>> {
let spawned = self.shared.submit(scope, name, entry)?;
Ok(crate::JoinHandle::new(
Arc::clone(&self.shared),
spawned.id,
spawned.cell,
spawned.record,
))
}
}
impl Drop for Runtime {
fn drop(&mut self) {
// Also release a coordinator created before a partial construction failure.
self.shutdown_driver.ready(&self.shared);
self.shared.request_stop();
// Any managed worker may participate in a cross-runtime dependency cycle.
// The process lifecycle owner already retains this operation and all handles.
if context::current().is_none() && !crate::worker_context::is_managed() {
let _ = self.wait_shutdown(None);
}
}
}
impl fmt::Debug for Runtime {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("Runtime")
.field("config", &self.config)
.finish_non_exhaustive()
}
}
#[cfg(test)]
#[path = "runtime_test.rs"]
mod runtime_test;