Open topic with navigation

RtkWaitForSingleObject

RtkWaitForSingleObject returns when one of the following occurs:

• The specified object is in the signaled state.
• The time-out interval elapses.

Syntax

ULONG RtkWaitForSingleObject(
    RTSSINST RtssInst,
    PULONG pErrorCode,
    HANDLE hHandle,
    DWORD Milliseconds
);

Parameters

RtssInst

An RTSSINST value returned from a call to RtkRtssAttach.

pErrorCode

A pointer to a location where additional error information may be returned. This location need not be defined; the user may pass a NULL value. If defined, this location is set to NULL if no error occurred.

hHandle

The object identifier. See the list of the object types whose handles can be specified in the Comments section.

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 Values

The event that caused the function to return if the function succeeds, WAIT_FAILED if the function fails

The return value on success is one of the following values:

• 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.
• WAIT_OBJECT_0 — The state of the specified object is signaled.
• WAIT_TIMEOUT — The time-out interval elapsed, and the object's state is non-signaled.

Remarks

RtkWaitForSingleObject checks the current state of the specified object. 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 or objects 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:

• 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 is greater than zero and non-signaled when its count is zero. If the current state is signaled, the wait function decreases the count by one.
• Mutex
  RtkCreateMutex and RtkOpenMutex return handles to the mutex object which becomes signaled when the mutex is unowned.
• Event
  The RtkCreateEvent or RtkOpenEvent function returns the handle. An event object's state is set explicitly to signaled by the RtkSetEvent or RtkPulseEvent function. A manual-reset event object's state must be reset explicitly to nonsignaled by the RtkResetEvent function. For an auto-reset event object, the wait function resets the object's state to nonsignaled before returning.

See Also:

RtkCreateMutex

RtkCreateSemaphore

RtkOpenMutex

RtkOpenSemaphore

IntervalZero.com | Support | Give Feedback