html-to-markdown 2.24.4 → 2.24.6

data/rust-vendor/wit-bindgen-0.46.0/src/rt/async_support/waitable.rs

@@ -0,0 +1,466 @@
+//! Generic support for "any waitable" and performing asynchronous operations on
+//! that waitable.
+
+use super::cabi;
+use std::ffi::c_void;
+use std::future::Future;
+use std::marker;
+use std::mem;
+use std::pin::Pin;
+use std::ptr;
+use std::task::{Context, Poll, Waker};
+
+/// Generic future-based operation on any "waitable" in the component model.
+///
+/// This is used right now to power futures and streams for both read/write
+/// halves. This structure is driven by `S`, an implementation of
+/// [`WaitableOp`], which codifies the various state transitions and what to do
+/// on each state transition.
+pub struct WaitableOperation<S: WaitableOp> {
+    state: WaitableOperationState<S>,
+    /// Storage for the final result of this asynchronous operation, if it's
+    /// completed asynchronously.
+    completion_status: CompletionStatus,
+}
+
+/// Structure used to store the `u32` return code from the canonical ABI about
+/// an asynchronous operation.
+///
+/// When an asynchronous operation is started and it does not immediately
+/// complete then this structure is used to asynchronously fill in the return
+/// code. A `Pin<&mut CompletionStatus>` is used to register a pointer with
+/// `FutureState` to get filled in.
+///
+/// Note that this means that this type is participating in unsafe lifetime
+/// management and has properties it needs to uphold as a result. Specifically
+/// the `PhantomPinned` field here means that `Pin` actually has meaning for
+/// this structure, notably that once `Pin<&mut CompletionStatus>` is created
+/// then it's guaranteed the destructor will be run before the backing memory
+/// is deallocated. That's used in `WaitableOperation` above to share an
+/// internal pointer of this data structure with `FuturesState` safely. The
+/// destructor of `WaitableOperation` will deregister from `FutureState` meaning
+/// that if `FuturesState` has a pointer here then it should be valid .
+struct CompletionStatus {
+    /// Where the async operation's code is filled in, and `None` until that
+    /// happens.
+    code: Option<u32>,
+
+    waker: Option<Waker>,
+
+    /// This is necessary to ensure that `Pin<&mut CompletionStatus>` carries
+    /// the "pin guarantee", basically to mean that it's not safe to construct
+    /// `Pin<&mut CompletionStatus>` and it must somehow require `unsafe` code.
+    _pinned: marker::PhantomPinned,
+}
+
+/// Helper trait to be used with `WaitableOperation` to assist with machinery
+/// necessary to track in-flight reads/writes on futures.
+///
+/// # Unsafety
+///
+/// This trait is `unsafe` as it has various guarantees that must be upheld by
+/// implementors such as:
+///
+/// * `S::in_progress_waitable` must always return the same value for the state
+///   given.
+pub unsafe trait WaitableOp {
+    /// Initial state of this operation, used to kick off the actual component
+    /// model operation and transition to `InProgress`.
+    type Start;
+
+    /// Intermediate state of this operation when the component model is
+    /// involved but it hasn't resolved just yet.
+    type InProgress;
+
+    /// Result type of this operation.
+    type Result;
+
+    /// Result of when this operation is cancelled.
+    type Cancel;
+
+    /// Starts the async operation.
+    ///
+    /// This method will actually call `{future,stream}.{read,write}` with
+    /// `state` provided. The return code of the intrinsic is returned here
+    /// along with the `InProgress` state.
+    fn start(state: Self::Start) -> (u32, Self::InProgress);
+
+    /// Optionally complete the async operation.
+    ///
+    /// This method will transition from the `InProgress` state, with some
+    /// status code that was received, to either a completed result or a new
+    /// `InProgress` state. This is invoked when:
+    ///
+    /// * a new status code has been received by an async export's `callback`
+    /// * cancellation returned a code to be processed here
+    fn in_progress_update(
+        state: Self::InProgress,
+        code: u32,
+    ) -> Result<Self::Result, Self::InProgress>;
+
+    /// Conversion from the "start" state to the "cancel" result, needed when an
+    /// operation is cancelled before it's started.
+    fn start_cancelled(state: Self::Start) -> Self::Cancel;
+
+    /// Acquires the component-model `waitable` index that the `InProgress`
+    /// state is waiting on.
+    fn in_progress_waitable(state: &Self::InProgress) -> u32;
+
+    /// Initiates a request for cancellation of this operation. Returns the
+    /// status code returned by the `{future,stream}.cancel-{read,write}`
+    /// intrinsic.
+    ///
+    /// Note that this must synchronously complete the operation somehow. This
+    /// cannot return a status code indicating that an operation is pending,
+    /// instead the operation must be complete with the returned code. That may
+    /// mean that this intrinsic can block while figuring things out in the
+    /// component model ABI, for example.
+    fn in_progress_cancel(state: &Self::InProgress) -> u32;
+
+    /// Converts a "completion result" into a "cancel result". This is necessary
+    /// when an in-progress operation is cancelled so the in-progress result is
+    /// first acquired and then transitioned to a cancel request.
+    fn result_into_cancel(result: Self::Result) -> Self::Cancel;
+}
+
+enum WaitableOperationState<S: WaitableOp> {
+    Start(S::Start),
+    InProgress(S::InProgress),
+    Done,
+}
+
+impl<S> WaitableOperation<S>
+where
+    S: WaitableOp,
+{
+    /// Creates a new operation in the initial state.
+    pub fn new(state: S::Start) -> WaitableOperation<S> {
+        WaitableOperation {
+            state: WaitableOperationState::Start(state),
+            completion_status: CompletionStatus {
+                code: None,
+                waker: None,
+                _pinned: marker::PhantomPinned,
+            },
+        }
+    }
+
+    fn pin_project(
+        self: Pin<&mut Self>,
+    ) -> (&mut WaitableOperationState<S>, Pin<&mut CompletionStatus>) {
+        // SAFETY: this is the one method used to project from `Pin<&mut Self>`
+        // to the fields, and the contract we're deciding on is that
+        // `state` is never pinned but the `CompletionStatus` is. That's used
+        // to share a raw pointer with the completion callback with
+        // respect to `Option<u32>` internally.
+        unsafe {
+            let me = self.get_unchecked_mut();
+            (&mut me.state, Pin::new_unchecked(&mut me.completion_status))
+        }
+    }
+
+    /// Registers a completion of `waitable` within the current task's future to:
+    ///
+    /// * Fill in `completion_status` with the result of a completion event.
+    /// * Call `cx.waker().wake()`.
+    pub fn register_waker(self: Pin<&mut Self>, waitable: u32, cx: &mut Context) {
+        let (_, mut completion_status) = self.pin_project();
+        debug_assert!(completion_status.as_mut().code_mut().is_none());
+        *completion_status.as_mut().waker_mut() = Some(cx.waker().clone());
+
+        // SAFETY: There's quite a lot going on here. First is the usage of
+        // `task` below, and for that see `unregister_waker` below for why this
+        // pattern should be safe.
+        //
+        // Otherwise we're handing off a pointer to `completion_status` to the
+        // `task` itself. That should be safe as we're guaranteed, via
+        // `Pin<&mut Self>`, that before `&mut Self` is deallocated the
+        // destructor will be run which will perform de-registration via
+        // cancellation.
+        unsafe {
+            let task = cabi::wasip3_task_set(ptr::null_mut());
+            assert!(!task.is_null());
+            assert!((*task).version >= cabi::WASIP3_TASK_V1);
+            let ptr: *mut CompletionStatus = completion_status.get_unchecked_mut();
+            let prev = ((*task).waitable_register)((*task).ptr, waitable, cabi_wake, ptr.cast());
+            // We might be inserting a waker for the first time or overwriting
+            // the previous waker. Only assert the expected value here if the
+            // previous value was non-null.
+            if !prev.is_null() {
+                assert_eq!(ptr, prev.cast());
+            }
+            cabi::wasip3_task_set(task);
+        }
+
+        unsafe extern "C" fn cabi_wake(ptr: *mut c_void, code: u32) {
+            let ptr: &mut CompletionStatus = &mut *ptr.cast::<CompletionStatus>();
+            ptr.code = Some(code);
+            ptr.waker.take().unwrap().wake()
+        }
+    }
+
+    /// Deregisters the corresponding `register_waker` within the current task
+    /// for the `waitable` passed here.
+    ///
+    /// This relinquishes control of the original `completion_status` pointer
+    /// passed to `register_waker` after this call has completed.
+    pub fn unregister_waker(self: Pin<&mut Self>, waitable: u32) {
+        // SAFETY: the contract of `wasip3_task_set` is that the returned
+        // pointer is valid for the lifetime of our entire task, so it's valid
+        // for this stack frame. Additionally we assert it's non-null to
+        // double-check it's initialized and additionally check the version for
+        // the fields that we access.
+        //
+        // Otherwise the `waitable_unregister` callback should be safe because:
+        //
+        // * We're fulfilling the contract where the first argument must be
+        //   `(*task).ptr`
+        // * We own the `waitable` that we're passing in, so we're fulfilling
+        //   the contract that arbitrary waitables for other units of work
+        //   aren't being manipulated.
+        unsafe {
+            let task = cabi::wasip3_task_set(ptr::null_mut());
+            assert!(!task.is_null());
+            assert!((*task).version >= cabi::WASIP3_TASK_V1);
+            let prev = ((*task).waitable_unregister)((*task).ptr, waitable);
+
+            // Note that `_prev` here is not guaranteed to be either `NULL` or
+            // not. A racy completion notification may have come in and
+            // removed our waitable from the map even though we're in the
+            // `InProgress` state, meaning it may not be present.
+            //
+            // The main thing is that after this method is called the
+            // internal `completion_status` is guaranteed to no longer be in
+            // `task`.
+            //
+            // Note, though, that if present this must be our `CompletionStatus`
+            // pointer.
+            if !prev.is_null() {
+                let ptr: *mut CompletionStatus = self.pin_project().1.get_unchecked_mut();
+                assert_eq!(ptr, prev.cast());
+            }
+
+            cabi::wasip3_task_set(task);
+        }
+    }
+
+    /// Polls this operation to see if it has completed yet.
+    ///
+    /// This is intended to be used within `Future::poll`.
+    pub fn poll_complete(mut self: Pin<&mut Self>, cx: &mut Context) -> Poll<S::Result> {
+        use WaitableOperationState::*;
+
+        let (state, completion_status) = self.as_mut().pin_project();
+
+        // First up, determine the completion status, if any, that's available.
+        let optional_code = match state {
+            // If this operation hasn't actually started yet then now's the
+            // time to start it.
+            Start(_) => {
+                let Start(s) = mem::replace(state, Done) else {
+                    unreachable!()
+                };
+                let (code, s) = S::start(s);
+                *state = InProgress(s);
+                Some(code)
+            }
+
+            // This operation was previously queued so we're just waiting on
+            // the completion to come in. Read the completion status and
+            // interpret it down below.
+            //
+            // Note that it's the responsibility of the completion callback at
+            // the ABI level that we install to fill in this pointer, e.g. it's
+            // part of the `register_waker` contract.
+            InProgress(_) => completion_status.code_mut().take(),
+
+            // This write has already completed, it's a Rust-level API violation
+            // to call this function again.
+            Done => panic!("cannot re-poll after operation completes"),
+        };
+
+        self.poll_complete_with_code(Some(cx), optional_code)
+    }
+
+    /// After acquiring the current return of this operation in `optional_code`,
+    /// figures out what to do with it.
+    ///
+    /// The `cx` argument is optional to do nothing in the case that
+    /// `optional_code` is not present.
+    fn poll_complete_with_code(
+        mut self: Pin<&mut Self>,
+        cx: Option<&mut Context>,
+        optional_code: Option<u32>,
+    ) -> Poll<S::Result> {
+        use WaitableOperationState::*;
+
+        let (state, _completion_status) = self.as_mut().pin_project();
+
+        // If a status code is provided, then extract the in-progress state and
+        // see what it thinks about this code. If we're done, yay! If not then
+        // record the new in-progress state and fall through to registering a
+        // waker.
+        //
+        // If no status code is available then that means we were polled before
+        // the status came back, so just re-register the waker.
+        if let Some(code) = optional_code {
+            let InProgress(in_progress) = mem::replace(state, Done) else {
+                unreachable!()
+            };
+            match S::in_progress_update(in_progress, code) {
+                Ok(result) => return Poll::Ready(result),
+                Err(in_progress) => *state = InProgress(in_progress),
+            }
+        }
+
+        let in_progress = match state {
+            InProgress(s) => s,
+            _ => unreachable!(),
+        };
+
+        // The operation is still in progress.
+        //
+        // Register the `cx.waker()` to get notified when `writer.handle`
+        // receives its completion.
+        if let Some(cx) = cx {
+            let handle = S::in_progress_waitable(in_progress);
+            self.register_waker(handle, cx);
+        }
+        Poll::Pending
+    }
+
+    /// Cancels the in-flight operation, if it's still in-flight, and sees what
+    /// happened.
+    ///
+    /// Defers to `S` how to communicate the current status through the
+    /// cancellation type.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the operation has already been completed via `poll_complete`
+    /// above.
+    /// Panics if this method is called twice.
+    pub fn cancel(mut self: Pin<&mut Self>) -> S::Cancel {
+        use WaitableOperationState::*;
+
+        let (state, mut completion_status) = self.as_mut().pin_project();
+        let in_progress = match state {
+            // This operation was never actually started, so there's no need to
+            // cancel anything, just pull out the value and return it.
+            Start(_) => {
+                let Start(s) = mem::replace(state, Done) else {
+                    unreachable!()
+                };
+                return S::start_cancelled(s);
+            }
+
+            // This operation is actively in progress, fall through to below.
+            InProgress(s) => s,
+
+            // This operation was already completed after a `poll_complete`
+            // above advanced to the `Done` state, or this was cancelled twice.
+            // In such situations this is a programmer error to call this
+            // method, so panic.
+            Done => panic!("cannot cancel operation after completing it"),
+        };
+
+        // Our operation is in-progress, let's take a look at the pending
+        // completion code, if any.
+        match completion_status.as_mut().code_mut().take() {
+            // A completion code, or status update, is available. This can
+            // happen for example if an export received a status update for
+            // this operation but then during the subsequent poll we decided
+            // that the future should be dropped instead, aka a race between
+            // two events. In this situation though to fully process the
+            // cancellation we need to see what's up, so check to see if the
+            // operation is done with this code.
+            //
+            // Note that in this branch it's known that this operation's waker
+            // is not registered with the exported task because the exported
+            // task already delivered us the completion code, which
+            // automatically deregisters it at this time.
+            Some(code) => {
+                match self.as_mut().poll_complete_with_code(None, Some(code)) {
+                    // The operation completed without us needing to cancel it,
+                    // so just convert that to the `Cancel` type. In this
+                    // situation no cancellation is necessary, the async
+                    // operation is now inert, and we can immediately return.
+                    Poll::Ready(result) => return S::result_into_cancel(result),
+
+                    // The operation, despite receiving an update via a code,
+                    // has not yet completed. In this case we do indeed need to
+                    // perform cancellation, so fall through to below.
+                    Poll::Pending => {}
+                }
+            }
+
+            // A completion code is not yet available. In this situation we
+            // deregister our waker from the exported task's waitable set and
+            // callback handling since we'll be no longer waiting for events.
+            // Cancellation below happens synchronously.
+            //
+            // After we've unregistered fall through to below.
+            None => {
+                let waitable = S::in_progress_waitable(in_progress);
+                self.as_mut().unregister_waker(waitable);
+            }
+        }
+
+        // This operation is guaranteed actively in progress at this point.
+        // That means we really do in fact need to cancel it. Here the
+        // appropriate cancellation intrinsic for the component model is
+        // invoked which returns the final completion status for this
+        // operation.
+        //
+        // The completion code is forwarded to `poll_complete_with_code` which
+        // determines what happened as a result. Note that at this time
+        // cancellation is required to be a synchronous operation in Rust, even
+        // if it's async in the component model, since that's the only way for
+        // this to be sound. Rust doesn't currently have linear types or async
+        // destructors for example to ensure otherwise that if this were to
+        // proceed asynchronously that we could rely on it being invoked.
+        let (InProgress(in_progress), _) = self.as_mut().pin_project() else {
+            unreachable!()
+        };
+        let code = S::in_progress_cancel(in_progress);
+        match self.poll_complete_with_code(None, Some(code)) {
+            Poll::Ready(result) => S::result_into_cancel(result),
+            Poll::Pending => unreachable!(),
+        }
+    }
+}
+
+impl<S: WaitableOp> Future for WaitableOperation<S> {
+    type Output = S::Result;
+
+    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<S::Result> {
+        self.poll_complete(cx)
+    }
+}
+
+impl<S: WaitableOp> Drop for WaitableOperation<S> {
+    fn drop(&mut self) {
+        // SAFETY: we're in the destructor here so the value `self` is about
+        // to go away and we can guarantee we're not moving out of it.
+        let mut pin = unsafe { Pin::new_unchecked(self) };
+
+        let (state, _) = pin.as_mut().pin_project();
+
+        // If this operation has already completed then skip cancellation,
+        // otherwise it's our job to cancel anything in-flight.
+        if let WaitableOperationState::Done = state {
+            return;
+        }
+        pin.cancel();
+    }
+}
+
+impl CompletionStatus {
+    fn code_mut(self: Pin<&mut Self>) -> &mut Option<u32> {
+        unsafe { &mut self.get_unchecked_mut().code }
+    }
+
+    fn waker_mut(self: Pin<&mut Self>) -> &mut Option<Waker> {
+        unsafe { &mut self.get_unchecked_mut().waker }
+    }
+}

data/rust-vendor/wit-bindgen-0.46.0/src/rt/async_support/waitable_set.rs

@@ -0,0 +1,100 @@
+//! Low-level FFI-like bindings around `waitable-set` in the canonical ABI.
+
+use std::num::NonZeroU32;
+
+pub struct WaitableSet(NonZeroU32);
+
+impl WaitableSet {
+    pub fn new() -> WaitableSet {
+        let ret = WaitableSet(NonZeroU32::new(unsafe { new() }).unwrap());
+        rtdebug!("waitable-set.new() = {}", ret.0.get());
+        ret
+    }
+
+    pub fn join(&self, waitable: u32) {
+        rtdebug!("waitable-set.join({waitable}, {})", self.0.get());
+        unsafe { join(waitable, self.0.get()) }
+    }
+
+    pub fn remove_waitable_from_all_sets(waitable: u32) {
+        rtdebug!("waitable-set.join({waitable}, 0)");
+        unsafe { join(waitable, 0) }
+    }
+
+    pub fn wait(&self) -> (u32, u32, u32) {
+        unsafe {
+            let mut payload = [0; 2];
+            let event0 = wait(self.0.get(), &mut payload);
+            rtdebug!(
+                "waitable-set.wait({}) = ({event0}, {:#x}, {:#x})",
+                self.0.get(),
+                payload[0],
+                payload[1],
+            );
+            (event0, payload[0], payload[1])
+        }
+    }
+
+    pub fn poll(&self) -> (u32, u32, u32) {
+        unsafe {
+            let mut payload = [0; 2];
+            let event0 = poll(self.0.get(), &mut payload);
+            rtdebug!(
+                "waitable-set.poll({}) = ({event0}, {:#x}, {:#x})",
+                self.0.get(),
+                payload[0],
+                payload[1],
+            );
+            (event0, payload[0], payload[1])
+        }
+    }
+
+    pub fn as_raw(&self) -> u32 {
+        self.0.get()
+    }
+}
+
+impl Drop for WaitableSet {
+    fn drop(&mut self) {
+        unsafe {
+            rtdebug!("waitable-set.drop({})", self.0.get());
+            drop(self.0.get());
+        }
+    }
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+unsafe fn new() -> u32 {
+    unreachable!()
+}
+#[cfg(not(target_arch = "wasm32"))]
+unsafe fn drop(_: u32) {
+    unreachable!()
+}
+#[cfg(not(target_arch = "wasm32"))]
+unsafe fn join(_: u32, _: u32) {
+    unreachable!()
+}
+#[cfg(not(target_arch = "wasm32"))]
+unsafe fn wait(_: u32, _: *mut [u32; 2]) -> u32 {
+    unreachable!();
+}
+#[cfg(not(target_arch = "wasm32"))]
+unsafe fn poll(_: u32, _: *mut [u32; 2]) -> u32 {
+    unreachable!();
+}
+
+#[cfg(target_arch = "wasm32")]
+#[link(wasm_import_module = "$root")]
+extern "C" {
+    #[link_name = "[waitable-set-new]"]
+    fn new() -> u32;
+    #[link_name = "[waitable-set-drop]"]
+    fn drop(set: u32);
+    #[link_name = "[waitable-join]"]
+    fn join(waitable: u32, set: u32);
+    #[link_name = "[waitable-set-wait]"]
+    fn wait(_: u32, _: *mut [u32; 2]) -> u32;
+    #[link_name = "[waitable-set-poll]"]
+    fn poll(_: u32, _: *mut [u32; 2]) -> u32;
+}