Requests a unit from the specified low-level semaphore.

BOOLEAN knWaitForRtSemaphore(
    KNHANDLE hSemaphore,    // handle for low-level semaphore
    DWORD dwKernelTicks     // the number of kernel clock intervals to wait
);

Parameters

hSemaphore

Handle for a low-level semaphore object.

dwKernelTicks

Maximum number of system timer ticks which the calling thread is willing to wait for a unit. The length of this interval is configurable and its value may obtained from the SYSINFO structure which is read using CopyRtSystemInfo. The US_TO_KTICKS macro may be used to convert a value in microseconds to a system timer tick count using the information supplied in this structure.

Literal	Meaning
KN_DONT_WAIT	The thread does not wait at all.
KN_WAIT_FOREVER	The thread waits indefinitely.
UINT_32 value	The thread waits for the specified number of clock ticks.

Remarks

If the semaphore currently contains units, the number of units is reduced by 1 and the thread proceeds. If the semaphore has no units and the thread is willing to wait, the thread is put to sleep and placed into the semaphore's thread queue. The thread will be awakened by one of these events:

• The thread is at the head of the semaphore queue and another thread invokes knReleaseRtSemaphore on this semaphore.
• The number of clock ticks specified by the thread expires.
• The semaphore is deleted.

Note:   This is a blocking call; do not use it in an interrupt handler.

Return Values

TRUE

Success.

FALSE

Failure. To determine the status, call GetLastRtError.

Status

E_OK

The thread received the requested unit.

E_KN_TIME_OUT

The time limit expired.

E_KN_NONEXIST

The semaphore was deleted while the thread was waiting.

Note:   Delete semaphores only after a thread begins waiting. This call cannot return control to the calling thread if its corresponding semaphore is already deleted.

Requirements

See Also

Semaphore system calls, CopyRtSystemInfo, knReleaseRtSemaphore