Debian Codegraph @

.cargo/vendor/wit-bindgen/src/rt/async_support/waitable.rs

raw
1 //! Generic support for "any waitable" and performing asynchronous operations on
2 //! that waitable.
3
4 use super::cabi;
5 use std::ffi::c_void;
6 use std::future::Future;
7 use std::marker;
8 use std::mem;
9 use std::pin::Pin;
10 use std::ptr;
11 use std::task::{Context, Poll, Waker};
12
13 /// Generic future-based operation on any "waitable" in the component model.
14 ///
15 /// This is used right now to power futures and streams for both read/write
16 /// halves. This structure is driven by `S`, an implementation of
17 /// [`WaitableOp`], which codifies the various state transitions and what to do
18 /// on each state transition.
19 pub struct WaitableOperation<S: WaitableOp> {
20 state: WaitableOperationState<S>,
21 /// Storage for the final result of this asynchronous operation, if it's
22 /// completed asynchronously.
23 completion_status: CompletionStatus,
24 }
25
26 /// Structure used to store the `u32` return code from the canonical ABI about
27 /// an asynchronous operation.
28 ///
29 /// When an asynchronous operation is started and it does not immediately
30 /// complete then this structure is used to asynchronously fill in the return
31 /// code. A `Pin<&mut CompletionStatus>` is used to register a pointer with
32 /// `FutureState` to get filled in.
33 ///
34 /// Note that this means that this type is participating in unsafe lifetime
35 /// management and has properties it needs to uphold as a result. Specifically
36 /// the `PhantomPinned` field here means that `Pin` actually has meaning for
37 /// this structure, notably that once `Pin<&mut CompletionStatus>` is created
38 /// then it's guaranteed the destructor will be run before the backing memory
39 /// is deallocated. That's used in `WaitableOperation` above to share an
40 /// internal pointer of this data structure with `FuturesState` safely. The
41 /// destructor of `WaitableOperation` will deregister from `FutureState` meaning
42 /// that if `FuturesState` has a pointer here then it should be valid .
43 struct CompletionStatus {
44 /// Where the async operation's code is filled in, and `None` until that
45 /// happens.
46 code: Option<u32>,
47
48 waker: Option<Waker>,
49
50 /// This is necessary to ensure that `Pin<&mut CompletionStatus>` carries
51 /// the "pin guarantee", basically to mean that it's not safe to construct
52 /// `Pin<&mut CompletionStatus>` and it must somehow require `unsafe` code.
53 _pinned: marker::PhantomPinned,
54 }
55
56 /// Helper trait to be used with `WaitableOperation` to assist with machinery
57 /// necessary to track in-flight reads/writes on futures.
58 ///
59 /// # Unsafety
60 ///
61 /// This trait is `unsafe` as it has various guarantees that must be upheld by
62 /// implementors such as:
63 ///
64 /// * `S::in_progress_waitable` must always return the same value for the state
65 /// given.
66 pub unsafe trait WaitableOp {
67 /// Initial state of this operation, used to kick off the actual component
68 /// model operation and transition to `InProgress`.
69 type Start;
70
71 /// Intermediate state of this operation when the component model is
72 /// involved but it hasn't resolved just yet.
73 type InProgress;
74
75 /// Result type of this operation.
76 type Result;
77
78 /// Result of when this operation is cancelled.
79 type Cancel;
80
81 /// Starts the async operation.
82 ///
83 /// This method will actually call `{future,stream}.{read,write}` with
84 /// `state` provided. The return code of the intrinsic is returned here
85 /// along with the `InProgress` state.
86 fn start(state: Self::Start) -> (u32, Self::InProgress);
87
88 /// Optionally complete the async operation.
89 ///
90 /// This method will transition from the `InProgress` state, with some
91 /// status code that was received, to either a completed result or a new
92 /// `InProgress` state. This is invoked when:
93 ///
94 /// * a new status code has been received by an async export's `callback`
95 /// * cancellation returned a code to be processed here
96 fn in_progress_update(
97 state: Self::InProgress,
98 code: u32,
99 ) -> Result<Self::Result, Self::InProgress>;
100
101 /// Conversion from the "start" state to the "cancel" result, needed when an
102 /// operation is cancelled before it's started.
103 fn start_cancelled(state: Self::Start) -> Self::Cancel;
104
105 /// Acquires the component-model `waitable` index that the `InProgress`
106 /// state is waiting on.
107 fn in_progress_waitable(state: &Self::InProgress) -> u32;
108
109 /// Initiates a request for cancellation of this operation. Returns the
110 /// status code returned by the `{future,stream}.cancel-{read,write}`
111 /// intrinsic.
112 ///
113 /// Note that this must synchronously complete the operation somehow. This
114 /// cannot return a status code indicating that an operation is pending,
115 /// instead the operation must be complete with the returned code. That may
116 /// mean that this intrinsic can block while figuring things out in the
117 /// component model ABI, for example.
118 fn in_progress_cancel(state: &Self::InProgress) -> u32;
119
120 /// Converts a "completion result" into a "cancel result". This is necessary
121 /// when an in-progress operation is cancelled so the in-progress result is
122 /// first acquired and then transitioned to a cancel request.
123 fn result_into_cancel(result: Self::Result) -> Self::Cancel;
124 }
125
126 enum WaitableOperationState<S: WaitableOp> {
127 Start(S::Start),
128 InProgress(S::InProgress),
129 Done,
130 }
131
132 impl<S> WaitableOperation<S>
133 where
134 S: WaitableOp,
135 {
136 /// Creates a new operation in the initial state.
137 pub fn new(state: S::Start) -> WaitableOperation<S> {
138 WaitableOperation {
139 state: WaitableOperationState::Start(state),
140 completion_status: CompletionStatus {
141 code: None,
142 waker: None,
143 _pinned: marker::PhantomPinned,
144 },
145 }
146 }
147
148 fn pin_project(
149 self: Pin<&mut Self>,
150 ) -> (&mut WaitableOperationState<S>, Pin<&mut CompletionStatus>) {
151 // SAFETY: this is the one method used to project from `Pin<&mut Self>`
152 // to the fields, and the contract we're deciding on is that
153 // `state` is never pinned but the `CompletionStatus` is. That's used
154 // to share a raw pointer with the completion callback with
155 // respect to `Option<u32>` internally.
156 unsafe {
157 let me = self.get_unchecked_mut();
158 (&mut me.state, Pin::new_unchecked(&mut me.completion_status))
159 }
160 }
161
162 /// Registers a completion of `waitable` within the current task's future to:
163 ///
164 /// * Fill in `completion_status` with the result of a completion event.
165 /// * Call `cx.waker().wake()`.
166 pub fn register_waker(self: Pin<&mut Self>, waitable: u32, cx: &mut Context) {
167 let (_, mut completion_status) = self.pin_project();
168 debug_assert!(completion_status.as_mut().code_mut().is_none());
169 *completion_status.as_mut().waker_mut() = Some(cx.waker().clone());
170
171 // SAFETY: There's quite a lot going on here. First is the usage of
172 // `task` below, and for that see `unregister_waker` below for why this
173 // pattern should be safe.
174 //
175 // Otherwise we're handing off a pointer to `completion_status` to the
176 // `task` itself. That should be safe as we're guaranteed, via
177 // `Pin<&mut Self>`, that before `&mut Self` is deallocated the
178 // destructor will be run which will perform de-registration via
179 // cancellation.
180 unsafe {
181 let task = cabi::wasip3_task_set(ptr::null_mut());
182 assert!(!task.is_null());
183 assert!((*task).version >= cabi::WASIP3_TASK_V1);
184 let ptr: *mut CompletionStatus = completion_status.get_unchecked_mut();
185 let prev = ((*task).waitable_register)((*task).ptr, waitable, cabi_wake, ptr.cast());
186 // We might be inserting a waker for the first time or overwriting
187 // the previous waker. Only assert the expected value here if the
188 // previous value was non-null.
189 if !prev.is_null() {
190 assert_eq!(ptr, prev.cast());
191 }
192 cabi::wasip3_task_set(task);
193 }
194
195 unsafe extern "C" fn cabi_wake(ptr: *mut c_void, code: u32) {
196 let ptr: &mut CompletionStatus = &mut *ptr.cast::<CompletionStatus>();
197 ptr.code = Some(code);
198 ptr.waker.take().unwrap().wake()
199 }
200 }
201
202 /// Deregisters the corresponding `register_waker` within the current task
203 /// for the `waitable` passed here.
204 ///
205 /// This relinquishes control of the original `completion_status` pointer
206 /// passed to `register_waker` after this call has completed.
207 pub fn unregister_waker(self: Pin<&mut Self>, waitable: u32) {
208 // SAFETY: the contract of `wasip3_task_set` is that the returned
209 // pointer is valid for the lifetime of our entire task, so it's valid
210 // for this stack frame. Additionally we assert it's non-null to
211 // double-check it's initialized and additionally check the version for
212 // the fields that we access.
213 //
214 // Otherwise the `waitable_unregister` callback should be safe because:
215 //
216 // * We're fulfilling the contract where the first argument must be
217 // `(*task).ptr`
218 // * We own the `waitable` that we're passing in, so we're fulfilling
219 // the contract that arbitrary waitables for other units of work
220 // aren't being manipulated.
221 unsafe {
222 let task = cabi::wasip3_task_set(ptr::null_mut());
223 assert!(!task.is_null());
224 assert!((*task).version >= cabi::WASIP3_TASK_V1);
225 let prev = ((*task).waitable_unregister)((*task).ptr, waitable);
226
227 // Note that `_prev` here is not guaranteed to be either `NULL` or
228 // not. A racy completion notification may have come in and
229 // removed our waitable from the map even though we're in the
230 // `InProgress` state, meaning it may not be present.
231 //
232 // The main thing is that after this method is called the
233 // internal `completion_status` is guaranteed to no longer be in
234 // `task`.
235 //
236 // Note, though, that if present this must be our `CompletionStatus`
237 // pointer.
238 if !prev.is_null() {
239 let ptr: *mut CompletionStatus = self.pin_project().1.get_unchecked_mut();
240 assert_eq!(ptr, prev.cast());
241 }
242
243 cabi::wasip3_task_set(task);
244 }
245 }
246
247 /// Polls this operation to see if it has completed yet.
248 ///
249 /// This is intended to be used within `Future::poll`.
250 pub fn poll_complete(mut self: Pin<&mut Self>, cx: &mut Context) -> Poll<S::Result> {
251 use WaitableOperationState::*;
252
253 let (state, completion_status) = self.as_mut().pin_project();
254
255 // First up, determine the completion status, if any, that's available.
256 let optional_code = match state {
257 // If this operation hasn't actually started yet then now's the
258 // time to start it.
259 Start(_) => {
260 let Start(s) = mem::replace(state, Done) else {
261 unreachable!()
262 };
263 let (code, s) = S::start(s);
264 *state = InProgress(s);
265 Some(code)
266 }
267
268 // This operation was previously queued so we're just waiting on
269 // the completion to come in. Read the completion status and
270 // interpret it down below.
271 //
272 // Note that it's the responsibility of the completion callback at
273 // the ABI level that we install to fill in this pointer, e.g. it's
274 // part of the `register_waker` contract.
275 InProgress(_) => completion_status.code_mut().take(),
276
277 // This write has already completed, it's a Rust-level API violation
278 // to call this function again.
279 Done => panic!("cannot re-poll after operation completes"),
280 };
281
282 self.poll_complete_with_code(Some(cx), optional_code)
283 }
284
285 /// After acquiring the current return of this operation in `optional_code`,
286 /// figures out what to do with it.
287 ///
288 /// The `cx` argument is optional to do nothing in the case that
289 /// `optional_code` is not present.
290 fn poll_complete_with_code(
291 mut self: Pin<&mut Self>,
292 cx: Option<&mut Context>,
293 optional_code: Option<u32>,
294 ) -> Poll<S::Result> {
295 use WaitableOperationState::*;
296
297 let (state, _completion_status) = self.as_mut().pin_project();
298
299 // If a status code is provided, then extract the in-progress state and
300 // see what it thinks about this code. If we're done, yay! If not then
301 // record the new in-progress state and fall through to registering a
302 // waker.
303 //
304 // If no status code is available then that means we were polled before
305 // the status came back, so just re-register the waker.
306 if let Some(code) = optional_code {
307 let InProgress(in_progress) = mem::replace(state, Done) else {
308 unreachable!()
309 };
310 match S::in_progress_update(in_progress, code) {
311 Ok(result) => return Poll::Ready(result),
312 Err(in_progress) => *state = InProgress(in_progress),
313 }
314 }
315
316 let in_progress = match state {
317 InProgress(s) => s,
318 _ => unreachable!(),
319 };
320
321 // The operation is still in progress.
322 //
323 // Register the `cx.waker()` to get notified when `writer.handle`
324 // receives its completion.
325 if let Some(cx) = cx {
326 let handle = S::in_progress_waitable(in_progress);
327 self.register_waker(handle, cx);
328 }
329 Poll::Pending
330 }
331
332 /// Cancels the in-flight operation, if it's still in-flight, and sees what
333 /// happened.
334 ///
335 /// Defers to `S` how to communicate the current status through the
336 /// cancellation type.
337 ///
338 /// # Panics
339 ///
340 /// Panics if the operation has already been completed via `poll_complete`
341 /// above.
342 /// Panics if this method is called twice.
343 pub fn cancel(mut self: Pin<&mut Self>) -> S::Cancel {
344 use WaitableOperationState::*;
345
346 let (state, mut completion_status) = self.as_mut().pin_project();
347 let in_progress = match state {
348 // This operation was never actually started, so there's no need to
349 // cancel anything, just pull out the value and return it.
350 Start(_) => {
351 let Start(s) = mem::replace(state, Done) else {
352 unreachable!()
353 };
354 return S::start_cancelled(s);
355 }
356
357 // This operation is actively in progress, fall through to below.
358 InProgress(s) => s,
359
360 // This operation was already completed after a `poll_complete`
361 // above advanced to the `Done` state, or this was cancelled twice.
362 // In such situations this is a programmer error to call this
363 // method, so panic.
364 Done => panic!("cannot cancel operation after completing it"),
365 };
366
367 // Our operation is in-progress, let's take a look at the pending
368 // completion code, if any.
369 match completion_status.as_mut().code_mut().take() {
370 // A completion code, or status update, is available. This can
371 // happen for example if an export received a status update for
372 // this operation but then during the subsequent poll we decided
373 // that the future should be dropped instead, aka a race between
374 // two events. In this situation though to fully process the
375 // cancellation we need to see what's up, so check to see if the
376 // operation is done with this code.
377 //
378 // Note that in this branch it's known that this operation's waker
379 // is not registered with the exported task because the exported
380 // task already delivered us the completion code, which
381 // automatically deregisters it at this time.
382 Some(code) => {
383 match self.as_mut().poll_complete_with_code(None, Some(code)) {
384 // The operation completed without us needing to cancel it,
385 // so just convert that to the `Cancel` type. In this
386 // situation no cancellation is necessary, the async
387 // operation is now inert, and we can immediately return.
388 Poll::Ready(result) => return S::result_into_cancel(result),
389
390 // The operation, despite receiving an update via a code,
391 // has not yet completed. In this case we do indeed need to
392 // perform cancellation, so fall through to below.
393 Poll::Pending => {}
394 }
395 }
396
397 // A completion code is not yet available. In this situation we
398 // deregister our waker from the exported task's waitable set and
399 // callback handling since we'll be no longer waiting for events.
400 // Cancellation below happens synchronously.
401 //
402 // After we've unregistered fall through to below.
403 None => {
404 let waitable = S::in_progress_waitable(in_progress);
405 self.as_mut().unregister_waker(waitable);
406 }
407 }
408
409 // This operation is guaranteed actively in progress at this point.
410 // That means we really do in fact need to cancel it. Here the
411 // appropriate cancellation intrinsic for the component model is
412 // invoked which returns the final completion status for this
413 // operation.
414 //
415 // The completion code is forwarded to `poll_complete_with_code` which
416 // determines what happened as a result. Note that at this time
417 // cancellation is required to be a synchronous operation in Rust, even
418 // if it's async in the component model, since that's the only way for
419 // this to be sound. Rust doesn't currently have linear types or async
420 // destructors for example to ensure otherwise that if this were to
421 // proceed asynchronously that we could rely on it being invoked.
422 let (InProgress(in_progress), _) = self.as_mut().pin_project() else {
423 unreachable!()
424 };
425 let code = S::in_progress_cancel(in_progress);
426 match self.poll_complete_with_code(None, Some(code)) {
427 Poll::Ready(result) => S::result_into_cancel(result),
428 Poll::Pending => unreachable!(),
429 }
430 }
431 }
432
433 impl<S: WaitableOp> Future for WaitableOperation<S> {
434 type Output = S::Result;
435
436 fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<S::Result> {
437 self.poll_complete(cx)
438 }
439 }
440
441 impl<S: WaitableOp> Drop for WaitableOperation<S> {
442 fn drop(&mut self) {
443 // SAFETY: we're in the destructor here so the value `self` is about
444 // to go away and we can guarantee we're not moving out of it.
445 let mut pin = unsafe { Pin::new_unchecked(self) };
446
447 let (state, _) = pin.as_mut().pin_project();
448
449 // If this operation has already completed then skip cancellation,
450 // otherwise it's our job to cancel anything in-flight.
451 if let WaitableOperationState::Done = state {
452 return;
453 }
454 pin.cancel();
455 }
456 }
457
458 impl CompletionStatus {
459 fn code_mut(self: Pin<&mut Self>) -> &mut Option<u32> {
460 unsafe { &mut self.get_unchecked_mut().code }
461 }
462
463 fn waker_mut(self: Pin<&mut Self>) -> &mut Option<Waker> {
464 unsafe { &mut self.get_unchecked_mut().waker }
465 }
466 }