@samitouri / QOSamiQemu
Code Commits Issues Pulls Sessions CI/CD
master
master
h 321 lines 10.9 KB
Raw
1 /*
2 * QEMU coroutine implementation
3 *
4 * Copyright IBM, Corp. 2011
5 *
6 * Authors:
7 * Stefan Hajnoczi <stefanha@linux.vnet.ibm.com>
8 * Kevin Wolf <kwolf@redhat.com>
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 "qemu/coroutine-core.h"
19 #include "qemu/atomic.h"
20 #include "qemu/queue.h"
21 #include "qemu/timer.h"
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 BQL.
31 *
32 * Functions that execute in coroutine context cannot be called
33 * directly from normal functions. Use @coroutine_fn to mark such
34 * functions. For example:
35 *
36 * static void coroutine_fn foo(void) {
37 * ....
38 * }
39 *
40 * In the future it would be nice to have the compiler or a static
41 * checker catch misuse of such functions. This annotation might make
42 * it possible and in the meantime it serves as documentation.
43 */
44
45 /**
46 * Provides a mutex that can be used to synchronise coroutines
47 */
48 struct CoWaitRecord;
49 struct CoMutex {
50 /* Count of pending lockers; 0 for a free mutex, 1 for an
51 * uncontended mutex.
52 */
53 unsigned locked;
54
55 /* Context that is holding the lock. Useful to avoid spinning
56 * when two coroutines on the same AioContext try to get the lock. :)
57 */
58 AioContext *ctx;
59
60 /* A queue of waiters. Elements are added atomically in front of
61 * from_push. to_pop is only populated, and popped from, by whoever
62 * is in charge of the next wakeup. This can be an unlocker or,
63 * through the handoff protocol, a locker that is about to go to sleep.
64 */
65 QSLIST_HEAD(, CoWaitRecord) from_push, to_pop;
66
67 unsigned handoff, sequence;
68
69 Coroutine *holder;
70 };
71
72 /**
73 * Assert that the current coroutine holds @mutex.
74 */
75 static inline coroutine_fn void qemu_co_mutex_assert_locked(CoMutex *mutex)
76 {
77 /*
78 * mutex->holder doesn't need any synchronisation if the assertion holds
79 * true because the mutex protects it. If it doesn't hold true, we still
80 * don't mind if another thread takes or releases mutex behind our back,
81 * because the condition will be false no matter whether we read NULL or
82 * the pointer for any other coroutine.
83 */
84 assert(qatomic_read(&mutex->locked) &&
85 mutex->holder == qemu_coroutine_self());
86 }
87
88 #include "qemu/lockable.h"
89
90 /**
91 * CoQueues are a mechanism to queue coroutines in order to continue executing
92 * them later. They are similar to condition variables, but they need help
93 * from an external mutex in order to maintain thread-safety.
94 */
95 typedef struct CoQueue {
96 QSIMPLEQ_HEAD(, Coroutine) entries;
97 } CoQueue;
98
99 /**
100 * Initialise a CoQueue. This must be called before any other operation is used
101 * on the CoQueue.
102 */
103 void qemu_co_queue_init(CoQueue *queue);
104
105 typedef enum {
106 /*
107 * Enqueue at front instead of back. Use this to re-queue a request when
108 * its wait condition is not satisfied after being woken up.
109 */
110 CO_QUEUE_WAIT_FRONT = 0x1,
111 } CoQueueWaitFlags;
112
113 /**
114 * Adds the current coroutine to the CoQueue and transfers control to the
115 * caller of the coroutine. The mutex is unlocked during the wait and
116 * locked again afterwards.
117 */
118 #define qemu_co_queue_wait(queue, lock) \
119 qemu_co_queue_wait_impl(queue, QEMU_MAKE_LOCKABLE(lock), 0)
120 #define qemu_co_queue_wait_flags(queue, lock, flags) \
121 qemu_co_queue_wait_impl(queue, QEMU_MAKE_LOCKABLE(lock), (flags))
122 void coroutine_fn qemu_co_queue_wait_impl(CoQueue *queue, QemuLockable *lock,
123 CoQueueWaitFlags flags);
124
125 /**
126 * Removes the next coroutine from the CoQueue, and queue it to run after
127 * the currently-running coroutine yields.
128 * Returns true if a coroutine was removed, false if the queue is empty.
129 * Used from coroutine context, use qemu_co_enter_next outside.
130 */
131 bool coroutine_fn qemu_co_queue_next(CoQueue *queue);
132
133 /**
134 * Empties the CoQueue and queues the coroutine to run after
135 * the currently-running coroutine yields.
136 * Used from coroutine context, use qemu_co_enter_all outside.
137 */
138 void coroutine_fn qemu_co_queue_restart_all(CoQueue *queue);
139
140 /**
141 * Removes the next coroutine from the CoQueue, and wake it up. Unlike
142 * qemu_co_queue_next, this function releases the lock during aio_co_wake
143 * because it is meant to be used outside coroutine context; in that case, the
144 * coroutine is entered immediately, before qemu_co_enter_next returns.
145 *
146 * If used in coroutine context, qemu_co_enter_next is equivalent to
147 * qemu_co_queue_next.
148 */
149 #define qemu_co_enter_next(queue, lock) \
150 qemu_co_enter_next_impl(queue, QEMU_MAKE_LOCKABLE(lock))
151 bool qemu_co_enter_next_impl(CoQueue *queue, QemuLockable *lock);
152
153 /**
154 * Empties the CoQueue, waking the waiting coroutine one at a time. Unlike
155 * qemu_co_queue_all, this function releases the lock during aio_co_wake
156 * because it is meant to be used outside coroutine context; in that case, the
157 * coroutine is entered immediately, before qemu_co_enter_all returns.
158 *
159 * If used in coroutine context, qemu_co_enter_all is equivalent to
160 * qemu_co_queue_all.
161 */
162 #define qemu_co_enter_all(queue, lock) \
163 qemu_co_enter_all_impl(queue, QEMU_MAKE_LOCKABLE(lock))
164 void qemu_co_enter_all_impl(CoQueue *queue, QemuLockable *lock);
165
166 /**
167 * Checks if the CoQueue is empty.
168 */
169 bool qemu_co_queue_empty(CoQueue *queue);
170
171
172 typedef struct CoRwTicket CoRwTicket;
173 typedef struct CoRwlock {
174 CoMutex mutex;
175
176 /* Number of readers, or -1 if owned for writing. */
177 int owners;
178
179 /* Waiting coroutines. */
180 QSIMPLEQ_HEAD(, CoRwTicket) tickets;
181 } CoRwlock;
182
183 /**
184 * Initialises a CoRwlock. This must be called before any other operation
185 * is used on the CoRwlock
186 */
187 void qemu_co_rwlock_init(CoRwlock *lock);
188
189 /**
190 * Read locks the CoRwlock. If the lock cannot be taken immediately because
191 * of a parallel writer, control is transferred to the caller of the current
192 * coroutine.
193 */
194 void coroutine_fn qemu_co_rwlock_rdlock(CoRwlock *lock);
195
196 /**
197 * Write Locks the CoRwlock from a reader. This is a bit more efficient than
198 * @qemu_co_rwlock_unlock followed by a separate @qemu_co_rwlock_wrlock.
199 * Note that if the lock cannot be upgraded immediately, control is transferred
200 * to the caller of the current coroutine; another writer might run while
201 * @qemu_co_rwlock_upgrade blocks.
202 */
203 void coroutine_fn qemu_co_rwlock_upgrade(CoRwlock *lock);
204
205 /**
206 * Downgrades a write-side critical section to a reader. Downgrading with
207 * @qemu_co_rwlock_downgrade never blocks, unlike @qemu_co_rwlock_unlock
208 * followed by @qemu_co_rwlock_rdlock. This makes it more efficient, but
209 * may also sometimes be necessary for correctness.
210 */
211 void coroutine_fn qemu_co_rwlock_downgrade(CoRwlock *lock);
212
213 /**
214 * Write Locks the mutex. If the lock cannot be taken immediately because
215 * of a parallel reader, control is transferred to the caller of the current
216 * coroutine.
217 */
218 void coroutine_fn qemu_co_rwlock_wrlock(CoRwlock *lock);
219
220 /**
221 * Unlocks the read/write lock and schedules the next coroutine that was
222 * waiting for this lock to be run.
223 */
224 void coroutine_fn qemu_co_rwlock_unlock(CoRwlock *lock);
225
226 typedef struct QemuCoSleep {
227 Coroutine *to_wake;
228 } QemuCoSleep;
229
230 /**
231 * Yield the coroutine for a given duration. Initializes @w so that,
232 * during this yield, it can be passed to qemu_co_sleep_wake() to
233 * terminate the sleep.
234 */
235 void coroutine_fn qemu_co_sleep_ns_wakeable(QemuCoSleep *w,
236 QEMUClockType type, int64_t ns);
237
238 /**
239 * Yield the coroutine until the next call to qemu_co_sleep_wake.
240 */
241 void coroutine_fn qemu_co_sleep(QemuCoSleep *w);
242
243 static inline void coroutine_fn qemu_co_sleep_ns(QEMUClockType type, int64_t ns)
244 {
245 QemuCoSleep w = { 0 };
246 qemu_co_sleep_ns_wakeable(&w, type, ns);
247 }
248
249 typedef void CleanupFunc(void *opaque);
250 /**
251 * Run entry in a coroutine and start timer. Wait for entry to finish or for
252 * timer to elapse, what happen first. If entry finished, return 0, if timer
253 * elapsed earlier, return -ETIMEDOUT.
254 *
255 * Be careful, entry execution is not canceled, user should handle it somehow.
256 * If @clean is provided, it's called after coroutine finish if timeout
257 * happened.
258 */
259 int coroutine_fn qemu_co_timeout(CoroutineEntry *entry, void *opaque,
260 uint64_t timeout_ns, CleanupFunc clean);
261
262 /**
263 * Wake a coroutine sleeping in qemu_co_sleep() or qemu_co_sleep_ns_wakeable().
264 * The timer set up by the latter is deleted on wakeup.
265 *
266 * The wake is sticky: if no sleeper is parked on @w at the time of the call,
267 * the wake is recorded on @w and consumed by the next qemu_co_sleep() on the
268 * same @w, which then returns without yielding. This closes the lost-wakeup
269 * window between two sleeps and is the documented behavior callers should
270 * rely on -- e.g. a cancellation signal raised between iterations of a
271 * sleep/work loop will shorten the next sleep instead of being dropped.
272 *
273 * The state persists until consumed: if no further qemu_co_sleep() is ever
274 * called on @w, the pending wake is harmlessly discarded when @w goes away.
275 * Multiple wakes coalesce -- the next sleep consumes at most one.
276 */
277 void qemu_co_sleep_wake(QemuCoSleep *w);
278
279 /**
280 * Yield until a file descriptor becomes readable
281 *
282 * Note that this function clobbers the handlers for the file descriptor.
283 */
284 void coroutine_fn yield_until_fd_readable(int fd);
285
286 /**
287 * Increase coroutine pool size
288 */
289 void qemu_coroutine_inc_pool_size(unsigned int additional_pool_size);
290
291 /**
292 * Decrease coroutine pool size
293 */
294 void qemu_coroutine_dec_pool_size(unsigned int additional_pool_size);
295
296 /**
297 * Sends a (part of) iovec down a socket, yielding when the socket is full, or
298 * Receives data into a (part of) iovec from a socket,
299 * yielding when there is no data in the socket.
300 * The same interface as qemu_sendv_recvv(), with added yielding.
301 * XXX should mark these as coroutine_fn
302 */
303 ssize_t coroutine_fn qemu_co_sendv_recvv(int sockfd, struct iovec *iov,
304 unsigned iov_cnt, size_t offset,
305 size_t bytes, bool do_send);
306 #define qemu_co_recvv(sockfd, iov, iov_cnt, offset, bytes) \
307 qemu_co_sendv_recvv(sockfd, iov, iov_cnt, offset, bytes, false)
308 #define qemu_co_sendv(sockfd, iov, iov_cnt, offset, bytes) \
309 qemu_co_sendv_recvv(sockfd, iov, iov_cnt, offset, bytes, true)
310
311 /**
312 * The same as above, but with just a single buffer
313 */
314 ssize_t coroutine_fn qemu_co_send_recv(int sockfd, void *buf, size_t bytes,
315 bool do_send);
316 #define qemu_co_recv(sockfd, buf, bytes) \
317 qemu_co_send_recv(sockfd, buf, bytes, false)
318 #define qemu_co_send(sockfd, buf, bytes) \
319 qemu_co_send_recv(sockfd, buf, bytes, true)
320
321 #endif /* QEMU_COROUTINE_H */