]>
git.proxmox.com Git - mirror_qemu.git/blob - include/qemu/coroutine-core.h
2 * QEMU coroutine implementation
4 * Copyright IBM, Corp. 2011
7 * Stefan Hajnoczi <stefanha@linux.vnet.ibm.com>
8 * Kevin Wolf <kwolf@redhat.com>
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.
15 #ifndef QEMU_COROUTINE_CORE_H
16 #define QEMU_COROUTINE_CORE_H
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.
25 * These functions are re-entrant and may be used outside the global mutex.
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:
31 * static void coroutine_fn foo(void) {
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.
41 * Mark a function that executes in coroutine context
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:
48 * static void coroutine_fn foo(void) {
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.
57 typedef struct Coroutine Coroutine
;
58 typedef struct CoMutex CoMutex
;
61 * Coroutine entry point
63 * When the coroutine is entered for the first time, opaque is passed in as an
66 * When this function returns, the coroutine is destroyed automatically and
67 * execution continues in the caller who last entered the coroutine.
69 typedef void coroutine_fn
CoroutineEntry(void *opaque
);
72 * Create a new coroutine
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.
77 Coroutine
*qemu_coroutine_create(CoroutineEntry
*entry
, void *opaque
);
80 * Transfer control to a coroutine
82 void qemu_coroutine_enter(Coroutine
*coroutine
);
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.
88 void qemu_coroutine_enter_if_inactive(Coroutine
*co
);
91 * Transfer control to a coroutine and associate it with ctx
93 void qemu_aio_coroutine_enter(AioContext
*ctx
, Coroutine
*co
);
96 * Transfer control back to a coroutine's caller
98 * This function does not return until the coroutine is re-entered using
99 * qemu_coroutine_enter().
101 void coroutine_fn
qemu_coroutine_yield(void);
104 * Get the AioContext of the given coroutine
106 AioContext
*qemu_coroutine_get_aio_context(Coroutine
*co
);
109 * Get the currently executing coroutine
111 Coroutine
*qemu_coroutine_self(void);
114 * Return whether or not currently inside a coroutine
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.
120 bool qemu_in_coroutine(void);
123 * Return true if the coroutine is currently entered
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().
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.
134 bool qemu_coroutine_entered(Coroutine
*co
);
137 * Initialises a CoMutex. This must be called before any other operation is used
140 void qemu_co_mutex_init(CoMutex
*mutex
);
143 * Locks the mutex. If the lock cannot be taken immediately, control is
144 * transferred to the caller of the current coroutine.
146 void coroutine_fn
qemu_co_mutex_lock(CoMutex
*mutex
);
149 * Unlocks the mutex and schedules the next coroutine that was waiting for this
152 void coroutine_fn
qemu_co_mutex_unlock(CoMutex
*mutex
);