ntxWaitForRtSemaphore(INtimeDotNet)

Requests a specified number of units to be received from the RTsemaphore.

Use ntxWaitForRtSemaphore to find out how many units are available by specifying 0 (zero) in the units parameter.

You can specify the amount of time a thread that uses ntxWaitForRtSemaphore waits for a semaphore unit. Two factors determine whether the thread receives the units and how soon.

How many units the thread asks for.
Where the thread is in the queue.

If the number of units requested is within the specified maximum for that semaphore, the request is valid.

If the thread is at the front of the queue and the number is less than the current number, the request is granted immediately and the thread stays running.

If a request is valid but cannot be granted immediately, it can either wait or not.

If the thread specifies that it can wait, the thread goes into the thread queue and goes to sleep by waiting for a pre-set length of time. If the time elapses before the thread gets the units it asked for, the thread awakens and receives an E_TIME condition code.

If the thread specifies that it cannot wait, the thread receives an E_TIME condition code.

If the thread asks for more units than the maximum number allowed for a particular semaphore, the request is invalid and the semaphore returns an E_LIMIT condition code.

Visual Basic:

Function ntxWaitForRtSemaphore(
  ByVal hSemaphore As Integer,
  ByVal wUnits As Short,
  ByVal dwMilliseconds As Integer)
As Short

Visual C#:

Int16 ntxWaitForRtSemaphore (
  Int32 hSemaphore,
  Int16 wUnits,
  Int32 dwMilliseconds );

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. This will cause the assembly to throw an exception.

Parameters

hSemaphore

The handle to the RT semaphore.

wUnits

The number of units to send.

dwMilliseconds

The number of milliseconds the calling thread waits:

`NTX_NO_WAIT`	The thread does not wait.
`NTX_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.

Status

E_TIME

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

The semaphore's maximum unit count would have been exceeded. A semaphore's maximum unit count is determined when it is created.

E_EXIST

hSemaphore is not a handle for an existing object.

E_TYPE

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	Reference
INtime 3.0	INtimeDotNet