Struct WaitableHandle 

pub struct WaitableHandle { /* private fields */ }

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 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.

Implementations

impl WaitableHandle

pub fn event(manual_reset: bool, initially_signalled: bool) -> Result<Self>

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.

Errors

Returns the error from CreateEventW.

pub unsafe fn assume_waitable(handle: OwnedHandle) -> Self

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.

pub unsafe fn assume_waitable_with(handle: HANDLE, close: WaitCloseFn) -> Self

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 – 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 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.

pub fn handle(&self) -> BorrowedHandle<'_>

Borrow the underlying handle, for signalling or inspecting it.

pub fn into_handle(self) -> Result<OwnedHandle, Self>

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): 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.

Trait Implementations

impl Debug for WaitableHandle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.