Returns a valid handle to the created event object upon success, or NULL_HANDLE if the operation fails. To retrieve extended error information, call the osGetLastError function.

This function initializes and creates a new event object.

Events are synchronization primitives that exist in one of two states-signaled or non-signaled-and are used to notify tasks of specific system activities or conditions.

An optional name may be assigned during creation, allowing other tasks to obtain a handle to the event via the osOpenEvent function. When an event is no longer required, its handle should be released using osCloseHandle. The system destroys the event object only after all tasks have closed their respective handles. For further details, refer to the System Objects Management section.

To optimize memory usage, if the application does not utilize any osOpen* functions, the kernel ignores object names and excludes the name management code from the build. This optimization reduces the final footprint of the executable image. See the System Objects Management section for more information regarding object naming and opening conventions.

The state of an event can be transitioned at any time using the osSetEvent and osResetEvent functions. The initial state of the object is defined at the time of creation.

The behavior of the event-either manual-reset or auto-reset-is determined at creation. A manual-reset event remains in the signaled state until it is explicitly cleared via osResetEvent. Conversely, an auto-reset event automatically transitions to the non-signaled state as soon as a single waiting task successfully acquires the event and is resumed. Consequently, an auto-reset event can function effectively as a simple binary semaphore.

If multiple tasks are pending on a signaled event, the task with the highest priority is resumed first. If all waiting tasks have lower priority than the task currently setting the event state, they will be scheduled for execution when the processor becomes available. If a higher-priority task subsequently attempts to wait on a signaled event, it will preemptively acquire the event over lower-priority tasks already in the queue.

In the case of auto-reset events, if a task attempts to acquire a signaled event and its priority is equal to or lower than the priority of tasks already in the wait queue, that task is appended to the end of the pending queue. If no tasks are currently waiting, the task acquires the event immediately, and the event state is automatically reset to non-signaled.