Struct Event 

pub struct Event { /* private fields */ }

An owned event object.

Holds a handle to an event and closes it on drop. 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_clone(&self) -> Result<Event, Error>

A second handle to the same event, with the same access.

Setting or resetting either affects both, and the event lives until every handle to it is closed, so a clone may outlive the original.

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.

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

A second handle to the same event that can wait on it and do nothing else.

The handle carries SYNCHRONIZE access alone, so it can neither set nor reset the event: the kernel refuses a SetEvent or ResetEvent on it. That is something try_clone cannot give, since its clone holds whatever access the original does. 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 try_clone’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 Debug for Event

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

Formats the value using the given formatter.

impl Signalable for Event