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
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
//! Stop requests and deadline-bounded observation of a single owned join operation.
use super::Runtime;
use crate::{
Error, Result, RuntimeSnapshot, ShutdownPhase, ShutdownReport, context, control::Shared,
};
use std::{
sync::{
Arc,
atomic::{AtomicBool, Ordering},
},
time::Instant,
};
pub(super) struct ShutdownDriver {
ready: Arc<AtomicBool>,
}
impl ShutdownDriver {
pub(super) fn new(shared: &Arc<Shared>) -> Result<Self> {
let ready = Arc::new(AtomicBool::new(false));
let constructed = Arc::clone(&ready);
let shared = Arc::clone(shared);
let resources = Arc::clone(&shared.resources);
let cleanup = Arc::clone(&resources);
crate::lifecycle_owner::start(Arc::clone(&shared), resources, move || {
loop {
let observed = shared.changed.version();
if constructed.load(Ordering::Acquire)
&& shared.shutdown_phase() != ShutdownPhase::NotRequested
{
break;
}
shared.changed.wait(observed, None);
}
#[cfg(test)]
assert!(
!shared.fail_coordinator_before_drain.load(Ordering::Relaxed),
"injected coordinator failure before cleanup"
);
shared.advance_shutdown(ShutdownPhase::JoiningCarriers);
cleanup
.workers
.join_all(&Arc::downgrade(&shared), crate::ThreadComponent::Carrier);
// A retained affine stack may own a native-result acknowledgement. Joining
// services then could wait forever; let the process owner fail stop now.
if !cleanup.carriers_reclaimed(&shared) {
return;
}
drain_services(&shared);
#[cfg(test)]
if let Some(hook) = crate::signal::lock(&shared.coordinator_exit_hook).take() {
hook();
}
// Only the process owner may publish completion, after joining this thread.
})?;
Ok(Self { ready })
}
pub(super) fn ready(&self, shared: &Shared) {
self.ready.store(true, Ordering::Release);
shared.changed.notify();
}
}
/// Result of a deadline-based runtime shutdown wait.
#[derive(Clone, Debug)]
#[non_exhaustive]
#[must_use = "Inspect timeout diagnostics and retain the owner until shutdown completes"]
pub enum ShutdownOutcome {
/// Every carrier, service and coordinator has been joined, including OS TLS cleanup.
/// Its process lifecycle admission slot is released. Caller-owned root callbacks
/// may still be executing on other OS threads.
Complete(ShutdownReport),
/// Work remains runtime-owned; the deadline expired without detaching any thread.
TimedOut(Box<RuntimeSnapshot>),
}
impl Runtime {
/// Stops admission and requests cancellation without joining or running user destructors.
///
/// Idempotent and safe from managed workers. A request is not completion: ordinary
/// OS callers use `shutdown` or `shutdown_until` to wait. Metadata locks and wake
/// delivery are not hard real-time operations.
pub fn request_shutdown(&self) {
self.shared.request_stop();
}
/// Stops admission, reclaims tasks, and waits for the single owned join operation.
///
/// CPU loops, native calls, FFI, and destructors can delay completion indefinitely.
/// No virtual thread or managed native worker may wait, including foreign workers.
/// A failed process lifecycle service returns `Error::LifecycleFailed` promptly;
/// unfinished coordinators stay process-owned and cleanup is not claimed complete.
/// Terminal shutdown also releases this runtime's process lifecycle admission slot.
/// Root callbacks belong to ordinary OS callers and may continue after shutdown;
/// each `run_scope` invocation waits for its own callback to return. Shutdown cannot
/// forcibly terminate callback code or wait for callbacks that can themselves stop it.
pub fn shutdown(&self) -> Result<ShutdownReport> {
self.check_shutdown_caller()?;
self.request_shutdown();
self.wait_shutdown(None)?;
Ok(self.shutdown_report())
}
/// Requests shutdown and observes completion up to an absolute monotonic deadline.
///
/// An expired deadline checks completion once. Timeout retains every unfinished
/// thread under the process lifecycle owner's bounded ownership; callers can retry.
/// One coordinator is established before runtime workers start. Final-owner Drop on
/// an ordinary OS thread waits; on any managed worker it only requests shutdown.
/// The process service retains and joins the coordinator, including OS TLS cleanup.
/// Service failure returns `Error::LifecycleFailed` without waiting for the deadline.
/// Scheduling and metadata locks are not a hard real-time guarantee.
/// Completion releases lifecycle capacity but does not wait for caller-owned root
/// callbacks on other OS threads; their scope invocations await their own return.
///
/// ```
/// use std::time::{Duration, Instant};
/// use vthread::{Runtime, lifecycle::ShutdownOutcome};
/// let runtime = Runtime::new()?;
/// match runtime.shutdown_until(Instant::now() + Duration::from_secs(1))? {
/// ShutdownOutcome::Complete(report) => assert_eq!(report.failed_carriers(), 0),
/// ShutdownOutcome::TimedOut(snapshot) => assert!(!snapshot.accepting()),
/// _ => runtime.shutdown().map(|_| ())?,
/// }
/// # Ok::<(), vthread::Error>(())
/// ```
pub fn shutdown_until(&self, deadline: Instant) -> Result<ShutdownOutcome> {
self.check_shutdown_caller()?;
self.request_shutdown();
if self.wait_shutdown(Some(deadline))? {
Ok(ShutdownOutcome::Complete(self.shutdown_report()))
} else {
Ok(ShutdownOutcome::TimedOut(Box::new(self.snapshot())))
}
}
pub(super) fn wait_shutdown(&self, deadline: Option<Instant>) -> Result<bool> {
loop {
let observed = self.shared.changed.version();
match self.shared.shutdown_phase() {
ShutdownPhase::Complete => return Ok(true),
ShutdownPhase::Failed => {
return Err(Error::ShutdownFailed(Box::new(self.shutdown_report())));
}
_ => {}
}
crate::lifecycle_owner::check_health()?;
if deadline.is_some_and(|end| Instant::now() >= end) {
return Ok(false);
}
self.shared.changed.wait(observed, deadline);
}
}
fn check_shutdown_caller(&self) -> Result<()> {
if context::current().is_some() {
return Err(Error::InsideVThread);
}
if crate::worker_context::is_managed() {
return Err(Error::InsideManagedWorker);
}
Ok(())
}
fn shutdown_report(&self) -> ShutdownReport {
let snapshot = self.snapshot();
ShutdownReport {
failures: snapshot.failures,
completed: snapshot.stats.completed,
panicked: snapshot.stats.panicked,
aborted: snapshot.stats.aborted,
failed_carriers: snapshot
.carriers
.iter()
.filter(|carrier| carrier.status == crate::CarrierStatus::Failed)
.count(),
}
}
}
fn drain_services(shared: &Shared) {
if let Some(services) = shared.services.get() {
// A stop request can race publication during runtime construction.
services.stop();
shared.advance_shutdown(ShutdownPhase::JoiningReadiness);
services.reactor.join();
shared.advance_shutdown(ShutdownPhase::JoiningNative);
services.blocking.join();
}
}
#[cfg(test)]
#[path = "runtime_lifecycle_test.rs"]
mod runtime_lifecycle_test;
#[cfg(test)]
#[path = "runtime_ownership_test.rs"]
mod runtime_ownership_test;