2 * QEMU aio implementation
4 * Copyright IBM, Corp. 2008
7 * Anthony Liguori <aliguori@us.ibm.com>
9 * This work is licensed under the terms of the GNU GPL, version 2. See
10 * the COPYING file in the top-level directory.
17 #include "qemu/typedefs.h"
18 #include "qemu-common.h"
19 #include "qemu/queue.h"
20 #include "qemu/event_notifier.h"
21 #include "qemu/thread.h"
22 #include "qemu/rfifolock.h"
23 #include "qemu/timer.h"
25 typedef struct BlockAIOCB BlockAIOCB
;
26 typedef void BlockCompletionFunc(void *opaque
, int ret
);
28 typedef struct AIOCBInfo
{
29 void (*cancel_async
)(BlockAIOCB
*acb
);
30 AioContext
*(*get_aio_context
)(BlockAIOCB
*acb
);
35 const AIOCBInfo
*aiocb_info
;
37 BlockCompletionFunc
*cb
;
42 void *qemu_aio_get(const AIOCBInfo
*aiocb_info
, BlockDriverState
*bs
,
43 BlockCompletionFunc
*cb
, void *opaque
);
44 void qemu_aio_unref(void *p
);
45 void qemu_aio_ref(void *p
);
47 typedef struct AioHandler AioHandler
;
48 typedef void QEMUBHFunc(void *opaque
);
49 typedef void IOHandler(void *opaque
);
54 /* Protects all fields from multi-threaded access */
57 /* The list of registered AIO handlers */
58 QLIST_HEAD(, AioHandler
) aio_handlers
;
60 /* This is a simple lock used to protect the aio_handlers list.
61 * Specifically, it's used to ensure that no callbacks are removed while
62 * we're walking and dispatching callbacks.
66 /* Used to avoid unnecessary event_notifier_set calls in aio_notify;
67 * accessed with atomic primitives. If this field is 0, everything
68 * (file descriptors, bottom halves, timers) will be re-evaluated
69 * before the next blocking poll(), thus the event_notifier_set call
70 * can be skipped. If it is non-zero, you may need to wake up a
71 * concurrent aio_poll or the glib main event loop, making
72 * event_notifier_set necessary.
74 * Bit 0 is reserved for GSource usage of the AioContext, and is 1
75 * between a call to aio_ctx_check and the next call to aio_ctx_dispatch.
76 * Bits 1-31 simply count the number of active calls to aio_poll
77 * that are in the prepare or poll phase.
79 * The GSource and aio_poll must use a different mechanism because
80 * there is no certainty that a call to GSource's prepare callback
81 * (via g_main_context_prepare) is indeed followed by check and
82 * dispatch. It's not clear whether this would be a bug, but let's
83 * play safe and allow it---it will just cause extra calls to
84 * event_notifier_set until the next call to dispatch.
86 * Instead, the aio_poll calls include both the prepare and the
87 * dispatch phase, hence a simple counter is enough for them.
91 /* lock to protect between bh's adders and deleter */
94 /* Anchor of the list of Bottom Halves belonging to the context */
95 struct QEMUBH
*first_bh
;
97 /* A simple lock used to protect the first_bh list, and ensure that
98 * no callbacks are removed while we're walking and dispatching callbacks.
102 /* Used for aio_notify. */
103 EventNotifier notifier
;
105 /* Thread pool for performing work and receiving completion callbacks */
106 struct ThreadPool
*thread_pool
;
108 /* TimerLists for calling timers - one per clock type */
109 QEMUTimerListGroup tlg
;
113 * aio_context_new: Allocate a new AioContext.
115 * AioContext provide a mini event-loop that can be waited on synchronously.
116 * They also provide bottom halves, a service to execute a piece of code
117 * as soon as possible.
119 AioContext
*aio_context_new(Error
**errp
);
123 * @ctx: The AioContext to operate on.
125 * Add a reference to an AioContext.
127 void aio_context_ref(AioContext
*ctx
);
131 * @ctx: The AioContext to operate on.
133 * Drop a reference to an AioContext.
135 void aio_context_unref(AioContext
*ctx
);
137 /* Take ownership of the AioContext. If the AioContext will be shared between
138 * threads, and a thread does not want to be interrupted, it will have to
139 * take ownership around calls to aio_poll(). Otherwise, aio_poll()
140 * automatically takes care of calling aio_context_acquire and
141 * aio_context_release.
143 * Access to timers and BHs from a thread that has not acquired AioContext
144 * is possible. Access to callbacks for now must be done while the AioContext
145 * is owned by the thread (FIXME).
147 void aio_context_acquire(AioContext
*ctx
);
149 /* Relinquish ownership of the AioContext. */
150 void aio_context_release(AioContext
*ctx
);
153 * aio_bh_new: Allocate a new bottom half structure.
155 * Bottom halves are lightweight callbacks whose invocation is guaranteed
156 * to be wait-free, thread-safe and signal-safe. The #QEMUBH structure
157 * is opaque and must be allocated prior to its use.
159 QEMUBH
*aio_bh_new(AioContext
*ctx
, QEMUBHFunc
*cb
, void *opaque
);
162 * aio_notify: Force processing of pending events.
164 * Similar to signaling a condition variable, aio_notify forces
165 * aio_wait to exit, so that the next call will re-examine pending events.
166 * The caller of aio_notify will usually call aio_wait again very soon,
167 * or go through another iteration of the GLib main loop. Hence, aio_notify
168 * also has the side effect of recalculating the sets of file descriptors
169 * that the main loop waits for.
171 * Calling aio_notify is rarely necessary, because for example scheduling
172 * a bottom half calls it already.
174 void aio_notify(AioContext
*ctx
);
177 * aio_bh_poll: Poll bottom halves for an AioContext.
179 * These are internal functions used by the QEMU main loop.
180 * And notice that multiple occurrences of aio_bh_poll cannot
181 * be called concurrently
183 int aio_bh_poll(AioContext
*ctx
);
186 * qemu_bh_schedule: Schedule a bottom half.
188 * Scheduling a bottom half interrupts the main loop and causes the
189 * execution of the callback that was passed to qemu_bh_new.
191 * Bottom halves that are scheduled from a bottom half handler are instantly
192 * invoked. This can create an infinite loop if a bottom half handler
195 * @bh: The bottom half to be scheduled.
197 void qemu_bh_schedule(QEMUBH
*bh
);
200 * qemu_bh_cancel: Cancel execution of a bottom half.
202 * Canceling execution of a bottom half undoes the effect of calls to
203 * qemu_bh_schedule without freeing its resources yet. While cancellation
204 * itself is also wait-free and thread-safe, it can of course race with the
205 * loop that executes bottom halves unless you are holding the iothread
206 * mutex. This makes it mostly useless if you are not holding the mutex.
208 * @bh: The bottom half to be canceled.
210 void qemu_bh_cancel(QEMUBH
*bh
);
213 *qemu_bh_delete: Cancel execution of a bottom half and free its resources.
215 * Deleting a bottom half frees the memory that was allocated for it by
216 * qemu_bh_new. It also implies canceling the bottom half if it was
218 * This func is async. The bottom half will do the delete action at the finial
221 * @bh: The bottom half to be deleted.
223 void qemu_bh_delete(QEMUBH
*bh
);
225 /* Return whether there are any pending callbacks from the GSource
226 * attached to the AioContext, before g_poll is invoked.
228 * This is used internally in the implementation of the GSource.
230 bool aio_prepare(AioContext
*ctx
);
232 /* Return whether there are any pending callbacks from the GSource
233 * attached to the AioContext, after g_poll is invoked.
235 * This is used internally in the implementation of the GSource.
237 bool aio_pending(AioContext
*ctx
);
239 /* Dispatch any pending callbacks from the GSource attached to the AioContext.
241 * This is used internally in the implementation of the GSource.
243 bool aio_dispatch(AioContext
*ctx
);
245 /* Progress in completing AIO work to occur. This can issue new pending
246 * aio as a result of executing I/O completion or bh callbacks.
248 * Return whether any progress was made by executing AIO or bottom half
249 * handlers. If @blocking == true, this should always be true except
250 * if someone called aio_notify.
252 * If there are no pending bottom halves, but there are pending AIO
253 * operations, it may not be possible to make any progress without
254 * blocking. If @blocking is true, this function will wait until one
255 * or more AIO events have completed, to ensure something has moved
258 bool aio_poll(AioContext
*ctx
, bool blocking
);
260 /* Register a file descriptor and associated callbacks. Behaves very similarly
261 * to qemu_set_fd_handler. Unlike qemu_set_fd_handler, these callbacks will
262 * be invoked when using aio_poll().
264 * Code that invokes AIO completion functions should rely on this function
265 * instead of qemu_set_fd_handler[2].
267 void aio_set_fd_handler(AioContext
*ctx
,
273 /* Register an event notifier and associated callbacks. Behaves very similarly
274 * to event_notifier_set_handler. Unlike event_notifier_set_handler, these callbacks
275 * will be invoked when using aio_poll().
277 * Code that invokes AIO completion functions should rely on this function
278 * instead of event_notifier_set_handler.
280 void aio_set_event_notifier(AioContext
*ctx
,
281 EventNotifier
*notifier
,
282 EventNotifierHandler
*io_read
);
284 /* Return a GSource that lets the main loop poll the file descriptors attached
285 * to this AioContext.
287 GSource
*aio_get_g_source(AioContext
*ctx
);
289 /* Return the ThreadPool bound to this AioContext */
290 struct ThreadPool
*aio_get_thread_pool(AioContext
*ctx
);
294 * @ctx: the aio context
295 * @type: the clock type
297 * @cb: the callback to call on timer expiry
298 * @opaque: the opaque pointer to pass to the callback
300 * Allocate a new timer attached to the context @ctx.
301 * The function is responsible for memory allocation.
303 * The preferred interface is aio_timer_init. Use that
304 * unless you really need dynamic memory allocation.
306 * Returns: a pointer to the new timer
308 static inline QEMUTimer
*aio_timer_new(AioContext
*ctx
, QEMUClockType type
,
310 QEMUTimerCB
*cb
, void *opaque
)
312 return timer_new_tl(ctx
->tlg
.tl
[type
], scale
, cb
, opaque
);
317 * @ctx: the aio context
319 * @type: the clock type
321 * @cb: the callback to call on timer expiry
322 * @opaque: the opaque pointer to pass to the callback
324 * Initialise a new timer attached to the context @ctx.
325 * The caller is responsible for memory allocation.
327 static inline void aio_timer_init(AioContext
*ctx
,
328 QEMUTimer
*ts
, QEMUClockType type
,
330 QEMUTimerCB
*cb
, void *opaque
)
332 timer_init_tl(ts
, ctx
->tlg
.tl
[type
], scale
, cb
, opaque
);
336 * aio_compute_timeout:
337 * @ctx: the aio context
339 * Compute the timeout that a blocking aio_poll should use.
341 int64_t aio_compute_timeout(AioContext
*ctx
);