1.. _events:
2
3Events
4######
5
6An :dfn:`event object` is a kernel object that implements traditional events.
7
8.. contents::
9    :local:
10    :depth: 2
11
12Concepts
13********
14
15Any number of event objects can be defined (limited only by available RAM). Each
16event object is referenced by its memory address. One or more threads may wait
17on an event object until the desired set of events has been delivered to the
18event object. When new events are delivered to the event object, all threads
19whose wait conditions have been satisfied become ready simultaneously.
20
21An event object has the following key properties:
22
23* A 32-bit value that tracks which events have been delivered to it.
24
25An event object must be initialized before it can be used.
26
27Events may be **delivered** by a thread or an ISR. When delivering events, the
28events may either overwrite the existing set of events or add to them in
29a bitwise fashion. When overwriting the existing set of events, this is referred
30to as setting. When adding to them in a bitwise fashion, this is referred to as
31posting. Both posting and setting events have the potential to fulfill match
32conditions of multiple threads waiting on the event object. All threads whose
33match conditions have been met are made active at the same time.
34
35Threads may wait on one or more events. They may either wait for all of the
36requested events, or for any of them. Furthermore, threads making a wait request
37have the option of resetting the current set of events tracked by the event
38object prior to waiting. Care must be taken with this option when multiple
39threads wait on the same event object.
40
41.. note::
42    The kernel does allow an ISR to query an event object, however the ISR must
43    not attempt to wait for the events.
44
45Implementation
46**************
47
48Defining an Event Object
49========================
50
51An event object is defined using a variable of type :c:struct:`k_event`.
52It must then be initialized by calling :c:func:`k_event_init`.
53
54The following code defines an event object.
55
56.. code-block:: c
57
58    struct k_event my_event;
59
60    k_event_init(&my_event);
61
62Alternatively, an event object can be defined and initialized at compile time
63by calling :c:macro:`K_EVENT_DEFINE`.
64
65The following code has the same effect as the code segment above.
66
67.. code-block:: c
68
69    K_EVENT_DEFINE(my_event);
70
71Setting Events
72==============
73
74Events in an event object are set by calling :c:func:`k_event_set`.
75
76The following code builds on the example above, and sets the events tracked by
77the event object to 0x001.
78
79.. code-block:: c
80
81    void input_available_interrupt_handler(void *arg)
82    {
83        /* notify threads that data is available */
84
85        k_event_set(&my_event, 0x001);
86
87        ...
88    }
89
90Posting Events
91==============
92
93Events are posted to an event object by calling :c:func:`k_event_post`.
94
95The following code builds on the example above, and posts a set of events to
96the event object.
97
98.. code-block:: c
99
100    void input_available_interrupt_handler(void *arg)
101    {
102        ...
103
104        /* notify threads that more data is available */
105
106        k_event_post(&my_event, 0x120);
107
108        ...
109    }
110
111Waiting for Events
112==================
113
114Threads wait for events by calling :c:func:`k_event_wait`.
115
116The following code builds on the example above, and waits up to 50 milliseconds
117for any of the specified events to be posted.  A warning is issued if none
118of the events are posted in time.
119
120.. code-block:: c
121
122    void consumer_thread(void)
123    {
124        uint32_t  events;
125
126        events = k_event_wait(&my_event, 0xFFF, false, K_MSEC(50));
127        if (events == 0) {
128            printk("No input devices are available!");
129        } else {
130            /* Access the desired input device(s) */
131            ...
132        }
133        ...
134    }
135
136Alternatively, the consumer thread may desire to wait for all the events
137before continuing.
138
139.. code-block:: c
140
141    void consumer_thread(void)
142    {
143        uint32_t  events;
144
145        events = k_event_wait_all(&my_event, 0x121, false, K_MSEC(50));
146        if (events == 0) {
147            printk("At least one input device is not available!");
148        } else {
149            /* Access the desired input devices */
150            ...
151        }
152        ...
153    }
154
155Suggested Uses
156**************
157
158Use events to indicate that a set of conditions have occurred.
159
160Use events to pass small amounts of data to multiple threads at once.
161
162Configuration Options
163*********************
164
165Related configuration options:
166
167* :kconfig:option:`CONFIG_EVENTS`
168
169API Reference
170**************
171
172.. doxygengroup:: event_apis
173