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
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
//! Public runtime errors and panic reports.
#[path = "error_display.rs"]
mod error_display;
use std::{any::Any, io};
pub use crate::scope_failure::ScopeFailure;
pub use crate::scope_failure_report::{FailureKind, FailureReport, ScopeFailureReport};
#[path = "error_types.rs"]
mod error_types;
pub use error_types::{ConfigurationField, LimitResource};
#[path = "run_error.rs"]
mod run_error;
use crate::{TaskFailure, TaskId};
pub use run_error::{RunFailure, ScopeRunError};
#[path = "application_run_failure.rs"]
mod application_run_failure;
pub use application_run_failure::ApplicationRunFailure;
#[path = "runtime_build_failure.rs"]
mod runtime_build_failure;
pub use runtime_build_failure::RuntimeBuildFailure;
#[path = "error_context.rs"]
mod error_context;
pub use error_context::{CapacityResource, FaultComponent, IoFailure, RuntimeFault};
/// The result type returned by `vthread` operations.
pub type Result<T> = std::result::Result<T, Error>;
/// A stable, transportable description of a task panic.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct PanicReport {
captured: vthread_stack::panic_payload::CapturedPanic,
}
impl PanicReport {
pub(crate) fn capture(payload: Box<dyn Any + Send>) -> Self {
Self {
captured: vthread_stack::panic_payload::capture(payload),
}
}
pub(crate) fn from_captured(captured: vthread_stack::panic_payload::CapturedPanic) -> Self {
Self { captured }
}
/// Returns the panic message or a fallback for non-string payloads.
pub fn message(&self) -> &str {
&self.captured.message
}
/// Whether the original message exceeded the 1024-byte UTF-8 text limit.
pub fn truncated(&self) -> bool {
self.captured.truncated
}
/// Whether disposing of the panic payload itself panicked and failed its owner.
pub fn cleanup_panicked(&self) -> bool {
self.captured.cleanup_panicked
}
}
/// A runtime, scheduling, parking, or task failure.
#[derive(Debug)]
#[non_exhaustive]
pub enum Error {
/// A socket, filesystem, resolver, or readiness backend operation failed.
Io(IoFailure),
/// The readiness driver stopped after a backend failure.
ReadinessFailed,
/// A native worker failed and its pool no longer accepts work.
BlockingFailed,
/// A bounded I/O result exceeded its requested limit.
LimitExceeded {
/// Which result was bounded.
resource: LimitResource,
/// Configured maximum size or count.
limit: usize,
},
/// A delegated blocking operation panicked.
BlockingPanicked(PanicReport),
/// A synchronization primitive or channel no longer accepts this operation.
Closed,
/// A nonblocking synchronization operation cannot complete immediately.
WouldBlock,
/// This handle's terminal result has already been consumed.
ResultAlreadyTaken,
/// The current task or an ancestor scope requested cancellation.
Cancelled,
/// The earliest inherited deadline expired at a runtime boundary.
DeadlineExceeded,
/// A task-local initializer tried to read the same key before initialization completed.
RecursiveTaskLocal,
/// Fallible reservation could not grow an explicitly bounded result buffer.
AllocationFailed {
/// Bounded resource being allocated.
resource: LimitResource,
/// Requested total buffer capacity in bytes.
requested: usize,
},
/// A builder value violates the runtime contract.
InvalidConfiguration {
/// Name of the invalid field.
field: ConfigurationField,
/// Human-readable constraint.
message: &'static str,
},
/// A bounded resource reached its admission limit.
Capacity {
/// Which resource rejected the request.
resource: CapacityResource,
/// Configured admission limit.
limit: usize,
},
/// A scope was entered while another scope was active on the runtime.
RootScopeActive,
/// The scope or supervisor has closed transferable child admission.
ScopeClosed,
/// The runtime no longer accepts work.
RuntimeStopped,
/// A structured scope retained body, cleanup, policy or child failures.
ScopeFailed(std::sync::Arc<crate::ScopeFailure>),
/// All runtime threads were joined, but one or more owned components failed.
ShutdownFailed(Box<crate::ShutdownReport>),
/// The process lifecycle service failed; unfinished threads remain process-owned.
LifecycleFailed(Box<crate::ThreadFailure>),
/// Both the application scope and explicit shutdown failed.
RunFailed(Box<RunFailure>),
/// Runtime construction and explicit cleanup both failed. Both causes are retained.
ConstructionFailed(Box<RuntimeBuildFailure>),
/// A blocking runtime operation was called from a virtual thread.
InsideVThread,
/// A managed runtime thread attempted an operation reserved for ordinary OS callers.
InsideManagedWorker,
/// An owned operating-system thread could not be created.
ThreadStart {
/// Component that could not start.
component: crate::ThreadComponent,
/// Original operating-system error.
source: io::Error,
},
/// A task attempted to wait for itself.
JoinSelf,
/// A child stack was reclaimed without a normal result.
TaskAborted {
/// Identity of the aborted task.
task: TaskId,
/// Why the task was reclaimed.
reason: TaskFailure,
},
/// Suspension was attempted without a mounted virtual thread.
OutsideVThread,
/// One parker was asked to own two active generations simultaneously.
ParkerBusy,
/// A relative duration could not be represented as a monotonic deadline.
DeadlineOverflow,
/// A guard-page-backed stack could not be allocated.
StackAllocation(io::Error),
/// A joined or unobserved child task panicked.
TaskPanicked {
/// Identity of the failed task.
task: TaskId,
/// Operator-visible task name.
name: String,
/// Captured panic description.
panic: PanicReport,
},
/// Live tasks existed but no runnable task or timer could make progress.
RuntimeStalled {
/// Number of live tasks at the point of failure.
active: usize,
},
/// An internal fault with opaque incident identity and component metadata.
Fault(RuntimeFault),
}
impl Error {
/// Returns structured scope details without discarding any secondary failure.
pub fn scope_failure(&self) -> Option<&crate::ScopeFailure> {
if let Self::ScopeFailed(failure) = self {
Some(failure)
} else {
None
}
}
/// Returns the representative causal error through any enclosing scope failures.
/// Inspect scope_failure as well when secondary failures affect recovery.
pub fn primary(&self) -> &Self {
let mut current = self;
while let Self::ScopeFailed(failure) = current {
let Some(next) = failure.primary() else {
break;
};
current = next;
}
current
}
pub(crate) fn fault(component: FaultComponent, detail: &'static str) -> Self {
Self::Fault(RuntimeFault::new(component, detail))
}
pub(crate) fn io(
operation: &'static str,
context: impl std::fmt::Display,
source: io::Error,
) -> Self {
Self::Io(IoFailure::new(operation, context, source))
}
pub(crate) fn thread_start(component: crate::ThreadComponent, source: io::Error) -> Self {
Self::ThreadStart { component, source }
}
pub(crate) fn invalid_configuration(field: ConfigurationField, message: &'static str) -> Self {
Self::InvalidConfiguration { field, message }
}
pub(crate) fn task_panicked(task: TaskId, name: String, panic: PanicReport) -> Self {
Self::TaskPanicked { task, name, panic }
}
}
#[cfg(test)]
#[path = "error_test.rs"]
mod error_test;