Event Functions

The following functions are available to create an event object and set its state.

Using RtCreateEvent

A thread uses the RtCreateEvent function to create an event object. The creating thread specifies the initial state of the object and whether it is a manual-reset or auto-reset event object. The creating thread can also specify a name for the event object. Threads in other processes can open a handle of an existing event object by specifying its name in a call to RtOpenEvent. For additional information about names for objects, see Object Names.

Using RtPulseEvent

A thread can use RtPulseEvent to set the state of an event object to signaled and then reset it to non-signaled after releasing the appropriate number of waiting threads. For a manual-reset event object, all waiting threads are released. For an auto-reset event object, the function releases only a single waiting thread, even if multiple threads are waiting. If no threads are waiting, RtPulseEvent simply sets the state of the event object to nonsignaled and returns.

Using RtSetEvent

RtSetEvent sets the state of the specified event object to signaled. The state of a manual-reset event object remains signaled until it is set explicitly to the non-signaled state by the RtResetEvent function. Any number of waiting threads, or threads that subsequently begin wait operations for the specified event object by calling the wait functions, can be released while the object's state is signaled.

In the case of an auto-reset event object, the RtSetEvent function resets the state to non-signaled and returns after releasing, or the event remains signaled until a single waiting thread is released, at which time the system automatically sets the state to non-signaled. If no threads are waiting, the event object's state remains signaled.

Using RtResetEvent

RtResetEvent sets the state of the specified event object to non-signaled. The state of an event object remains non-signaled until it is explicitly set to signaled by the RtSetEvent or RtPulseEvent function. The non-signaled state blocks the execution of any threads that have specified the event object in a call to a wait function.

The RtResetEvent function is used primarily for manual-reset event objects, which must be set explicitly to the non-signaled state. Auto-reset event objects automatically change from signaled to non-signaled after a single waiting thread is released.

RtWaitForSingleObject and RtWaitForMultipleObjects

You use RtWaitForSingleObject and RtWaitForMultipleObjects to wait for an interprocess communication object (IPC) to become available. IPC objects include semaphores, mutexes, and events.

RtWaitForSingleObject waits for one RTX64 IPC object at a time. A thread can wait for a specified amount of time, after which processing continues even if the object is not signaled, or an infinite amount of time (the thread waits indefinitely until the object is signaled).

RtWaitForMultipleObjects waits for up to 16 RTX64 IPC objects. The first object to become available causes the wait to be broken. The RtWaitForMultipleObjects function only supports WAIT FOR ANY object, making it possible for processing to start before all the objects the thread is waiting for are signaled.