| 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_CORE_H |
| 16 | #define QEMU_COROUTINE_CORE_H |
| 17 | |
| 18 | /** |
| 19 | * Coroutines are a mechanism for stack switching and can be used for |
| 20 | * cooperative userspace threading. These functions provide a simple but |
| 21 | * useful flavor of coroutines that is suitable for writing sequential code, |
| 22 | * rather than callbacks, for operations that need to give up control while |
| 23 | * waiting for events to complete. |
| 24 | * |
| 25 | * These functions are re-entrant and may be used outside the BQL. |
| 26 | * |
| 27 | * Functions that execute in coroutine context cannot be called |
| 28 | * directly from normal functions. Use @coroutine_fn to mark such |
| 29 | * functions. For example: |
| 30 | * |
| 31 | * static void coroutine_fn foo(void) { |
| 32 | * .... |
| 33 | * } |
| 34 | * |
| 35 | * In the future it would be nice to have the compiler or a static |
| 36 | * checker catch misuse of such functions. This annotation might make |
| 37 | * it possible and in the meantime it serves as documentation. |
| 38 | */ |
| 39 | |
| 40 | /** |
| 41 | * Mark a function that executes in coroutine context |
| 42 | * |
| 43 | * |
| 44 | * Functions that execute in coroutine context cannot be called |
| 45 | * directly from normal functions. Use @coroutine_fn to mark such |
| 46 | * functions. For example: |
| 47 | * |
| 48 | * static void coroutine_fn foo(void) { |
| 49 | * .... |
| 50 | * } |
| 51 | * |
| 52 | * In the future it would be nice to have the compiler or a static |
| 53 | * checker catch misuse of such functions. This annotation might make |
| 54 | * it possible and in the meantime it serves as documentation. |
| 55 | */ |
| 56 | |
| 57 | typedef struct Coroutine Coroutine; |
| 58 | typedef struct CoMutex CoMutex; |
| 59 | |
| 60 | /** |
| 61 | * Coroutine entry point |
| 62 | * |
| 63 | * When the coroutine is entered for the first time, opaque is passed in as an |
| 64 | * argument. |
| 65 | * |
| 66 | * When this function returns, the coroutine is destroyed automatically and |
| 67 | * execution continues in the caller who last entered the coroutine. |
| 68 | */ |
| 69 | typedef void coroutine_fn CoroutineEntry(void *opaque); |
| 70 | |
| 71 | /** |
| 72 | * Create a new coroutine |
| 73 | * |
| 74 | * Use qemu_coroutine_enter() to actually transfer control to the coroutine. |
| 75 | * The opaque argument is passed as the argument to the entry point. |
| 76 | */ |
| 77 | Coroutine *qemu_coroutine_create(CoroutineEntry *entry, void *opaque); |
| 78 | |
| 79 | /** |
| 80 | * Transfer control to a coroutine |
| 81 | */ |
| 82 | void qemu_coroutine_enter(Coroutine *coroutine); |
| 83 | |
| 84 | /** |
| 85 | * Transfer control to a coroutine if it's not active (i.e. part of the call |
| 86 | * stack of the running coroutine). Otherwise, do nothing. |
| 87 | */ |
| 88 | void qemu_coroutine_enter_if_inactive(Coroutine *co); |
| 89 | |
| 90 | /** |
| 91 | * Transfer control to a coroutine and associate it with ctx |
| 92 | */ |
| 93 | void qemu_aio_coroutine_enter(AioContext *ctx, Coroutine *co); |
| 94 | |
| 95 | /** |
| 96 | * Transfer control back to a coroutine's caller |
| 97 | * |
| 98 | * This function does not return until the coroutine is re-entered using |
| 99 | * qemu_coroutine_enter(). |
| 100 | */ |
| 101 | void coroutine_fn qemu_coroutine_yield(void); |
| 102 | |
| 103 | /** |
| 104 | * Get the AioContext of the given coroutine |
| 105 | */ |
| 106 | AioContext *qemu_coroutine_get_aio_context(Coroutine *co); |
| 107 | |
| 108 | /** |
| 109 | * Get the currently executing coroutine |
| 110 | */ |
| 111 | Coroutine *qemu_coroutine_self(void); |
| 112 | |
| 113 | /** |
| 114 | * Return whether or not currently inside a coroutine |
| 115 | * |
| 116 | * This can be used to write functions that work both when in coroutine context |
| 117 | * and when not in coroutine context. Note that such functions cannot use the |
| 118 | * coroutine_fn annotation since they work outside coroutine context. |
| 119 | */ |
| 120 | bool qemu_in_coroutine(void); |
| 121 | |
| 122 | /** |
| 123 | * Return true if the coroutine is currently entered |
| 124 | * |
| 125 | * A coroutine is "entered" if it has not yielded from the current |
| 126 | * qemu_coroutine_enter() call used to run it. This does not mean that the |
| 127 | * coroutine is currently executing code since it may have transferred control |
| 128 | * to another coroutine using qemu_coroutine_enter(). |
| 129 | * |
| 130 | * When several coroutines enter each other there may be no way to know which |
| 131 | * ones have already been entered. In such situations this function can be |
| 132 | * used to avoid recursively entering coroutines. |
| 133 | */ |
| 134 | bool qemu_coroutine_entered(Coroutine *co); |
| 135 | |
| 136 | /** |
| 137 | * Initialises a CoMutex. This must be called before any other operation is used |
| 138 | * on the CoMutex. |
| 139 | */ |
| 140 | void qemu_co_mutex_init(CoMutex *mutex); |
| 141 | |
| 142 | /** |
| 143 | * Locks the mutex. If the lock cannot be taken immediately, control is |
| 144 | * transferred to the caller of the current coroutine. |
| 145 | */ |
| 146 | void coroutine_fn qemu_co_mutex_lock(CoMutex *mutex); |
| 147 | |
| 148 | /** |
| 149 | * Unlocks the mutex and schedules the next coroutine that was waiting for this |
| 150 | * lock to be run. |
| 151 | */ |
| 152 | void coroutine_fn qemu_co_mutex_unlock(CoMutex *mutex); |
| 153 | |
| 154 | #endif |