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 */ 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 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