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 BlockDriverAIOCB BlockDriverAIOCB
;
26 typedef void BlockDriverCompletionFunc(void *opaque
, int ret
);
28 typedef struct AIOCBInfo
{
29 void (*cancel
)(BlockDriverAIOCB
*acb
);
33 struct BlockDriverAIOCB
{
34 const AIOCBInfo
*aiocb_info
;
36 BlockDriverCompletionFunc
*cb
;
40 void *qemu_aio_get(const AIOCBInfo
*aiocb_info
, BlockDriverState
*bs
,
41 BlockDriverCompletionFunc
*cb
, void *opaque
);
42 void qemu_aio_release(void *p
);
44 typedef struct AioHandler AioHandler
;
45 typedef void QEMUBHFunc(void *opaque
);
46 typedef void IOHandler(void *opaque
);
51 /* Protects all fields from multi-threaded access */
54 /* The list of registered AIO handlers */
55 QLIST_HEAD(, AioHandler
) aio_handlers
;
57 /* This is a simple lock used to protect the aio_handlers list.
58 * Specifically, it's used to ensure that no callbacks are removed while
59 * we're walking and dispatching callbacks.
63 /* Used to avoid unnecessary event_notifier_set calls in aio_notify.
64 * Writes protected by lock or BQL, reads are lockless.
68 /* lock to protect between bh's adders and deleter */
71 /* Anchor of the list of Bottom Halves belonging to the context */
72 struct QEMUBH
*first_bh
;
74 /* A simple lock used to protect the first_bh list, and ensure that
75 * no callbacks are removed while we're walking and dispatching callbacks.
79 /* Used for aio_notify. */
80 EventNotifier notifier
;
82 /* GPollFDs for aio_poll() */
85 /* Thread pool for performing work and receiving completion callbacks */
86 struct ThreadPool
*thread_pool
;
88 /* TimerLists for calling timers - one per clock type */
89 QEMUTimerListGroup tlg
;
92 /* Used internally to synchronize aio_poll against qemu_bh_schedule. */
93 void aio_set_dispatching(AioContext
*ctx
, bool dispatching
);
96 * aio_context_new: Allocate a new AioContext.
98 * AioContext provide a mini event-loop that can be waited on synchronously.
99 * They also provide bottom halves, a service to execute a piece of code
100 * as soon as possible.
102 AioContext
*aio_context_new(void);
106 * @ctx: The AioContext to operate on.
108 * Add a reference to an AioContext.
110 void aio_context_ref(AioContext
*ctx
);
114 * @ctx: The AioContext to operate on.
116 * Drop a reference to an AioContext.
118 void aio_context_unref(AioContext
*ctx
);
120 /* Take ownership of the AioContext. If the AioContext will be shared between
121 * threads, a thread must have ownership when calling aio_poll().
123 * Note that multiple threads calling aio_poll() means timers, BHs, and
124 * callbacks may be invoked from a different thread than they were registered
125 * from. Therefore, code must use AioContext acquire/release or use
126 * fine-grained synchronization to protect shared state if other threads will
127 * be accessing it simultaneously.
129 void aio_context_acquire(AioContext
*ctx
);
131 /* Relinquish ownership of the AioContext. */
132 void aio_context_release(AioContext
*ctx
);
135 * aio_bh_new: Allocate a new bottom half structure.
137 * Bottom halves are lightweight callbacks whose invocation is guaranteed
138 * to be wait-free, thread-safe and signal-safe. The #QEMUBH structure
139 * is opaque and must be allocated prior to its use.
141 QEMUBH
*aio_bh_new(AioContext
*ctx
, QEMUBHFunc
*cb
, void *opaque
);
144 * aio_notify: Force processing of pending events.
146 * Similar to signaling a condition variable, aio_notify forces
147 * aio_wait to exit, so that the next call will re-examine pending events.
148 * The caller of aio_notify will usually call aio_wait again very soon,
149 * or go through another iteration of the GLib main loop. Hence, aio_notify
150 * also has the side effect of recalculating the sets of file descriptors
151 * that the main loop waits for.
153 * Calling aio_notify is rarely necessary, because for example scheduling
154 * a bottom half calls it already.
156 void aio_notify(AioContext
*ctx
);
159 * aio_bh_poll: Poll bottom halves for an AioContext.
161 * These are internal functions used by the QEMU main loop.
162 * And notice that multiple occurrences of aio_bh_poll cannot
163 * be called concurrently
165 int aio_bh_poll(AioContext
*ctx
);
168 * qemu_bh_schedule: Schedule a bottom half.
170 * Scheduling a bottom half interrupts the main loop and causes the
171 * execution of the callback that was passed to qemu_bh_new.
173 * Bottom halves that are scheduled from a bottom half handler are instantly
174 * invoked. This can create an infinite loop if a bottom half handler
177 * @bh: The bottom half to be scheduled.
179 void qemu_bh_schedule(QEMUBH
*bh
);
182 * qemu_bh_cancel: Cancel execution of a bottom half.
184 * Canceling execution of a bottom half undoes the effect of calls to
185 * qemu_bh_schedule without freeing its resources yet. While cancellation
186 * itself is also wait-free and thread-safe, it can of course race with the
187 * loop that executes bottom halves unless you are holding the iothread
188 * mutex. This makes it mostly useless if you are not holding the mutex.
190 * @bh: The bottom half to be canceled.
192 void qemu_bh_cancel(QEMUBH
*bh
);
195 *qemu_bh_delete: Cancel execution of a bottom half and free its resources.
197 * Deleting a bottom half frees the memory that was allocated for it by
198 * qemu_bh_new. It also implies canceling the bottom half if it was
200 * This func is async. The bottom half will do the delete action at the finial
203 * @bh: The bottom half to be deleted.
205 void qemu_bh_delete(QEMUBH
*bh
);
207 /* Return whether there are any pending callbacks from the GSource
208 * attached to the AioContext.
210 * This is used internally in the implementation of the GSource.
212 bool aio_pending(AioContext
*ctx
);
214 /* Progress in completing AIO work to occur. This can issue new pending
215 * aio as a result of executing I/O completion or bh callbacks.
217 * Return whether any progress was made by executing AIO or bottom half
218 * handlers. If @blocking == true, this should always be true except
219 * if someone called aio_notify.
221 * If there are no pending bottom halves, but there are pending AIO
222 * operations, it may not be possible to make any progress without
223 * blocking. If @blocking is true, this function will wait until one
224 * or more AIO events have completed, to ensure something has moved
227 bool aio_poll(AioContext
*ctx
, bool blocking
);
230 /* Register a file descriptor and associated callbacks. Behaves very similarly
231 * to qemu_set_fd_handler2. Unlike qemu_set_fd_handler2, these callbacks will
232 * be invoked when using aio_poll().
234 * Code that invokes AIO completion functions should rely on this function
235 * instead of qemu_set_fd_handler[2].
237 void aio_set_fd_handler(AioContext
*ctx
,
244 /* Register an event notifier and associated callbacks. Behaves very similarly
245 * to event_notifier_set_handler. Unlike event_notifier_set_handler, these callbacks
246 * will be invoked when using aio_poll().
248 * Code that invokes AIO completion functions should rely on this function
249 * instead of event_notifier_set_handler.
251 void aio_set_event_notifier(AioContext
*ctx
,
252 EventNotifier
*notifier
,
253 EventNotifierHandler
*io_read
);
255 /* Return a GSource that lets the main loop poll the file descriptors attached
256 * to this AioContext.
258 GSource
*aio_get_g_source(AioContext
*ctx
);
260 /* Return the ThreadPool bound to this AioContext */
261 struct ThreadPool
*aio_get_thread_pool(AioContext
*ctx
);
265 * @ctx: the aio context
266 * @type: the clock type
268 * @cb: the callback to call on timer expiry
269 * @opaque: the opaque pointer to pass to the callback
271 * Allocate a new timer attached to the context @ctx.
272 * The function is responsible for memory allocation.
274 * The preferred interface is aio_timer_init. Use that
275 * unless you really need dynamic memory allocation.
277 * Returns: a pointer to the new timer
279 static inline QEMUTimer
*aio_timer_new(AioContext
*ctx
, QEMUClockType type
,
281 QEMUTimerCB
*cb
, void *opaque
)
283 return timer_new_tl(ctx
->tlg
.tl
[type
], scale
, cb
, opaque
);
288 * @ctx: the aio context
290 * @type: the clock type
292 * @cb: the callback to call on timer expiry
293 * @opaque: the opaque pointer to pass to the callback
295 * Initialise a new timer attached to the context @ctx.
296 * The caller is responsible for memory allocation.
298 static inline void aio_timer_init(AioContext
*ctx
,
299 QEMUTimer
*ts
, QEMUClockType type
,
301 QEMUTimerCB
*cb
, void *opaque
)
303 timer_init(ts
, ctx
->tlg
.tl
[type
], scale
, cb
, opaque
);