osCreateEvent function
Declaration:
HANDLE osCreateEvent(
  SYSNAME Name,
  BOOL InitialState,
  BOOL ManualReset
);
Parameters:
Name

Name of the object (may be NULL).

InitialState

The initial event state. When it is the TRUE, event object will be signaled, otherwise non-signaled.

ManualReset

When it is set to TRUE, created is a manual-reset event, otherwise an auto-reset event (see below to the description section).

Return value:

The return value is a handle to the created event object when success or NULL_HANDLE on failure. Use osGetLastError function to obtain extended error information.

Description:

Function creates an event object.

Events are two-state objects that may be used to signal any kind of activity.

During event creation, an optional event name may be specified. It makes tasks able to open it by osOpenEvent function. The non-used event should be closed with the osCloseHandle. Event will be deleted when it is closed by all tasks that opened it. More information you can find in the system objects managementsection.

If all of the osOpen* functions are not used, the system ignores an object name and the code used to name management will be removed. It will reduce final size of the output code. For more information about the names and object opening see the system objects managementsection.

Events are objects that state can be modified in any time by osSetEvent and osResetEvent functions that set event states for signaled and non-signaled. During event creation the beginning state is specified.

Whether the event is manual-reset or auto-reset, it is determined during event creation. In case of manual-reset event, object state can be changed with osSetEvent and osResetEvent only, while in case of auto-reset event, the state is changed for a non-signaled also when a task completes waiting for an event. This case only one of the waiting tasks is started. The auto-reset event can be used as a simple binary semaphore.

When many tasks are waiting for event that has just been signaled signaled, as first a task with the highest priority is resumed. If all waiting tasks have the lower priority, than the task that has just changed event state, they will be let in, when they are ready to run. If the other task with the higher priority starts waiting for it, it will acquire the event immediately, as it has the highest priority than the waiting tasks.

Additionally, for an auto-reset event, when the task that try to acquire signaled event have the same or the lower priority comparing with the priority of waiting task, the task will be added at the end of the pending tasks queue. If there are no waiting tasks, it completes the wait function immediately with success and resets event state to non-signaled.

Version:1.0
Header file:OS_Event.h (include OS_API.h)
See also: BOOL, events, FALSE, HANDLE, NULL, NULL_HANDLE, OS_OPEN_EVENT_FUNC, osCloseHandle, osGetLastError, osOpenEvent, SYSNAME, system objects management, TRUE
SpaceShadow documentation