RtkWaitForSingleObject

RtkWaitForSingleObject allows a thread to wait on an object to be signaled.

Syntax

Copy

NTSTATUS RtkWaitForSingleObject(
    [in]    RTSSINST RtssInst,
    [in]    HANDLE Handle,
    [in]    ULONG Milliseconds
);

Parameters

[in] RtssInst

An RTSSINST value returned from a call to RtkRtssAttach or RtkRtssAttachEx. Pass a valid RTSSINST value or the call will fail with STATUS_INVALID_PARAMETER.

[in] Handle

A handle to an open object handle. See the list of the object types whose handles can be specified in the Comments section.

[in] Milliseconds

The time-out interval, in milliseconds. The function returns if the interval elapses, even if the object's state is non-signaled. If Milliseconds is zero, the function tests the object's state and returns immediately. If Milliseconds is INFINITE, the function's time-out interval never elapses.

Return Value

If the function succeeds, it returns STATUS_SUCCESS. If the function fails, it returns a different value.

Possible return values:

Return value	Meaning
STATUS_ABANDONED_WAIT_0 (WAIT_ABANDONED)	The specified object is a mutex object that was not released by the thread that owned the mutex object before the owning thread terminated. Ownership of the mutex object is granted to the calling thread, and the mutex is set to non-signaled.
STATUS_SUCCESS	The state of the specified object is signaled.
STATUS_UNSUCCESSFUL	If the function fails to wait.
STATUS_INVALIDPARAMETER	If functions fail with invalid parameters.

Remarks

RtkWaitForSingleObject checks the specified object's current state. If the object's state is non-signaled, the calling thread enters an efficient wait state. The thread consumes very little processor time while waiting for the object state to become signaled or the time-out interval to elapse.

Before returning, a wait function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the function to return. For example, the count of a semaphore object is decreased by one.

RtkWaitForSingleObject can wait for the following objects:

Event – The RtkCreateEvent or RtkOpenEvent function returns the handle. The RtkSetEvent or RtkPulseEvent function explicitly sets an event object's state to signaled. The RtkResetEvent function must explicitly reset a manual-reset event object's state to non-signaled. For an auto-reset event object, the wait function resets the object's state to non-signaled before returning.
Mutex – RtkCreateMutex and RtkOpenMutex return handles to the mutex object, which becomes signaled when it is unowned.
Semaphore – RtkCreateSemaphore or RtkOpenSemaphore returns the handle. A semaphore object maintains a count between zero and some maximum value. Its state is signaled when its count exceeds zero and non-signaled when its count is zero. If the current state is signaled, the wait function decreases the count by one.

Requirements

Minimum supported version	Header	Library	IRQL
wRTOS 1.0 SDK	RtkApi.h	RtkApi_W64.lib	PASSIVE_LEVEL