INtime SDK Help
ntxWaitForRtSemaphore
INtime SDK v7.1 > About INtime > INtime Kernel > Semaphores > ntxWaitForRtSemaphore

Waits for and removes units from an RT semaphore. Execution continues when the units are available, or the thread has been waiting for the specified maximum amount of time.

WORD ntxWaitForRtSemaphore(
    NTXHANDLE hSemaphore,
    WORD wUnits,
    DWORD dwMilliseconds
);

Parameters

hSemaphore
Handle to the RT semaphore to receive units from.
wUnits
Number of units to receive.
dwMilliseconds
The number of milliseconds the calling thread waits:
NO_WAIT The thread does not wait.
INFINITE The thread waits for its request to be fully satisfied.
Any positive integer Calling thread goes to sleep for this many milliseconds, after which it awakes.
Note: The kernel converts milliseconds to high-level ticks.

Return Values

The number of units remaining in the semaphore after the call completes.
Success.
NTX_ERROR
Failure.

Status

E_OK 0x0000
No exceptional conditions occurred.
E_TIME 0x0001
The units do not appear within the specified time limit.

One of these is true:

  • The calling thread was not willing to wait and the requested units were not available.
  • dwMilliseconds expired while waiting in the thread queue before the requested units were available.
E_LIMIT 0x0004
wUnits is greater than the maximum number of units the semaphore can contain.
E_EXIST 0x0006
hSemaphore is not a handle for an existing object.
E_TYPE 0x8002
hSemaphore is not a handle for a semaphore.
E_NTX_INTERNAL_ERROR
The DLL could not contact the RT kernel to complete the request.

Requirements

Versions Defined in Include Link to
INtime 3.0 intime/nt/include/ntx.h ntx.h ntx.lib
INtime 4.01 (for 64-bit Windows) intime/nt/include/ntx.h ntx.h ntx64.lib

Warning: There is the possibility of confusion regarding the return value in the case where a semaphore:
a) has the maximum of 65535 units, and
b) ntxWaitForRtSemaphore is called with a request for zero units.

In this case the return value is 65535, which is also the value of the error value NTX_ERROR.

See Also

Semaphores