windows-threadpool-sys 0.3.0

// Copyright (c) 2026 Mike Grier
//! Thread-pool waits: `CreateThreadpoolWait` / `SetThreadpoolWait` /
//! `WaitForThreadpoolWaitCallbacks` / `CloseThreadpoolWait`.
//!
//! A wait object watches one waitable handle and queues its callback when the
//! handle is signalled or the wait times out. Two SDK contracts shape this API:
//!
//! - **The handle must stay valid while a wait is pending.** [`ThreadpoolWait`]
//!   therefore *owns* its handle rather than borrowing one, so it cannot be
//!   closed underneath a pending wait. Use [`ThreadpoolWait::handle`] to
//!   inspect it; to signal an event the wait owns, build the wait from a
//!   `win-sync-sys` [`Event`] and keep a clone of it.
//! - **A wait fires at most once per arming.** The SDK requires the wait to be
//!   rearmed explicitly for each activation, so the callback receives a
//!   [`WaitActivation`] carrying [`WaitActivation::rearm`]. A callback that does
//!   not rearm simply stops watching.
//!
//! Mutex handles are not supported by the thread pool and must not be passed to
//! [`ThreadpoolWait::new`].

use std::io;
use std::os::windows::io::{AsHandle, AsRawHandle, BorrowedHandle, OwnedHandle};
use std::ptr;
use std::sync::atomic::{AtomicIsize, Ordering};
use std::time::Duration;

use crate::rearm::RearmSuppression;

use win_sync_sys::{Event, ResetMode};
use windows_sys::Win32::Foundation::{FALSE, FILETIME, HANDLE, TRUE, WAIT_TIMEOUT};
use windows_sys::Win32::System::Threading::{
    CloseThreadpoolWait, CreateThreadpoolWait, PTP_CALLBACK_INSTANCE, PTP_WAIT, SetThreadpoolWait,
    WaitForThreadpoolWaitCallbacks,
};
use windows_sys::core::BOOL;

use crate::callback_env::CallbackEnviron;

/// Wait results the pool reports. Changing either value is a breaking change.
mod wait_status {
    /// `WAIT_OBJECT_0`: the handle was signalled.
    pub const SIGNALLED: u32 = 0;
}

/// 100-nanosecond intervals per second, for building a relative `FILETIME`.
/// Changing this value is a breaking change.
const FILETIME_TICKS_PER_SECOND: u64 = 10_000_000;
/// Nanoseconds per 100-nanosecond interval. Changing it is a breaking change.
const FILETIME_NANOS_PER_TICK: u32 = 100;

/// Build the negative tick count that means "relative timeout".
fn relative_filetime(timeout: Duration) -> FILETIME {
    let ticks = timeout
        .as_secs()
        .saturating_mul(FILETIME_TICKS_PER_SECOND)
        .saturating_add(u64::from(timeout.subsec_nanos() / FILETIME_NANOS_PER_TICK));
    let ticks = i64::try_from(ticks).unwrap_or(i64::MAX);
    let bits = (-ticks) as u64;
    FILETIME {
        dwLowDateTime: bits as u32,
        dwHighDateTime: (bits >> 32) as u32,
    }
}

/// A Win32 routine that closes a wait target.
///
/// This is the shape Win32 close routines already have, so one can be passed
/// directly with no shim: `CloseHandle` and `FindCloseChangeNotification` both
/// match it. The return value is ignored -- there is nothing a destructor could
/// usefully do with a close failure.
pub type WaitCloseFn = unsafe extern "system" fn(HANDLE) -> BOOL;

/// Owns a handle that is closed with a routine other than `CloseHandle`.
///
/// The `Drop` lives here rather than on [`WaitTarget`] so that the enum itself
/// has no destructor and can be taken apart by an ordinary `match`.
pub(crate) struct CustomClose {
    raw: HANDLE,
    close: WaitCloseFn,
}

impl Drop for CustomClose {
    fn drop(&mut self) {
        // Bracketed like a Win32 call because that is what it usually is: the
        // routine is caller-supplied and the case this exists for,
        // `FindCloseChangeNotification`, is a kernel close. It runs while the
        // owning wait is being torn down, so a slow one shows up as a stalled
        // teardown with no other explanation.
        crate::trace_call!("WaitCloseFn", self.raw as usize, self.close as usize, {
            // SAFETY: the handle was vouched for by `assume_waitable_with` and is
            // still open -- every owner drains the wait before dropping this, so the
            // pool is no longer watching it. This runs exactly once, because `Drop`
            // does.
            unsafe { (self.close)(self.raw) };
        });
    }
}

/// Owns a wait target and closes it with the routine that target requires.
///
/// Most handles are closed with `CloseHandle`, which is what a std
/// [`OwnedHandle`] does, so that stays the default. Some are not: a
/// `FindFirstChangeNotification` handle must be closed with
/// `FindCloseChangeNotification`, and closing it the usual way is wrong. The
/// second variant carries the caller's routine so those targets can be owned by
/// the pool on the same terms as any other.
pub(crate) enum WaitTarget {
    /// The default: closed by [`OwnedHandle`]'s own drop, with `CloseHandle`.
    Owned(OwnedHandle),
    /// Closed with the caller-supplied routine.
    Custom(CustomClose),
}

// SAFETY: a handle is an opaque OS-owned value, not a pointer into this
// process, and both variants only ever read it or hand it to a thread-safe Win32
// call. This restores what the plain `OwnedHandle` field had automatically.
unsafe impl Send for WaitTarget {}
unsafe impl Sync for WaitTarget {}

impl WaitTarget {
    /// The raw handle, for arming the wait and for the callback context.
    pub(crate) fn raw(&self) -> HANDLE {
        match self {
            WaitTarget::Owned(handle) => handle.as_raw_handle(),
            WaitTarget::Custom(custom) => custom.raw,
        }
    }

    /// Borrow the handle, for signalling or inspecting it.
    pub(crate) fn borrow(&self) -> BorrowedHandle<'_> {
        match self {
            WaitTarget::Owned(handle) => handle.as_handle(),
            // SAFETY: the handle stays open for as long as `self` owns it, and
            // the returned borrow cannot outlive that.
            WaitTarget::Custom(custom) => unsafe { BorrowedHandle::borrow_raw(custom.raw) },
        }
    }
}

impl std::fmt::Debug for WaitTarget {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // The close routine is a code pointer with no useful rendering.
        f.debug_struct("WaitTarget")
            .field("raw", &self.raw())
            .field(
                "close",
                &match self {
                    WaitTarget::Owned(_) => "CloseHandle",
                    WaitTarget::Custom(_) => "custom",
                },
            )
            .finish()
    }
}

/// A handle the thread pool is able to wait on.
///
/// The pool does not support every waitable object: a mutex handle in
/// particular produces undefined behaviour rather than an error. Requiring this
/// type instead of a bare [`OwnedHandle`] moves that precondition from prose
/// into the type system, so a safe caller cannot reach the undefined case.
///
/// Construct one safely from a `win-sync-sys` [`Event`] (`From<Event>`) or with
/// [`WaitableHandle::event`], or vouch for a handle
/// obtained elsewhere with the narrow [`WaitableHandle::assume_waitable`] seam --
/// or [`WaitableHandle::assume_waitable_with`] when the handle needs a close
/// routine other than `CloseHandle`.
/// This mirrors `UnassociatedEndpoint` in `windows-overlapped-io-sys`, which
/// pairs a safe `open` with an `assume_overlapped` escape hatch for the same
/// reason.
#[derive(Debug)]
pub struct WaitableHandle {
    target: WaitTarget,
}

impl WaitableHandle {
    /// Create an event and wrap it as a waitable handle.
    ///
    /// An event is always a supported wait target, so this needs no `unsafe`.
    /// A `manual_reset` event stays signalled until it is reset; an auto-reset
    /// event returns to unsignalled as soon as one wait is satisfied, which
    /// makes it the usual choice for handing off work one activation at a time.
    ///
    /// The event is a `win-sync-sys` [`Event`], so this crate creates none of
    /// its own. To be able to set the event once the wait owns it, create the
    /// [`Event`] directly, keep a [`try_clone`](Event::try_clone), and convert
    /// the other with `From<Event>`.
    ///
    /// # Errors
    ///
    /// Returns the error from [`Event::new`].
    pub fn event(manual_reset: bool, initially_signalled: bool) -> io::Result<Self> {
        let reset = if manual_reset {
            ResetMode::Manual
        } else {
            ResetMode::Auto
        };
        Ok(Event::new(reset, initially_signalled)?.into())
    }

    /// Wrap a handle whose wait support the caller vouches for.
    ///
    /// This is the extensibility seam for wait targets this crate cannot create
    /// itself -- semaphores, waitable timers, processes, threads, console input,
    /// change notifications, and so on.
    ///
    /// # Safety
    ///
    /// The caller guarantees that:
    ///
    /// - the handle is a waitable object the thread pool supports, and in
    ///   particular is **not a mutex**, which the SDK does not support and which
    ///   yields undefined behaviour rather than an error; and
    /// - ownership transfers exclusively into the returned value, so nothing
    ///   else closes the handle while a wait on it is pending.
    #[must_use]
    pub unsafe fn assume_waitable(handle: OwnedHandle) -> Self {
        Self {
            target: WaitTarget::Owned(handle),
        }
    }

    /// Wrap a handle that must be closed with a routine other than
    /// `CloseHandle`.
    ///
    /// Some waitable objects have their own destructor: a
    /// `FindFirstChangeNotification` handle is closed with
    /// `FindCloseChangeNotification`, and handing it to
    /// [`assume_waitable`](Self::assume_waitable) --
    /// which takes a std [`OwnedHandle`] and therefore closes it with
    /// `CloseHandle` -- would be wrong. `close` is invoked exactly once, and
    /// only after the wait has been drained, whether the object is torn down by
    /// [`ThreadpoolWait`]'s own drop or by a
    /// [`CleanupGroup`](crate::cleanup_group::CleanupGroup) release.
    ///
    /// `close` has the shape Win32 close routines already have, so it can be
    /// passed directly with no wrapper.
    ///
    /// # Safety
    ///
    /// The caller guarantees that:
    ///
    /// - the handle is a waitable object the thread pool supports, and in
    ///   particular is **not a mutex**, which the SDK does not support and which
    ///   yields undefined behaviour rather than an error;
    /// - ownership transfers exclusively into the returned value, so nothing
    ///   else closes the handle while a wait on it is pending; and
    /// - `close` is the correct destructor for this handle and is safe to call
    ///   once on it after the pool has stopped watching it.
    #[must_use]
    pub unsafe fn assume_waitable_with(handle: HANDLE, close: WaitCloseFn) -> Self {
        Self {
            target: WaitTarget::Custom(CustomClose { raw: handle, close }),
        }
    }

    /// Borrow the underlying handle, for signalling or inspecting it.
    #[must_use]
    pub fn handle(&self) -> BorrowedHandle<'_> {
        self.target.borrow()
    }

    /// Consume the wrapper and recover the owned handle.
    ///
    /// # Errors
    ///
    /// Returns the wrapper back unchanged when it carries a custom close
    /// routine (see [`assume_waitable_with`](Self::assume_waitable_with)): an
    /// [`OwnedHandle`] closes what it holds with `CloseHandle`, which is
    /// precisely the wrong destructor for such a target, so there is no correct
    /// value to hand back. The handle is neither closed nor leaked -- ownership
    /// simply stays where it was.
    pub fn into_handle(self) -> Result<OwnedHandle, Self> {
        match self.target {
            WaitTarget::Owned(handle) => Ok(handle),
            target @ WaitTarget::Custom(_) => Err(Self { target }),
        }
    }

    /// Consume the wrapper and recover the owner, whichever kind it is.
    pub(crate) fn into_target(self) -> WaitTarget {
        self.target
    }
}

/// An event is always a target the pool supports, so this needs no `unsafe`.
///
/// An [`Event`] is guaranteed to be an event rather than a mutex -- adopting a
/// handle as one is `unsafe` in `win-sync-sys` for exactly this reason -- and
/// to carry the access a wait needs.
impl From<Event> for WaitableHandle {
    fn from(event: Event) -> Self {
        Self {
            target: WaitTarget::Owned(event.into()),
        }
    }
}

/// Why a wait callback ran.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum WaitResult {
    /// The watched handle became signalled.
    Signalled,
    /// The timeout given when the wait was armed elapsed first.
    TimedOut,
    /// The pool reported a result this crate does not model. The raw value is
    /// preserved so a caller can inspect it rather than having it discarded.
    Other(u32),
}

impl WaitResult {
    fn from_raw(value: u32) -> Self {
        match value {
            wait_status::SIGNALLED => Self::Signalled,
            WAIT_TIMEOUT => Self::TimedOut,
            other => Self::Other(other),
        }
    }
}

/// Heap-allocated callback state kept alive for the lifetime of the wait object.
///
/// `wait` is filled in after `CreateThreadpoolWait` returns, because rearming
/// from inside a callback needs the object the callback belongs to.
struct WaitContext {
    wait: AtomicIsize,
    handle: HANDLE,
    /// Stops a callback re-arming this wait once a teardown has begun.
    ///
    /// Arming takes this lock and does nothing while the count is non-zero, so
    /// a callback that re-arms cannot start watching again after a disarm from
    /// outside. Its two users here are [`ThreadpoolWait::stop_and_drain`],
    /// which raises and lowers it, and `Drop`, which raises it permanently --
    /// the asymmetry [`RearmSuppression`] is a count for. The lock is only ever
    /// held across the native `SetThreadpoolWait` call.
    rearm: RearmSuppression,
    /// Whether the object is armed with nothing having drained it.
    ///
    /// A dispatch settles it because `SetThreadpoolWait` arms for exactly one
    /// activation: once the callback has entered, the object is no longer
    /// watching, so there is nothing for `Drop` to wait on and nothing to
    /// report. A callback that re-arms sets it again, which is why this is
    /// cleared at trampoline entry rather than on the way out.
    obligation: crate::obligation::CloseObligation,
    /// This pool's entry in the self-heal registry.
    ///
    /// **The one registration that is read rather than only held.** A wait is
    /// the only object that reaches the removal primitive a cancellation owes a
    /// repair for, so `try_cancel_pending`, `recover_repair` and `owe_repair`
    /// all go through this field; the other four context types hold theirs
    /// purely for its `Drop`.
    ///
    /// On the context rather than on [`ThreadpoolWait`] so it survives
    /// [`into_parts`](ThreadpoolWait::into_parts) into a cleanup-group member,
    /// which is how the group reaches it after the object itself is gone.
    registration: crate::heal::Registration,
    callback: Box<dyn Fn(&WaitActivation<'_>) + Send + Sync + 'static>,
}

impl WaitContext {
    /// Lock the suppression count, recovering from a panicking holder.
    fn suppression(&self) -> std::sync::MutexGuard<'_, u32> {
        self.rearm.lock()
    }

    /// Start suppressing re-arming, and disarm under the same acquisition.
    ///
    /// Doing both under one lock is what makes the pair atomic against a
    /// callback: a re-arm either lands entirely before this, or is suppressed by
    /// it. The lock is released before any drain.
    fn suppress_and_disarm(&self) {
        self.rearm.suppress_and(|suppressed| {
            let wait = self.wait.load(Ordering::Acquire);
            crate::trace_record!("wait", "suppress-and-disarm", wait, suppressed);
            if wait == 0 {
                return;
            }
            // SAFETY: `wait` is this object's live PTP_WAIT, published before any
            // callback could run and valid until Drop closes it.
            unsafe { disarm_raw(wait) };
        });
    }

    /// Stop suppressing re-arming.
    fn release_suppression(&self) {
        self.rearm.release();
    }
}

// SAFETY: `handle` is a raw handle owned by the ThreadpoolWait that outlives
// this context; it is only passed back to SetThreadpoolWait, never closed here.
unsafe impl Send for WaitContext {}
unsafe impl Sync for WaitContext {}

/// One activation of a [`ThreadpoolWait`], handed to its callback.
///
/// The wait is not armed when the callback runs. Call [`WaitActivation::rearm`]
/// to watch the handle again; doing nothing leaves the wait idle.
pub struct WaitActivation<'ctx> {
    result: WaitResult,
    ctx: &'ctx WaitContext,
}

impl std::fmt::Debug for WaitActivation<'_> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // The context holds the boxed callback and the raw wait object, neither
        // of which is meaningful to a reader; the result is the whole story.
        f.debug_struct("WaitActivation")
            .field("result", &self.result)
            .finish_non_exhaustive()
    }
}

impl WaitActivation<'_> {
    /// Why this callback ran.
    #[must_use]
    pub fn result(&self) -> WaitResult {
        self.result
    }

    /// Whether the watched handle was signalled.
    #[must_use]
    pub fn is_signalled(&self) -> bool {
        self.result == WaitResult::Signalled
    }

    /// Borrow the handle this activation was for.
    ///
    /// The wait owns the handle and outlives every callback, so it is open for
    /// the duration of this borrow. This is what makes the documented way out of
    /// the overlap hazard on [`rearm`](Self::rearm) reachable: a callback
    /// watching a manual-reset event can reset it before re-arming, so the next
    /// activation waits for a fresh signal instead of starting immediately
    /// alongside this one.
    #[must_use]
    pub fn handle(&self) -> BorrowedHandle<'_> {
        // SAFETY: the wait owns this handle and cannot be dropped while a
        // callback is running, so it is open for at least this borrow.
        unsafe { BorrowedHandle::borrow_raw(self.ctx.handle) }
    }

    /// Arm the wait again, so the next signal or timeout activates it.
    ///
    /// `timeout` of `None` waits indefinitely. This is the mechanism the SDK
    /// requires for repeated waits: an activation consumes the arming, so a
    /// callback that wants to keep watching must rearm from inside itself.
    ///
    /// # This can overlap the callback with itself
    ///
    /// Re-arming takes effect immediately, and the pool activates as soon as the
    /// handle is signalled. If the handle is *still signalled* when this is
    /// called -- which is the normal state of a manual-reset event -- the next
    /// activation is queued at once and can begin before the current callback
    /// returns. Re-arming early in a long callback therefore runs it
    /// concurrently with itself, repeatedly: a 20ms callback that re-armed at
    /// its start was measured entering 7529 times in 400ms, 5110 of those
    /// overlapping an earlier entry.
    ///
    /// This is not the guarantee [`TimerFiring::rearm_after`] gives. A one-shot
    /// timer's re-arm is deferred until the callback returns, precisely so
    /// firings stay sequential; a wait's re-arm is not, because the SDK requires
    /// the wait to be re-armed for the handle's *current* signal state to be
    /// observed.
    ///
    /// Either reset the event before re-arming, so the next activation waits
    /// for a fresh signal -- through a clone of the `win-sync-sys` [`Event`]
    /// the wait was built from, which the callback keeps:
    ///
    /// ```no_run
    /// # fn example(activation: &windows_threadpool_sys::wait::WaitActivation<'_>, event: &win_sync_sys::Event) {
    /// // `event` is the callback's clone of the event this wait watches.
    /// event
    ///     .reset()
    ///     .expect("an event created here has the access to reset it");
    /// activation.rearm(None);
    /// # }
    /// ```
    ///
    /// or accept the concurrency and make everything the callback touches
    /// tolerate it. An auto-reset event does not have this problem, because the
    /// wait consumes the signal.
    ///
    /// [`TimerFiring::rearm_after`]: crate::timer::TimerFiring::rearm_after
    ///
    /// # Re-arm before the next signal
    ///
    /// The ordering rule described on [`ThreadpoolWait::arm`] applies to
    /// every arming, not just the first -- `SetThreadpoolWait` says the event
    /// must be re-registered "before signaling it each time". A producer that
    /// signals in the window after an activation consumed the arming but
    /// before this call re-establishes it may not get a callback for that
    /// signal.
    ///
    /// Re-arming *before* draining closes that window, at the cost of
    /// callbacks that find nothing to do; draining first and re-arming after
    /// leaves it open. A caller who cannot order the two can drain, re-arm,
    /// then drain again, so that anything which landed in the window is
    /// picked up by the second pass rather than waited for.
    ///
    /// # Teardown
    ///
    /// Re-arming after the object has begun tearing down does nothing, so a
    /// callback racing [`ThreadpoolWait`]'s `Drop` cannot leave the object armed
    /// behind it.
    pub fn rearm(&self, timeout: Option<Duration>) {
        let _ = self.rearm_reporting(timeout);
    }

    /// [`rearm`](Self::rearm), reporting whether the arming actually happened.
    ///
    /// Returns `false` when the request was suppressed because the object is
    /// tearing down. The public entry point discards this, because a caller
    /// cannot act on it: by the time it could look, the object is gone. Tests
    /// use it to observe the suppression directly, which is otherwise only
    /// visible as the absence of undefined behaviour.
    pub(crate) fn rearm_reporting(&self, timeout: Option<Duration>) -> bool {
        // Recorded *before* the lock, not after: the acquisition can block on a
        // concurrent `suppress_and_disarm`, and a re-arm parked on that mutex is
        // one of the things a silent interval in the trace could be. Entry and
        // exit straddling the lock is what tells the two apart.
        let wait = self.ctx.wait.load(Ordering::Acquire);
        crate::trace_record!("wait", "rearm-entered", wait);
        // Taken before arming and held across it, so this either happens before
        // a suppressing caller raises the count or is suppressed by it -- never
        // in between.
        let suppressed = self.ctx.suppression();
        if *suppressed > 0 {
            crate::trace_record!("wait", "rearm-suppressed", wait, *suppressed);
            return false;
        }
        debug_assert_ne!(
            wait, 0,
            "the wait object must be published before callbacks"
        );
        // Recorded before the arming is published, not after: by here the
        // suppression check has already returned, so the arming is certain to
        // happen, and a dispatch it produces can settle the obligation on
        // another thread before this one gets any further. See
        // `CloseObligation::record_live_before`.
        self.ctx.obligation.record_live_before(|| {
            // SAFETY: `wait` is this object's live PTP_WAIT, published before any
            // callback could run, and `handle` is owned by that object so it is
            // still open. The timeout, if any, is a live stack value for the call.
            unsafe { arm_raw(wait, self.ctx.handle, timeout) };
        });
        drop(suppressed);
        crate::trace_record!("wait", "rearm-left", wait, self.ctx.handle as usize);
        true
    }
}

/// Stop a raw wait object.
///
/// SAFETY: `wait` must be a live `PTP_WAIT`.
pub(crate) unsafe fn disarm_raw(wait: PTP_WAIT) {
    crate::trace_call!("SetThreadpoolWait(disarm)", wait, 0, {
        // SAFETY: forwarded; a null handle is the documented way to cancel a wait.
        unsafe { SetThreadpoolWait(wait, ptr::null_mut(), ptr::null()) };
    });
    crate::trace_record!("wait", "disarmed", wait);
}

/// Arm a raw wait object against a borrowed target.
///
/// SAFETY: `wait` must be a live `PTP_WAIT` and `target` must stay open until
/// the wait is disarmed or the object released.
pub(crate) unsafe fn arm_member(wait: PTP_WAIT, target: &WaitTarget, timeout: Option<Duration>) {
    // SAFETY: forwarded from this function's own contract.
    unsafe { arm_raw(wait, target.raw(), timeout) };
}

/// Arm or disarm a wait object.
///
/// SAFETY: `wait` must be a live `PTP_WAIT` and `handle` a live waitable handle
/// (or null to disarm).
unsafe fn arm_raw(wait: PTP_WAIT, handle: HANDLE, timeout: Option<Duration>) {
    crate::trace_call!("SetThreadpoolWait", wait, handle as usize, {
        match timeout {
            Some(timeout) => {
                let filetime = relative_filetime(timeout);
                // SAFETY: forwarded from this function's contract; `filetime` is
                // read only for the duration of the call.
                unsafe { SetThreadpoolWait(wait, handle, &filetime) };
            }
            // SAFETY: forwarded; a null timeout means "wait indefinitely".
            None => unsafe { SetThreadpoolWait(wait, handle, ptr::null()) },
        }
    });
    crate::trace_record!("wait", "armed", wait, handle as usize);
}

/// Trampoline from the raw `PTP_WAIT_CALLBACK` ABI into the boxed closure.
///
/// SAFETY: `context` must point to a live [`WaitContext`] for the entire
/// duration of every callback invocation, which [`ThreadpoolWait`]'s `Drop`
/// ordering guarantees.
unsafe extern "system" fn wait_trampoline(
    _instance: PTP_CALLBACK_INSTANCE,
    context: *mut core::ffi::c_void,
    _wait: PTP_WAIT,
    wait_result: u32,
) {
    crate::trace_record!("wait", "trampoline-entered", _wait, wait_result);
    // SAFETY: context is a valid *mut WaitContext for the full callback duration.
    let ctx = unsafe { &*(context as *const WaitContext) };
    // This activation consumed the arming: the pool is no longer watching, so
    // nothing is owed unless the callback below arms it again.
    ctx.obligation.record_settled();
    // Stamped before the callback, not after: a dispatch that is still running
    // is evidence the pool is live, and a long callback must not look like
    // silence to the self-heal.
    let activation = WaitActivation {
        result: WaitResult::from_raw(wait_result),
        ctx,
    };
    // Not contained: see the callback contract in the crate docs.
    (ctx.callback)(&activation);
    // Paired with the record above. The pair is what makes a silent interval
    // readable: an entry with no exit says a callback is still inside the
    // closure, which is a different finding from no entry at all.
    crate::trace_record!("wait", "trampoline-left", _wait, wait_result);
}

/// An owned thread-pool wait object bound to one waitable handle.
///
/// The object owns the handle, so the handle cannot be closed while a wait is
/// pending. A newly created wait is idle; arm it with [`ThreadpoolWait::arm`],
/// and rearm from inside the callback with [`WaitActivation::rearm`].
///
/// [`Drop`] disarms before draining callbacks, then closes the object and only
/// afterwards releases the callback context and the handle.
///
/// Unlike [`ThreadpoolTimer`](crate::timer::ThreadpoolTimer), **the callback can
/// run concurrently with itself**: a wait's re-arm takes effect immediately, so
/// re-arming while the handle is still signalled queues the next activation
/// before the current callback returns. See [`WaitActivation::rearm`] for the
/// measurements and the two ways to avoid it.
///
/// # Examples
///
/// Watch an event once. The wait takes ownership of the handle it is given, so
/// keep a clone of the [`Event`] -- a second handle to the same event -- to
/// signal it through:
///
/// ```
/// use std::sync::mpsc;
/// use win_sync_sys::{Event, ResetMode};
/// use windows_threadpool_sys::wait::{ThreadpoolWait, WaitResult};
///
/// let event = Event::new(ResetMode::Manual, false)?;
/// let signal = event.try_clone()?;
///
/// let (tx, rx) = mpsc::channel();
/// let sender = std::sync::Mutex::new(tx);
/// let wait = ThreadpoolWait::new(event.into(), move |activation| {
///     let _ = sender.lock().expect("send").send(activation.result());
/// }, None)?;
///
/// wait.arm(None);
/// signal.set()?;
///
/// assert_eq!(rx.recv().expect("activation"), WaitResult::Signalled);
/// # Ok::<(), std::io::Error>(())
/// ```
///
/// Keep watching across activations by rearming from inside the callback, which
/// is what the SDK requires -- an activation consumes the arming:
///
/// ```
/// # use std::sync::Arc;
/// # use std::sync::atomic::{AtomicUsize, Ordering};
/// use win_sync_sys::{Event, ResetMode};
/// use windows_threadpool_sys::wait::ThreadpoolWait;
///
/// let event = Event::new(ResetMode::Auto, false)?;
/// let signal = event.try_clone()?;
///
/// let seen = Arc::new(AtomicUsize::new(0));
/// let counter = Arc::clone(&seen);
/// let wait = ThreadpoolWait::new(event.into(), move |activation| {
///     counter.fetch_add(1, Ordering::SeqCst);
///     activation.rearm(None);
/// }, None)?;
///
/// wait.arm(None);
/// for _ in 0..3 {
///     signal.set()?;
///     std::thread::sleep(std::time::Duration::from_millis(5));
/// }
///
/// // Disarms and drains in one step, discharging the drain this wait owes
/// // rather than leaving the blocking teardown to `Drop`.
/// wait.stop_and_drain();
/// assert!(seen.load(Ordering::SeqCst) >= 1);
/// # Ok::<(), std::io::Error>(())
/// ```
pub struct ThreadpoolWait {
    wait: PTP_WAIT,
    target: WaitTarget,
    // Kept alive as a raw pointer until Drop has disarmed and drained.
    context: *mut WaitContext,
}

// SAFETY: PTP_WAIT is a cross-thread pool object, WaitTarget is Send + Sync,
// and the context is Send + Sync; the pointer is only read until Drop frees it
// after all callbacks have finished.
unsafe impl Send for ThreadpoolWait {}
unsafe impl Sync for ThreadpoolWait {}

impl ThreadpoolWait {
    /// Create an idle wait watching `handle`.
    ///
    /// The object takes ownership of the handle and closes it on drop, which is
    /// what guarantees the handle outlives any pending wait.
    ///
    /// Pass `Some(env)` to select a private pool or callback priority; `None`
    /// uses the process-default pool with default priority.
    ///
    /// The callback runs on a shared, process-managed pool thread, must restore
    /// any thread state it changes, and must not terminate its thread. It must
    /// not panic: a panic unwinds to the `extern "system"` trampoline and aborts
    /// the process.
    ///
    /// Taking a [`WaitableHandle`] rather than a bare handle is what keeps this
    /// constructor safe: the thread pool does not support every waitable object,
    /// and a mutex handle in particular is undefined rather than an error.
    ///
    /// # Errors
    ///
    /// Returns the error from `CreateThreadpoolWait`.
    pub fn new<F>(
        handle: WaitableHandle,
        callback: F,
        env: Option<&mut CallbackEnviron<'_>>,
    ) -> io::Result<Self>
    where
        F: Fn(&WaitActivation<'_>) + Send + Sync + 'static,
    {
        let target = handle.into_target();
        // Read before `env` is consumed below, and registered before the object
        // exists: the entry must be able to repair this pool from the moment
        // anything of ours can dispatch on it.
        let registration = crate::heal::register(crate::heal::key_of(env.as_deref()));
        let context = Box::into_raw(Box::new(WaitContext {
            wait: AtomicIsize::new(0),
            handle: target.raw(),
            rearm: RearmSuppression::new(),
            obligation: crate::obligation::CloseObligation::new(),
            registration,
            callback: Box::new(callback),
        }));
        let env_ptr = env.map_or(ptr::null_mut(), |e| e.as_mut_ptr());

        // SAFETY: context is a valid heap pointer that outlives every callback,
        // and env_ptr is valid (or null) for the duration of this call.
        let wait = crate::trace_call!("CreateThreadpoolWait", 0, 0, {
            // SAFETY: context is a valid heap pointer that outlives every callback,
            // and env_ptr is valid (or null) for the duration of this call.
            unsafe {
                CreateThreadpoolWait(Some(wait_trampoline), context.cast(), env_ptr.cast_const())
            }
        });

        if wait == 0 {
            let error = io::Error::last_os_error();
            // SAFETY: the pool never saw context; reclaim it immediately.
            unsafe { drop(Box::from_raw(context)) };
            return Err(error);
        }

        // Publish the object before any callback can run. No wait is armed yet,
        // so no callback can observe the unpublished value.
        // SAFETY: context is live and exclusively ours until the first arming.
        unsafe { (*context).wait.store(wait, Ordering::Release) };
        crate::trace_record!("wait", "created", wait, target.raw() as usize);

        Ok(Self {
            wait,
            target,
            context,
        })
    }

    /// Borrow the watched handle, for signalling or inspecting it.
    #[must_use]
    pub fn handle(&self) -> BorrowedHandle<'_> {
        self.target.borrow()
    }

    /// Arm the wait, so the next signal or timeout runs the callback once.
    ///
    /// `timeout` of `None` waits indefinitely. Arming replaces any previous
    /// arming rather than adding to it, and an activation consumes the arming --
    /// rearm from inside the callback with [`WaitActivation::rearm`] to keep
    /// watching.
    ///
    /// # Arm before you signal
    ///
    /// `SetThreadpoolWait` documents that "you must re-register the event with
    /// the wait object before signaling it each time to trigger the wait
    /// callback". Signal a handle that is not currently armed -- including in
    /// the window between constructing a [`ThreadpoolWait`] and this call --
    /// and the callback is not guaranteed to run for that signal.
    ///
    /// An auto-reset event makes a dropped signal permanent rather than merely
    /// late, because the signal is consumed and there is nothing left for a
    /// subsequent arming to observe. If the handle is only ever signalled once,
    /// as a wakeup for state that is already present, that lost signal is the
    /// last one the waiter will ever get.
    ///
    /// Every example in this module arms first for that reason; so does every
    /// caller in this workspace. A caller who cannot control the ordering
    /// should watch a manual-reset event kept in agreement with the state it
    /// reports, which is level-triggered and so has no signal to lose.
    pub fn arm(&self, timeout: Option<Duration>) {
        // SAFETY: the context outlives every callback and is freed only by Drop,
        // which cannot run while this borrow of self is alive.
        unsafe { &*self.context }.obligation.record_live_before(|| {
            // SAFETY: `wait` is valid for the lifetime of self, and the handle is
            // owned by self so it is still open.
            unsafe { arm_raw(self.wait, self.target.raw(), timeout) };
        });
    }

    /// Stop watching.
    ///
    /// New activations stop being queued, but a callback already queued still
    /// runs; use `try_cancel_pending`, or
    /// [`try_cancel_pending_no_heal_tracking`](Self::try_cancel_pending_no_heal_tracking)
    /// in a build without the `self-heal` feature, to drop those as well.
    pub fn disarm(&self) {
        crate::trace_call!("SetThreadpoolWait(disarm)", self.wait, 0, {
            // SAFETY: `wait` is valid for the lifetime of self; a null handle is the
            // documented way to cancel a pending wait.
            unsafe { SetThreadpoolWait(self.wait, ptr::null_mut(), ptr::null()) };
        });
        crate::trace_record!("wait", "disarmed", self.wait);
    }

    /// Let every queued callback run, and block until none is executing.
    ///
    /// This does **not** leave a self-re-arming wait idle: a callback running
    /// during this call can [`rearm`](WaitActivation::rearm) before it returns,
    /// so the object is watching again when this returns. Use
    /// [`stop_and_drain`](Self::stop_and_drain) to reach quiescence.
    pub fn wait(&self) {
        crate::trace_call!("WaitForThreadpoolWaitCallbacks", self.wait, 0, {
            // SAFETY: `wait` is valid for the lifetime of self.
            unsafe { WaitForThreadpoolWaitCallbacks(self.wait, FALSE) };
        });
    }

    /// Drop callbacks that have not started, then wait for any executing one.
    ///
    /// Like [`wait`](Self::wait), this does not by itself leave a self-re-arming
    /// wait idle: it does not suppress the re-arm of a callback that is already
    /// running. Use [`stop_and_drain`](Self::stop_and_drain) when the wait must
    /// actually be quiescent afterwards.
    ///
    /// # This brings a process-wide hazard forward; it does not create it
    ///
    /// Cancelling asks the kernel to remove a completion packet that may already
    /// have been delivered to the pool's completion port
    /// (`IopCancelWaitCompletionPacket` with `RemoveSignaledPacket` set).
    /// Measured on this workspace's reproducer, a removal that lands a few
    /// microseconds after the packet was queued, on a port whose factory has no
    /// threads yet, can **sever the notification from that port to the worker
    /// factory**.
    ///
    /// The scope of that is one pool -- but it is the whole of that pool, not
    /// this wait and not waits as a kind. Measured during such a stall: already
    /// armed waits, a freshly armed and signalled wait, a fresh timer, and a
    /// completed overlapped read all fail to dispatch. A second pool in the same
    /// process is unaffected. Since the pool normally affected is the **default**
    /// one, the practical reach is every component in the process that did not
    /// explicitly create its own -- including code that has nothing to do with
    /// the caller.
    ///
    /// Submitting a work item recovers it, because that reaches the factory by a
    /// route the broken notification is not on. Nothing else observed does.
    ///
    /// **But this method is not the only way to reach that, and on the measured
    /// evidence it is not even the usual one.** `CloseThreadpoolWait` performs
    /// the same removal, through the same kernel routine with the same flag,
    /// whenever it finds a packet still outstanding -- so a teardown that never
    /// calls this method reaches the hazard anyway. In the reproducer, dropping
    /// the cancel entirely changed nothing measurable: 22 failures in 20004
    /// without it against 16 with it.
    ///
    /// What this method does is perform the removal *earlier*, which removes any
    /// chance for the callback to run first.
    ///
    /// The fix is therefore not to avoid this method but to leave nothing to
    /// remove: [`wait`](Self::wait) and [`stop_and_drain`](Self::stop_and_drain)
    /// let the queued callback run, which clears the association, after which the
    /// close has nothing to take. Draining cannot reach the removal primitive on
    /// any path. Prefer them -- but note that doing so is what makes the
    /// *subsequent close* safe, not merely this call.
    /// This crate repairs the pool afterwards, which is what makes this safe to
    /// offer -- with one exception, stated because a guarantee with an unstated
    /// hole is worse than one that names it.
    ///
    /// If this object's pool could not be registered for repair when the object
    /// was created, which happens only when creating the repair work item
    /// failed, this call registers it **here** rather than giving up. Only when
    /// that allocation fails too is the cancellation performed with nothing to
    /// repair it, and that case records `cancel-untracked` on the `heal` target
    /// -- naming the pool -- and panics under the `fail-fast` feature. See
    /// [README-FEATURE-self-heal.md](https://docs.rs/crate/windows-threadpool-sys/latest/source/README-FEATURE-self-heal.md).
    ///
    /// # Availability
    ///
    /// Requires the `self-heal` feature, which is on by default. Without it this
    /// method does not exist and a call to it fails to compile, naming
    /// [`try_cancel_pending_no_heal_tracking`](Self::try_cancel_pending_no_heal_tracking)
    /// as what to reach for instead. That is the designed behaviour, not an
    /// oversight: a guarantee you were relying on has been removed, and a
    /// compile error is the only way you find that out.
    #[cfg(feature = "self-heal")]
    pub fn try_cancel_pending(&self) {
        // SAFETY: the obligation this transfers is discharged here, by marking
        // the pool so the self-heal repairs it.
        unsafe { self.try_cancel_pending_no_heal_tracking() };
        // SAFETY: the context outlives every callback and is freed only by Drop,
        // which cannot run while this borrow of self is alive.
        let tracked = unsafe { &*self.context }.registration.owe_repair();
        // Last in the function, so the panic this may raise cannot skip the
        // marking above -- the same placement rule the drop fail-fast follows.
        crate::obligation::fail_fast_if_untracked(tracked, "ThreadpoolWait");
    }

    /// `try_cancel_pending` without the repair.
    ///
    /// Not a link, deliberately: the method it would name does not exist in a
    /// build with `self-heal` off, and this one does, so the link would dangle
    /// in exactly the configuration this method exists for.
    ///
    /// Always present, including in builds with `self-heal` off, which is the
    /// point: it is the method that still exists when the gated one does not,
    /// and its signature says what the caller takes on.
    ///
    /// # Safety
    ///
    /// The caller must ensure the pool is repaired. Submitting any work item to
    /// it does so; so does knowing the pool is kept live by something else.
    /// Leaving it unrepaired can stop the pool dispatching -- which, for the
    /// process-default pool, reaches every component in the process, including
    /// code with no connection to this call.
    ///
    /// This is not a memory-safety obligation, and the keyword is not claiming
    /// one. It is here because the obligation is statable and dischargeable by
    /// the caller, which is what `unsafe` marks; see
    /// [the self-heal decision](https://docs.rs/crate/windows-threadpool-sys/latest/source/DESIGN-NOTES.md).
    pub unsafe fn try_cancel_pending_no_heal_tracking(&self) {
        crate::trace_call!("WaitForThreadpoolWaitCallbacks(cancel)", self.wait, 1, {
            // SAFETY: `wait` is valid for the lifetime of self. A cancelled wait
            // callback owns no storage, so dropping queued callbacks orphans nothing.
            unsafe { WaitForThreadpoolWaitCallbacks(self.wait, TRUE) };
        });
    }

    /// Take a repair claim on this wait's pool while the object is still live.
    ///
    /// For [`crate::cleanup_group::CleanupGroup`], which must do this *before*
    /// its native release: a member whose pool was never registered holds
    /// nothing that keeps that pool alive, and the release frees the last bound
    /// object. The claim this returns owns a repair work object bound to the
    /// pool, so holding it across the release keeps the pool alive for the
    /// marking pass that follows.
    ///
    /// # Safety
    ///
    /// `context` must come from [`into_parts`](Self::into_parts) on this type
    /// and name a still-live object whose context the caller has not yet freed.
    pub(crate) unsafe fn recover_repair(
        context: *mut core::ffi::c_void,
    ) -> Option<crate::heal::Registration> {
        // SAFETY: forwarded; the context outlives the member until the group
        // frees it, and this only touches that object's registration.
        let ctx = unsafe { &*context.cast::<WaitContext>() };
        Some(ctx.registration.reclaim())
    }

    /// Mark this wait's pool as owing a repair, retrying the registration.
    ///
    /// Gated because its only caller is `WaitMember::try_cancel_pending`, which
    /// the feature gates too. It was reachable in every configuration until
    /// `M-T11.4` removed the `OwnedResource` hook that named it: the group's
    /// marking pass now goes through the claims, which is what the retry here
    /// must not be reached from.
    ///
    /// Reports whether the pool ended up tracked. A caller that accumulates
    /// this across several members must act on it only after every context is
    /// freed -- never mid-loop, where an unwind would skip those frees.
    ///
    /// # Safety
    ///
    /// `context` must come from [`into_parts`](Self::into_parts) on this type
    /// and name a still-live object whose context the caller has not yet freed.
    #[cfg(feature = "self-heal")]
    #[must_use]
    pub(crate) unsafe fn owe_repair(context: *mut core::ffi::c_void) -> bool {
        // SAFETY: forwarded; the context outlives the member until the group
        // frees it, and this only touches that object's registration.
        let ctx = unsafe { &*context.cast::<WaitContext>() };
        ctx.registration.owe_repair()
    }

    /// Stop watching and block until the wait is idle, leaving it reusable.
    ///
    /// This exists because neither [`disarm`](Self::disarm) nor
    /// `try_cancel_pending` can stop a self-re-arming wait on
    /// its own: a callback already running can call [`WaitActivation::rearm`]
    /// after a disarm from outside has taken effect. This suppresses re-arming
    /// for the duration of the call, using the same mechanism `Drop` uses, and
    /// lifts the suppression before returning so the wait can be armed again.
    ///
    /// # What this guarantees
    ///
    /// On return, provided no other thread arms the wait during the call:
    ///
    /// - no callback is queued or executing, and
    /// - the object is not watching -- a re-arm requested by a callback that ran
    ///   during the call is discarded rather than deferred.
    ///
    /// **A queued callback runs; it is not discarded.** That is the difference
    /// between this and `try_cancel_pending`, and it is why
    /// this can block for as long as the callback takes. See
    /// [the teardown-drains decision](../../../DESIGN-NOTES.md#teardown-drains)
    /// for why finishing the work is preferred to abandoning it.
    ///
    /// # What it does not
    ///
    /// **A concurrent [`arm`](Self::arm) from another thread is not excluded.**
    /// `ThreadpoolWait` is `Sync` and `arm` takes `&self`, so it does not pass
    /// through the suppression this uses, and nothing in this crate orders such
    /// a call against this one. A caller needing the wait to be provably idle
    /// must ensure nothing else arms it for the duration, by owning it
    /// exclusively or serializing access to it.
    ///
    /// Calling this from inside the wait's own callback would deadlock, because
    /// it waits for that callback to finish.
    pub fn stop_and_drain(&self) {
        // SAFETY: the context outlives every callback and is freed only by Drop,
        // which cannot run while this borrow of self is alive.
        unsafe { Self::stop_and_drain_parts(self.context.cast(), self.wait) };
    }

    /// [`stop_and_drain`](Self::stop_and_drain) against a detached context.
    ///
    /// One body rather than two, so this type and the cleanup-group member that
    /// wraps the same object cannot drift apart: the suppression discipline here
    /// is what makes the drain mean anything, and a second copy of it is a
    /// second place for a later change to reach one and miss the other.
    ///
    /// # Safety
    ///
    /// `context` must come from [`into_parts`](Self::into_parts) on this type
    /// and name a still-live object whose context the caller has not yet freed,
    /// and `wait` must be that object.
    pub(crate) unsafe fn stop_and_drain_parts(context: *mut core::ffi::c_void, wait: PTP_WAIT) {
        // SAFETY: forwarded from this function's own contract.
        let ctx = unsafe { &*context.cast::<WaitContext>() };
        ctx.suppress_and_disarm();
        // Drained with the lock released: a callback blocked on it would
        // otherwise never finish, and this would never return.
        crate::trace_call!("WaitForThreadpoolWaitCallbacks", wait, 0, {
            // SAFETY: `wait` is live, and waiting without cancelling cannot
            // orphan any storage.
            unsafe { WaitForThreadpoolWaitCallbacks(wait, FALSE) };
        });
        // Settled after the drain, not before: a callback running during it may
        // have asked to re-arm, and the suppression discards that request, so
        // the object really is idle here. Releasing the suppression below lets a
        // later `arm` make it live again, which sets this afresh.
        ctx.obligation.record_settled();
        ctx.release_suppression();
    }

    /// Give up ownership, returning the raw object, its callback context, and
    /// the watched target.
    ///
    /// Used only by [`crate::cleanup_group::CleanupGroup`], which takes over all
    /// three. The target must go with them: the pool may still be watching it
    /// until the group releases the member, so it cannot be closed when the
    /// borrowing member goes out of scope.
    pub(crate) fn into_parts(self) -> (PTP_WAIT, *mut core::ffi::c_void, WaitTarget) {
        let this = std::mem::ManuallyDrop::new(self);
        // SAFETY: `this` is never dropped, so moving the target out cannot be
        // observed by a later drop of the original value.
        let target = unsafe { ptr::read(&this.target) };
        (this.wait, this.context.cast(), target)
    }

    /// Free a context returned by [`ThreadpoolWait::into_parts`].
    ///
    /// # Safety
    ///
    /// `context` must come from `into_parts` on this type, its object must
    /// already have been released, and it must be freed exactly once.
    pub(crate) unsafe fn drop_context(context: *mut core::ffi::c_void) {
        // SAFETY: forwarded from this function's own contract.
        drop(unsafe { Box::from_raw(context.cast::<WaitContext>()) });
    }

    /// Whether `Drop` would report an undischarged drain obligation right now.
    ///
    /// Exists so the obligation's wiring can be asserted without depending on
    /// the trace, whose filter is fixed before `main` and so cannot be narrowed
    /// from inside a test.
    #[cfg(test)]
    pub(crate) fn obligation_owed(&self) -> bool {
        // SAFETY: the context outlives every callback and is freed only by Drop.
        unsafe { &*self.context }.obligation.is_owed()
    }

    /// Suppress this member's re-arm and disarm it, before a
    /// [`crate::cleanup_group::CleanupGroup`] bulk-releases its members.
    ///
    /// `CloseThreadpoolCleanupGroupMembers` waits for executing callbacks but
    /// does not stop one from re-arming: a callback still running can call
    /// [`WaitActivation::rearm`] after the bulk release has begun, which would
    /// re-arm an object being torn down and then free its context under a freshly
    /// queued callback. Raising the suppression before the release closes that
    /// door, exactly as this type's own `Drop` does; the suppression is never
    /// lifted because the member is being destroyed.
    ///
    /// # Safety
    ///
    /// `context` must come from [`into_parts`](Self::into_parts) on this type
    /// and name a still-live object whose context the caller has not yet freed.
    pub(crate) unsafe fn prepare_shutdown(context: *mut core::ffi::c_void) {
        // SAFETY: forwarded; the context outlives the member until the group
        // frees it, and `suppress_and_disarm` only touches this object.
        let ctx = unsafe { &*context.cast::<WaitContext>() };
        ctx.suppress_and_disarm();
    }
}

impl Drop for ThreadpoolWait {
    fn drop(&mut self) {
        // Close the door on re-arming before disarming, and do both under the
        // same lock. Disarming alone is not enough: a callback already running
        // could re-arm afterwards, the drain below could then return with the
        // object armed, and the close and context free would race a freshly
        // queued callback.
        // SAFETY: the context outlives every callback; Drop frees it below,
        // after the drain.
        let ctx = unsafe { &*self.context };
        // Raised and never released: unlike `stop_and_drain`, there is no
        // afterwards for this object.
        crate::trace_record!("wait", "drop-begin", self.wait, self.target.raw() as usize);
        // Read before the disarm and drain, and emitted before them: the record
        // marks the start of the blocking interval it reports, so a reader sees
        // what the following gap is for rather than learning it afterwards.
        // Captured, not re-read later: a callback dispatched during the drain
        // below settles the obligation, so asking afterwards would find nothing
        // owed on exactly the objects that owed something. The context is also
        // freed before the fail-fast, so this must be a value rather than a
        // borrow.
        let owed = ctx.obligation.is_owed();
        if owed {
            crate::trace_record!("wait", crate::obligation::DROP_OBLIGATION_OWED, self.wait);
        }
        ctx.suppress_and_disarm();
        // The lock is released before draining: a callback blocked on it would
        // otherwise never finish, and this wait would never return.
        self.wait();
        crate::trace_record!("wait", "drop-drained", self.wait);

        // SAFETY: no callback can be queued or executing, so the object can be
        // closed and the context freed exactly once. `target` is dropped after
        // this, when its field is dropped, so the handle outlives the wait
        // object and its close routine -- `CloseHandle` or a custom one -- runs
        // only once the pool has stopped watching it.
        crate::trace_call!("CloseThreadpoolWait", self.wait, 0, {
            unsafe { CloseThreadpoolWait(self.wait) };
        });
        // SAFETY: as above; the pool can no longer reach the context.
        unsafe {
            drop(Box::from_raw(self.context));
        }
        // The last record this object emits, and it carries the target handle
        // because nothing after it can: the close of that handle is the field
        // drop that runs the instant this body returns, with no code of ours in
        // between. So the interval from `drop-drained` to the handle's close
        // holds exactly `CloseThreadpoolWait`, the context free, and that field
        // drop -- a reader who sees a gap there is looking at one of those three
        // and not at something unrecorded.
        crate::trace_record!("wait", "drop-closed", self.wait, self.target.raw() as usize);
        // Last, after the drain, the close and the context free. A panic
        // unwinds, so anything after it would be skipped; the target handle
        // still closes, because field drops run even when `Drop::drop` unwinds.
        crate::obligation::fail_fast_if_owed(owed, "ThreadpoolWait", "stop_and_drain");
    }
}

#[cfg(test)]
mod tests;