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