Struct Event 

pub struct Event { /* private fields */ }

An owned event object.

Holds a handle to an event, shared by every clone, and closes it when the last clone drops. A clone is a second holder of the same handle, not a new handle: setting through one is seen through every other (WS-D-10). Because the handle is owned and is known to be an event, set and reset need no unsafe.

The handle being an event is what other crates may rely on (WS-D-4). Ownership alone keeps set memory-safe; it is event-ness that lets a consumer such as the thread pool, which cannot wait on a mutex, accept an Event without unsafe. That is why adopting an existing handle, from_owned_handle, is unsafe.

Setting and resetting take &self: they are atomic kernel operations, and an Event is Send and Sync. Setting an event that is already signalled changes nothing – an event is either signalled or not, and does not count how often it was set.

There is no pulse; see the crate documentation for why.

Implementations

impl Event

pub fn new(reset: ResetMode, initially_signalled: bool) -> Result<Event, Error>

Create an unnamed event.

Errors

Returns the error from CreateEventW. No test reaches this path: creating an unnamed event fails only when the process cannot get another handle or the kernel cannot allocate the object, which a test can produce only by exhausting a resource the rest of the run needs.

pub unsafe fn from_owned_handle(handle: OwnedHandle) -> Event

Adopt a handle the caller already owns as an event.

For an event that came from somewhere this crate did not create it, such as another library or a handle passed in by a parent process.

A handle without EVENT_MODIFY_STATE access is accepted: set and reset then report the access error rather than changing the event.

Safety

The caller guarantees that handle:

• refers to an event object – not a mutex, a semaphore or any other kind, because code holding an Event may rely on that; and
• carries SYNCHRONIZE access, so that anything given the Event to wait on can wait on it. What a thread-pool wait does with a handle it cannot wait on is not documented, and an Event must be safe to hand it.

pub fn set(&self) -> Result<(), Error>

Set the event to signalled.

Releases one waiter if the event is ResetMode::Auto, and every waiter until it is reset if it is ResetMode::Manual. Setting an event that is already signalled succeeds and changes nothing.

Errors

Returns the error from SetEvent: an access-denied error when the handle was adopted without EVENT_MODIFY_STATE.

pub fn reset(&self) -> Result<(), Error>

Set the event to unsignalled.

Resetting an event that is already unsignalled succeeds and changes nothing. Resetting an auto-reset event withdraws a signal no waiter has taken yet.

Errors

Returns the error from ResetEvent: an access-denied error when the handle was adopted without EVENT_MODIFY_STATE.

pub fn try_into_owned(self) -> Result<OwnedHandle, Event>

The handle, as an OwnedHandle, if self is its last holder.

Errors

If a clone still holds the handle, returns self unchanged, so nothing is lost and the caller can try again once the clones have dropped.

pub fn duplicate_wait_only(&self) -> Result<WaitOnlyEvent, Error>

A new handle to the same event that can wait on it and do nothing else: the one operation here that makes a handle, because access belongs to a handle and narrowing it needs a new one (WS-D-10).

The handle carries SYNCHRONIZE access alone, so it can neither set nor reset the event: the kernel refuses a SetEvent or ResetEvent on it. A clone cannot give that, since it shares the original’s handle and so its access. See WaitOnlyEvent for what the result is, why it is not an Event, and what the guarantee does not cover.

A wait through it takes what a signalled event gives, as any wait does: waiting through a wait-only handle consumes an auto-reset event’s signal. What it cannot do is signal or withdraw one.

Errors

Returns the error from DuplicateHandle. Like new’s, no test reaches it: duplicating a handle this process owns fails only when the process cannot get another handle.

Trait Implementations

impl AsHandle for Event

fn as_handle(&self) -> BorrowedHandle<'_>

Borrows the handle.

impl AsRawHandle for Event

fn as_raw_handle(&self) -> *mut c_void

Extracts the raw handle.

impl Clone for Event

fn clone(&self) -> Event

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Event

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

Formats the value using the given formatter.

impl From<Event> for SharedHandle

The shared handle, given up by this holder: what a consumer that holds handles shared, such as the thread pool’s wait target, takes.

fn from(event: Event) -> SharedHandle

Converts to this type from the input type.

impl Signalable for Event