.. _events: Events ###### An :dfn:`event object` is a kernel object that implements traditional events. .. contents:: :local: :depth: 2 Concepts ******** Any number of event objects can be defined (limited only by available RAM). Each event object is referenced by its memory address. One or more threads may wait on an event object until the desired set of events has been delivered to the event object. When new events are delivered to the event object, all threads whose wait conditions have been satisfied become ready simultaneously. An event object has the following key properties: * A 32-bit value that tracks which events have been delivered to it. An event object must be initialized before it can be used. Events may be **delivered** by a thread or an ISR. When delivering events, the events may either overwrite the existing set of events or add to them in a bitwise fashion. When overwriting the existing set of events, this is referred to as setting. When adding to them in a bitwise fashion, this is referred to as posting. Both posting and setting events have the potential to fulfill match conditions of multiple threads waiting on the event object. All threads whose match conditions have been met are made active at the same time. Threads may wait on one or more events. They may either wait for all of the requested events, or for any of them. Furthermore, threads making a wait request have the option of resetting the current set of events tracked by the event object prior to waiting. Care must be taken with this option when multiple threads wait on the same event object. .. note:: The kernel does allow an ISR to query an event object, however the ISR must not attempt to wait for the events. Implementation ************** Defining an Event Object ======================== An event object is defined using a variable of type :c:struct:`k_event`. It must then be initialized by calling :c:func:`k_event_init`. The following code defines an event object. .. code-block:: c struct k_event my_event; k_event_init(&my_event); Alternatively, an event object can be defined and initialized at compile time by calling :c:macro:`K_EVENT_DEFINE`. The following code has the same effect as the code segment above. .. code-block:: c K_EVENT_DEFINE(my_event); Setting Events ============== Events in an event object are set by calling :c:func:`k_event_set`. The following code builds on the example above, and sets the events tracked by the event object to 0x001. .. code-block:: c void input_available_interrupt_handler(void *arg) { /* notify threads that data is available */ k_event_set(&my_event, 0x001); ... } Posting Events ============== Events are posted to an event object by calling :c:func:`k_event_post`. The following code builds on the example above, and posts a set of events to the event object. .. code-block:: c void input_available_interrupt_handler(void *arg) { ... /* notify threads that more data is available */ k_event_post(&my_event, 0x120); ... } Waiting for Events ================== Threads wait for events by calling :c:func:`k_event_wait`. The following code builds on the example above, and waits up to 50 milliseconds for any of the specified events to be posted. A warning is issued if none of the events are posted in time. .. code-block:: c void consumer_thread(void) { uint32_t events; events = k_event_wait(&my_event, 0xFFF, false, K_MSEC(50)); if (events == 0) { printk("No input devices are available!"); } else { /* Access the desired input device(s) */ ... } ... } Alternatively, the consumer thread may desire to wait for all the events before continuing. .. code-block:: c void consumer_thread(void) { uint32_t events; events = k_event_wait_all(&my_event, 0x121, false, K_MSEC(50)); if (events == 0) { printk("At least one input device is not available!"); } else { /* Access the desired input devices */ ... } ... } Suggested Uses ************** Use events to indicate that a set of conditions have occurred. Use events to pass small amounts of data to multiple threads at once. Configuration Options ********************* Related configuration options: * :kconfig:option:`CONFIG_EVENTS` API Reference ************** .. doxygengroup:: event_apis