]>
Commit | Line | Data |
---|---|---|
00dccaf1 KW |
1 | /* |
2 | * QEMU coroutine implementation | |
3 | * | |
4 | * Copyright IBM, Corp. 2011 | |
5 | * | |
6 | * Authors: | |
7 | * Stefan Hajnoczi <stefanha@linux.vnet.ibm.com> | |
b96e9247 | 8 | * Kevin Wolf <kwolf@redhat.com> |
00dccaf1 KW |
9 | * |
10 | * This work is licensed under the terms of the GNU LGPL, version 2 or later. | |
11 | * See the COPYING.LIB file in the top-level directory. | |
12 | * | |
13 | */ | |
14 | ||
15 | #ifndef QEMU_COROUTINE_H | |
16 | #define QEMU_COROUTINE_H | |
17 | ||
18 | #include <stdbool.h> | |
6a1751b7 | 19 | #include "qemu/typedefs.h" |
1de7afc9 PB |
20 | #include "qemu/queue.h" |
21 | #include "qemu/timer.h" | |
00dccaf1 KW |
22 | |
23 | /** | |
24 | * Coroutines are a mechanism for stack switching and can be used for | |
25 | * cooperative userspace threading. These functions provide a simple but | |
26 | * useful flavor of coroutines that is suitable for writing sequential code, | |
27 | * rather than callbacks, for operations that need to give up control while | |
28 | * waiting for events to complete. | |
29 | * | |
30 | * These functions are re-entrant and may be used outside the global mutex. | |
31 | */ | |
32 | ||
33 | /** | |
34 | * Mark a function that executes in coroutine context | |
35 | * | |
36 | * Functions that execute in coroutine context cannot be called directly from | |
37 | * normal functions. In the future it would be nice to enable compiler or | |
38 | * static checker support for catching such errors. This annotation might make | |
39 | * it possible and in the meantime it serves as documentation. | |
40 | * | |
41 | * For example: | |
42 | * | |
43 | * static void coroutine_fn foo(void) { | |
44 | * .... | |
45 | * } | |
46 | */ | |
47 | #define coroutine_fn | |
48 | ||
49 | typedef struct Coroutine Coroutine; | |
50 | ||
51 | /** | |
52 | * Coroutine entry point | |
53 | * | |
54 | * When the coroutine is entered for the first time, opaque is passed in as an | |
55 | * argument. | |
56 | * | |
57 | * When this function returns, the coroutine is destroyed automatically and | |
58 | * execution continues in the caller who last entered the coroutine. | |
59 | */ | |
60 | typedef void coroutine_fn CoroutineEntry(void *opaque); | |
61 | ||
62 | /** | |
63 | * Create a new coroutine | |
64 | * | |
65 | * Use qemu_coroutine_enter() to actually transfer control to the coroutine. | |
66 | */ | |
67 | Coroutine *qemu_coroutine_create(CoroutineEntry *entry); | |
68 | ||
69 | /** | |
70 | * Transfer control to a coroutine | |
71 | * | |
72 | * The opaque argument is passed as the argument to the entry point when | |
73 | * entering the coroutine for the first time. It is subsequently ignored. | |
74 | */ | |
75 | void qemu_coroutine_enter(Coroutine *coroutine, void *opaque); | |
76 | ||
77 | /** | |
78 | * Transfer control back to a coroutine's caller | |
79 | * | |
80 | * This function does not return until the coroutine is re-entered using | |
81 | * qemu_coroutine_enter(). | |
82 | */ | |
83 | void coroutine_fn qemu_coroutine_yield(void); | |
84 | ||
85 | /** | |
86 | * Get the currently executing coroutine | |
87 | */ | |
88 | Coroutine *coroutine_fn qemu_coroutine_self(void); | |
89 | ||
90 | /** | |
91 | * Return whether or not currently inside a coroutine | |
92 | * | |
93 | * This can be used to write functions that work both when in coroutine context | |
94 | * and when not in coroutine context. Note that such functions cannot use the | |
95 | * coroutine_fn annotation since they work outside coroutine context. | |
96 | */ | |
97 | bool qemu_in_coroutine(void); | |
98 | ||
b96e9247 KW |
99 | |
100 | ||
101 | /** | |
102 | * CoQueues are a mechanism to queue coroutines in order to continue executing | |
103 | * them later. They provide the fundamental primitives on which coroutine locks | |
104 | * are built. | |
105 | */ | |
106 | typedef struct CoQueue { | |
107 | QTAILQ_HEAD(, Coroutine) entries; | |
28f08246 | 108 | AioContext *ctx; |
b96e9247 KW |
109 | } CoQueue; |
110 | ||
111 | /** | |
112 | * Initialise a CoQueue. This must be called before any other operation is used | |
113 | * on the CoQueue. | |
114 | */ | |
115 | void qemu_co_queue_init(CoQueue *queue); | |
116 | ||
117 | /** | |
118 | * Adds the current coroutine to the CoQueue and transfers control to the | |
119 | * caller of the coroutine. | |
120 | */ | |
121 | void coroutine_fn qemu_co_queue_wait(CoQueue *queue); | |
122 | ||
e9e6295b ZYW |
123 | /** |
124 | * Adds the current coroutine to the head of the CoQueue and transfers control to the | |
125 | * caller of the coroutine. | |
126 | */ | |
127 | void coroutine_fn qemu_co_queue_wait_insert_head(CoQueue *queue); | |
128 | ||
b96e9247 KW |
129 | /** |
130 | * Restarts the next coroutine in the CoQueue and removes it from the queue. | |
131 | * | |
132 | * Returns true if a coroutine was restarted, false if the queue is empty. | |
133 | */ | |
b681a1c7 | 134 | bool coroutine_fn qemu_co_queue_next(CoQueue *queue); |
b96e9247 | 135 | |
e8ee5e4c SH |
136 | /** |
137 | * Restarts all coroutines in the CoQueue and leaves the queue empty. | |
138 | */ | |
b681a1c7 BC |
139 | void coroutine_fn qemu_co_queue_restart_all(CoQueue *queue); |
140 | ||
141 | /** | |
142 | * Enter the next coroutine in the queue | |
143 | */ | |
144 | bool qemu_co_enter_next(CoQueue *queue); | |
e8ee5e4c | 145 | |
b96e9247 KW |
146 | /** |
147 | * Checks if the CoQueue is empty. | |
148 | */ | |
149 | bool qemu_co_queue_empty(CoQueue *queue); | |
150 | ||
151 | ||
152 | /** | |
153 | * Provides a mutex that can be used to synchronise coroutines | |
154 | */ | |
155 | typedef struct CoMutex { | |
156 | bool locked; | |
157 | CoQueue queue; | |
158 | } CoMutex; | |
159 | ||
160 | /** | |
161 | * Initialises a CoMutex. This must be called before any other operation is used | |
162 | * on the CoMutex. | |
163 | */ | |
164 | void qemu_co_mutex_init(CoMutex *mutex); | |
165 | ||
166 | /** | |
167 | * Locks the mutex. If the lock cannot be taken immediately, control is | |
168 | * transferred to the caller of the current coroutine. | |
169 | */ | |
170 | void coroutine_fn qemu_co_mutex_lock(CoMutex *mutex); | |
171 | ||
172 | /** | |
173 | * Unlocks the mutex and schedules the next coroutine that was waiting for this | |
174 | * lock to be run. | |
175 | */ | |
176 | void coroutine_fn qemu_co_mutex_unlock(CoMutex *mutex); | |
177 | ||
12888904 AK |
178 | typedef struct CoRwlock { |
179 | bool writer; | |
180 | int reader; | |
181 | CoQueue queue; | |
182 | } CoRwlock; | |
183 | ||
184 | /** | |
185 | * Initialises a CoRwlock. This must be called before any other operation | |
186 | * is used on the CoRwlock | |
187 | */ | |
188 | void qemu_co_rwlock_init(CoRwlock *lock); | |
189 | ||
190 | /** | |
191 | * Read locks the CoRwlock. If the lock cannot be taken immediately because | |
192 | * of a parallel writer, control is transferred to the caller of the current | |
193 | * coroutine. | |
194 | */ | |
195 | void qemu_co_rwlock_rdlock(CoRwlock *lock); | |
196 | ||
197 | /** | |
198 | * Write Locks the mutex. If the lock cannot be taken immediately because | |
199 | * of a parallel reader, control is transferred to the caller of the current | |
200 | * coroutine. | |
201 | */ | |
202 | void qemu_co_rwlock_wrlock(CoRwlock *lock); | |
203 | ||
204 | /** | |
205 | * Unlocks the read/write lock and schedules the next coroutine that was | |
206 | * waiting for this lock to be run. | |
207 | */ | |
208 | void qemu_co_rwlock_unlock(CoRwlock *lock); | |
209 | ||
7e624667 SH |
210 | /** |
211 | * Yield the coroutine for a given duration | |
212 | * | |
213 | * Note this function uses timers and hence only works when a main loop is in | |
214 | * use. See main-loop.h and do not use from qemu-tool programs. | |
215 | */ | |
216 | void coroutine_fn co_sleep_ns(QEMUClock *clock, int64_t ns); | |
217 | ||
9f05d0c3 MH |
218 | /** |
219 | * Yield until a file descriptor becomes readable | |
220 | * | |
221 | * Note that this function clobbers the handlers for the file descriptor. | |
222 | */ | |
223 | void coroutine_fn yield_until_fd_readable(int fd); | |
00dccaf1 | 224 | #endif /* QEMU_COROUTINE_H */ |