1 /*
2 * Copyright (c) 2008-2014 Travis Geiselbrecht
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining
5 * a copy of this software and associated documentation files
6 * (the "Software"), to deal in the Software without restriction,
7 * including without limitation the rights to use, copy, modify, merge,
8 * publish, distribute, sublicense, and/or sell copies of the Software,
9 * and to permit persons to whom the Software is furnished to do so,
10 * subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
18 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
19 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
20 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
21 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22 */
23
24 /**
25 * @file
26 * @brief Event wait and signal functions for threads.
27 * @defgroup event Events
28 *
29 * An event is a subclass of a wait queue.
30 *
31 * Threads wait for events, with optional timeouts.
32 *
33 * Events are "signaled", releasing waiting threads to continue.
34 * Signals may be one-shot signals (EVENT_FLAG_AUTOUNSIGNAL), in which
35 * case one signal releases only one thread, at which point it is
36 * automatically cleared. Otherwise, signals release all waiting threads
37 * to continue immediately until the signal is manually cleared with
38 * event_unsignal().
39 *
40 * @{
41 */
42
43 #include <kernel/event.h>
44 #include <debug.h>
45 #include <assert.h>
46 #include <err.h>
47 #include <kernel/thread.h>
48
49 /**
50 * @brief Initialize an event object
51 *
52 * @param e Event object to initialize
53 * @param initial Initial value for "signaled" state
54 * @param flags 0 or EVENT_FLAG_AUTOUNSIGNAL
55 */
event_init(event_t * e,bool initial,uint flags)56 void event_init(event_t *e, bool initial, uint flags)
57 {
58 *e = (event_t)EVENT_INITIAL_VALUE(*e, initial, flags);
59 }
60
61 /**
62 * @brief Destroy an event object.
63 *
64 * Event's resources are freed and it may no longer be
65 * used until event_init() is called again. Any threads
66 * still waiting on the event will be resumed.
67 *
68 * @param e Event object to initialize
69 */
event_destroy(event_t * e)70 void event_destroy(event_t *e)
71 {
72 DEBUG_ASSERT(e->magic == EVENT_MAGIC);
73
74 THREAD_LOCK(state);
75
76 e->magic = 0;
77 e->signaled = false;
78 e->flags = 0;
79 wait_queue_destroy(&e->wait, true);
80
81 THREAD_UNLOCK(state);
82 }
83
84 /**
85 * @brief Wait for event to be signaled
86 *
87 * If the event has already been signaled, this function
88 * returns immediately. Otherwise, the current thread
89 * goes to sleep until the event object is signaled,
90 * the timeout is reached, or the event object is destroyed
91 * by another thread.
92 *
93 * @param e Event object
94 * @param timeout Timeout value, in ms
95 *
96 * @return 0 on success, ERR_TIMED_OUT on timeout,
97 * other values on other errors.
98 */
event_wait_timeout(event_t * e,lk_time_t timeout)99 status_t event_wait_timeout(event_t *e, lk_time_t timeout)
100 {
101 status_t ret = NO_ERROR;
102
103 DEBUG_ASSERT(e->magic == EVENT_MAGIC);
104
105 THREAD_LOCK(state);
106
107 if (e->signaled) {
108 /* signaled, we're going to fall through */
109 if (e->flags & EVENT_FLAG_AUTOUNSIGNAL) {
110 /* autounsignal flag lets one thread fall through before unsignaling */
111 e->signaled = false;
112 }
113 } else {
114 /* unsignaled, block here */
115 ret = wait_queue_block(&e->wait, timeout);
116 }
117
118 THREAD_UNLOCK(state);
119
120 return ret;
121 }
122
123 /**
124 * @brief Signal an event
125 *
126 * Signals an event. If EVENT_FLAG_AUTOUNSIGNAL is set in the event
127 * object's flags, only one waiting thread is allowed to proceed. Otherwise,
128 * all waiting threads are allowed to proceed until such time as
129 * event_unsignal() is called.
130 *
131 * @param e Event object
132 * @param reschedule If true, waiting thread(s) are executed immediately,
133 * and the current thread resumes only after the
134 * waiting threads have been satisfied. If false,
135 * waiting threads are placed at the end of the run
136 * queue.
137 *
138 * @return Returns NO_ERROR on success.
139 */
event_signal(event_t * e,bool reschedule)140 status_t event_signal(event_t *e, bool reschedule)
141 {
142 DEBUG_ASSERT(e->magic == EVENT_MAGIC);
143
144 THREAD_LOCK(state);
145
146 if (!e->signaled) {
147 if (e->flags & EVENT_FLAG_AUTOUNSIGNAL) {
148 /* try to release one thread and leave unsignaled if successful */
149 if (wait_queue_wake_one(&e->wait, reschedule, NO_ERROR) <= 0) {
150 /*
151 * if we didn't actually find a thread to wake up, go to
152 * signaled state and let the next call to event_wait
153 * unsignal the event.
154 */
155 e->signaled = true;
156 }
157 } else {
158 /* release all threads and remain signaled */
159 e->signaled = true;
160 wait_queue_wake_all(&e->wait, reschedule, NO_ERROR);
161 }
162 }
163
164 THREAD_UNLOCK(state);
165
166 return NO_ERROR;
167 }
168
169 /**
170 * @brief Clear the "signaled" property of an event
171 *
172 * Used mainly for event objects without the EVENT_FLAG_AUTOUNSIGNAL
173 * flag. Once this function is called, threads that call event_wait()
174 * functions will once again need to wait until the event object
175 * is signaled.
176 *
177 * @param e Event object
178 *
179 * @return Returns NO_ERROR on success.
180 */
event_unsignal(event_t * e)181 status_t event_unsignal(event_t *e)
182 {
183 DEBUG_ASSERT(e->magic == EVENT_MAGIC);
184
185 e->signaled = false;
186
187 return NO_ERROR;
188 }
189
190