osWaitForObject function
Declaration:
BOOL osWaitForObject(
  HANDLE Handle,
  TIME Timeout
);
Parameters:
Handle

An object handle.

Timeout

A wait operation timeout.

Return value:

TRUE on success or FALSE on failure. Use osGetLastError function to obtain extended error information.

Description:

Function suspends task execution until specified object is in the signaled state, or the timeout interval elapses.

A system object can be in one of two states: signaled or non-signaled. Each task could be waiting for one or more objects, to check its state. When the task calls one of the system wait functions on a non-signaled object, its execution will be suspended until the object will not change its state to the signaled. When a task waits for many objects, it will be released if at least one of the objects will be in signaled state. When multiple tasks are waiting for the same object, they are queued in order to their priority. If the task performs wait operation on already signaled object, it will continue its execution, and the wait function will return with success immediately.

A task can be released only when both terms are fulfilled: the object is signaled and the task could be running (currently, in the system, tasks with higher priority are not being processed). If the task with the higher priority is executed in the system, and the object changes its state for signaled, waiting task will be started only when all tasks with the higher priority became blocked (see scheduling). If the object will change its state for a non-signaled state, before the task can be started, the wait function will not return until both conditions will not be fulfilled.

To wait for one object, an osWaitForObject function should be performed. To wait for more objects use an osWaitForObjects function. It is only available when the maximal number of the objects (that task could be waiting is greater than one. Use OS_MAX_WAIT_FOR_OBJECTS constant to define the maximal number of the objects that task can be waiting.

The wait functions allow passing a timeout parameter. It defines how long a task should wait for an object. When it is 0 (or OS_IGNORE), task will only check the object state and then will return immediately. When the object is signaled, it will return with success, otherwise will fail and set the last error code to ERR_WAIT_TIMEOUT. Specifying an OS_INFINITE as a timeout will cause that the task waits until the object will change its state into signaled, a timeout is ignored. All other value passed to wait function is a timeout specified in a time units. Values other than 0, OS_IGNORE and OS_INFINITE may be specified only, when the OS_USE_WAITING_WITH_TIME_OUT is set to 1. The task will wait until object state is changed to signaled or specified timeout elapses. For more information on time units, look into following time and timeouts of the synchronization section.

For more information please refer to synchronization section.

SpaceShadow documentation