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 #ifndef __KERNEL_WAIT_H
24 #define __KERNEL_WAIT_H
25 
26 #include <sys/types.h>
27 #include <list.h>
28 #include <compiler.h>
29 #include <arch/defines.h>
30 #include <arch/ops.h>
31 #include <arch/thread.h>
32 
33 __BEGIN_CDECLS;
34 
35 /* wait queue stuff */
36 #define WAIT_QUEUE_MAGIC (0x77616974) // 'wait'
37 
38 typedef struct wait_queue {
39     int magic;
40     struct list_node list;
41     int count;
42 } wait_queue_t;
43 
44 #define WAIT_QUEUE_INITIAL_VALUE(q) \
45 { \
46     .magic = WAIT_QUEUE_MAGIC, \
47     .list = LIST_INITIAL_VALUE((q).list), \
48     .count = 0 \
49 }
50 
51 /* wait queue primitive */
52 /* NOTE: must be inside critical section when using these */
53 void wait_queue_init(wait_queue_t *wait);
54 
55 /*
56  * release all the threads on this wait queue with a return code of ERR_OBJECT_DESTROYED.
57  * the caller must assure that no other threads are operating on the wait queue during or
58  * after the call.
59  */
60 void wait_queue_destroy(wait_queue_t *, bool reschedule);
61 
62 /*
63  * block on a wait queue.
64  * return status is whatever the caller of wait_queue_wake_*() specifies.
65  * a timeout other than INFINITE_TIME will set abort after the specified time
66  * and return ERR_TIMED_OUT. a timeout of 0 will immediately return.
67  */
68 status_t wait_queue_block(wait_queue_t *, lk_time_t timeout);
69 
70 /*
71  * release one or more threads from the wait queue.
72  * reschedule = should the system reschedule if any is released.
73  * wait_queue_error = what wait_queue_block() should return for the blocking thread.
74  */
75 int wait_queue_wake_one(wait_queue_t *, bool reschedule, status_t wait_queue_error);
76 int wait_queue_wake_all(wait_queue_t *, bool reschedule, status_t wait_queue_error);
77 
78 /*
79  * remove the thread from whatever wait queue it's in.
80  * return an error if the thread is not currently blocked (or is the current thread)
81  */
82 status_t thread_unblock_from_wait_queue(struct thread *t, status_t wait_queue_error);
83 
84 __END_CDECLS;
85 
86 #endif
87 
88