Event objects

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

Event creation and deletion

The function osCreateEvent creates a event object. The event can be created before system start, from an interrupt handler or by a task. During event creation, an optional event name may be specified. It makes tasks able to open it by osOpenEvent function. During event creation and opening, its handle is returned. The handle is assigned by the system and it is used to discern the system objects. All operations performed on the event except to specify its handle. The non-used event should be closed with the osCloseHandle. Event will be deleted when it will be closed by all tasks that opened it. More information you can find in the system objects management section.

When events are not used, the OS_USE_EVENT constant may be set to 0, to reduce the output code.

Using an event object

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.

SpaceShadow documentation