xref: /qemu/include/block/aio.h (revision 9b34277d23a6fb15eb9513006c96d8026beeea1f)
1a76bab49Saliguori /*
2a76bab49Saliguori  * QEMU aio implementation
3a76bab49Saliguori  *
4a76bab49Saliguori  * Copyright IBM, Corp. 2008
5a76bab49Saliguori  *
6a76bab49Saliguori  * Authors:
7a76bab49Saliguori  *  Anthony Liguori   <aliguori@us.ibm.com>
8a76bab49Saliguori  *
9a76bab49Saliguori  * This work is licensed under the terms of the GNU GPL, version 2.  See
10a76bab49Saliguori  * the COPYING file in the top-level directory.
11a76bab49Saliguori  *
12a76bab49Saliguori  */
13a76bab49Saliguori 
14a76bab49Saliguori #ifndef QEMU_AIO_H
15a76bab49Saliguori #define QEMU_AIO_H
16a76bab49Saliguori 
17a76bab49Saliguori #include "qemu-common.h"
181de7afc9SPaolo Bonzini #include "qemu/queue.h"
191de7afc9SPaolo Bonzini #include "qemu/event_notifier.h"
20a76bab49Saliguori 
2185e8dab1SPaolo Bonzini typedef struct BlockDriverAIOCB BlockDriverAIOCB;
2285e8dab1SPaolo Bonzini typedef void BlockDriverCompletionFunc(void *opaque, int ret);
2385e8dab1SPaolo Bonzini 
24d7331bedSStefan Hajnoczi typedef struct AIOCBInfo {
2585e8dab1SPaolo Bonzini     void (*cancel)(BlockDriverAIOCB *acb);
268c82e9a4SStefan Hajnoczi     size_t aiocb_size;
27d7331bedSStefan Hajnoczi } AIOCBInfo;
2885e8dab1SPaolo Bonzini 
2985e8dab1SPaolo Bonzini struct BlockDriverAIOCB {
30d7331bedSStefan Hajnoczi     const AIOCBInfo *aiocb_info;
3185e8dab1SPaolo Bonzini     BlockDriverState *bs;
3285e8dab1SPaolo Bonzini     BlockDriverCompletionFunc *cb;
3385e8dab1SPaolo Bonzini     void *opaque;
3485e8dab1SPaolo Bonzini };
3585e8dab1SPaolo Bonzini 
36d7331bedSStefan Hajnoczi void *qemu_aio_get(const AIOCBInfo *aiocb_info, BlockDriverState *bs,
3785e8dab1SPaolo Bonzini                    BlockDriverCompletionFunc *cb, void *opaque);
3885e8dab1SPaolo Bonzini void qemu_aio_release(void *p);
3985e8dab1SPaolo Bonzini 
40f627aab1SPaolo Bonzini typedef struct AioHandler AioHandler;
41f627aab1SPaolo Bonzini typedef void QEMUBHFunc(void *opaque);
42f627aab1SPaolo Bonzini typedef void IOHandler(void *opaque);
43f627aab1SPaolo Bonzini 
44f627aab1SPaolo Bonzini typedef struct AioContext {
45e3713e00SPaolo Bonzini     GSource source;
46e3713e00SPaolo Bonzini 
47a915f4bcSPaolo Bonzini     /* The list of registered AIO handlers */
48a915f4bcSPaolo Bonzini     QLIST_HEAD(, AioHandler) aio_handlers;
49a915f4bcSPaolo Bonzini 
50a915f4bcSPaolo Bonzini     /* This is a simple lock used to protect the aio_handlers list.
51a915f4bcSPaolo Bonzini      * Specifically, it's used to ensure that no callbacks are removed while
52a915f4bcSPaolo Bonzini      * we're walking and dispatching callbacks.
53a915f4bcSPaolo Bonzini      */
54a915f4bcSPaolo Bonzini     int walking_handlers;
55a915f4bcSPaolo Bonzini 
56f627aab1SPaolo Bonzini     /* Anchor of the list of Bottom Halves belonging to the context */
57f627aab1SPaolo Bonzini     struct QEMUBH *first_bh;
58f627aab1SPaolo Bonzini 
59f627aab1SPaolo Bonzini     /* A simple lock used to protect the first_bh list, and ensure that
60f627aab1SPaolo Bonzini      * no callbacks are removed while we're walking and dispatching callbacks.
61f627aab1SPaolo Bonzini      */
62f627aab1SPaolo Bonzini     int walking_bh;
632f4dc3c1SPaolo Bonzini 
642f4dc3c1SPaolo Bonzini     /* Used for aio_notify.  */
652f4dc3c1SPaolo Bonzini     EventNotifier notifier;
666b5f8762SStefan Hajnoczi 
676b5f8762SStefan Hajnoczi     /* GPollFDs for aio_poll() */
686b5f8762SStefan Hajnoczi     GArray *pollfds;
69*9b34277dSStefan Hajnoczi 
70*9b34277dSStefan Hajnoczi     /* Thread pool for performing work and receiving completion callbacks */
71*9b34277dSStefan Hajnoczi     struct ThreadPool *thread_pool;
72f627aab1SPaolo Bonzini } AioContext;
73f627aab1SPaolo Bonzini 
74a76bab49Saliguori /* Returns 1 if there are still outstanding AIO requests; 0 otherwise */
759958c351SPaolo Bonzini typedef int (AioFlushEventNotifierHandler)(EventNotifier *e);
76a76bab49Saliguori 
77f627aab1SPaolo Bonzini /**
78f627aab1SPaolo Bonzini  * aio_context_new: Allocate a new AioContext.
79f627aab1SPaolo Bonzini  *
80f627aab1SPaolo Bonzini  * AioContext provide a mini event-loop that can be waited on synchronously.
81f627aab1SPaolo Bonzini  * They also provide bottom halves, a service to execute a piece of code
82f627aab1SPaolo Bonzini  * as soon as possible.
83f627aab1SPaolo Bonzini  */
84f627aab1SPaolo Bonzini AioContext *aio_context_new(void);
85f627aab1SPaolo Bonzini 
86f627aab1SPaolo Bonzini /**
87e3713e00SPaolo Bonzini  * aio_context_ref:
88e3713e00SPaolo Bonzini  * @ctx: The AioContext to operate on.
89e3713e00SPaolo Bonzini  *
90e3713e00SPaolo Bonzini  * Add a reference to an AioContext.
91e3713e00SPaolo Bonzini  */
92e3713e00SPaolo Bonzini void aio_context_ref(AioContext *ctx);
93e3713e00SPaolo Bonzini 
94e3713e00SPaolo Bonzini /**
95e3713e00SPaolo Bonzini  * aio_context_unref:
96e3713e00SPaolo Bonzini  * @ctx: The AioContext to operate on.
97e3713e00SPaolo Bonzini  *
98e3713e00SPaolo Bonzini  * Drop a reference to an AioContext.
99e3713e00SPaolo Bonzini  */
100e3713e00SPaolo Bonzini void aio_context_unref(AioContext *ctx);
101e3713e00SPaolo Bonzini 
102e3713e00SPaolo Bonzini /**
103f627aab1SPaolo Bonzini  * aio_bh_new: Allocate a new bottom half structure.
104f627aab1SPaolo Bonzini  *
105f627aab1SPaolo Bonzini  * Bottom halves are lightweight callbacks whose invocation is guaranteed
106f627aab1SPaolo Bonzini  * to be wait-free, thread-safe and signal-safe.  The #QEMUBH structure
107f627aab1SPaolo Bonzini  * is opaque and must be allocated prior to its use.
108f627aab1SPaolo Bonzini  */
109f627aab1SPaolo Bonzini QEMUBH *aio_bh_new(AioContext *ctx, QEMUBHFunc *cb, void *opaque);
110f627aab1SPaolo Bonzini 
111f627aab1SPaolo Bonzini /**
1122f4dc3c1SPaolo Bonzini  * aio_notify: Force processing of pending events.
1132f4dc3c1SPaolo Bonzini  *
1142f4dc3c1SPaolo Bonzini  * Similar to signaling a condition variable, aio_notify forces
1152f4dc3c1SPaolo Bonzini  * aio_wait to exit, so that the next call will re-examine pending events.
1162f4dc3c1SPaolo Bonzini  * The caller of aio_notify will usually call aio_wait again very soon,
1172f4dc3c1SPaolo Bonzini  * or go through another iteration of the GLib main loop.  Hence, aio_notify
1182f4dc3c1SPaolo Bonzini  * also has the side effect of recalculating the sets of file descriptors
1192f4dc3c1SPaolo Bonzini  * that the main loop waits for.
1202f4dc3c1SPaolo Bonzini  *
1212f4dc3c1SPaolo Bonzini  * Calling aio_notify is rarely necessary, because for example scheduling
1222f4dc3c1SPaolo Bonzini  * a bottom half calls it already.
1232f4dc3c1SPaolo Bonzini  */
1242f4dc3c1SPaolo Bonzini void aio_notify(AioContext *ctx);
1252f4dc3c1SPaolo Bonzini 
1262f4dc3c1SPaolo Bonzini /**
127f627aab1SPaolo Bonzini  * aio_bh_poll: Poll bottom halves for an AioContext.
128f627aab1SPaolo Bonzini  *
129f627aab1SPaolo Bonzini  * These are internal functions used by the QEMU main loop.
130f627aab1SPaolo Bonzini  */
131f627aab1SPaolo Bonzini int aio_bh_poll(AioContext *ctx);
132f627aab1SPaolo Bonzini 
133f627aab1SPaolo Bonzini /**
134f627aab1SPaolo Bonzini  * qemu_bh_schedule: Schedule a bottom half.
135f627aab1SPaolo Bonzini  *
136f627aab1SPaolo Bonzini  * Scheduling a bottom half interrupts the main loop and causes the
137f627aab1SPaolo Bonzini  * execution of the callback that was passed to qemu_bh_new.
138f627aab1SPaolo Bonzini  *
139f627aab1SPaolo Bonzini  * Bottom halves that are scheduled from a bottom half handler are instantly
140f627aab1SPaolo Bonzini  * invoked.  This can create an infinite loop if a bottom half handler
141f627aab1SPaolo Bonzini  * schedules itself.
142f627aab1SPaolo Bonzini  *
143f627aab1SPaolo Bonzini  * @bh: The bottom half to be scheduled.
144f627aab1SPaolo Bonzini  */
145f627aab1SPaolo Bonzini void qemu_bh_schedule(QEMUBH *bh);
146f627aab1SPaolo Bonzini 
147f627aab1SPaolo Bonzini /**
148f627aab1SPaolo Bonzini  * qemu_bh_cancel: Cancel execution of a bottom half.
149f627aab1SPaolo Bonzini  *
150f627aab1SPaolo Bonzini  * Canceling execution of a bottom half undoes the effect of calls to
151f627aab1SPaolo Bonzini  * qemu_bh_schedule without freeing its resources yet.  While cancellation
152f627aab1SPaolo Bonzini  * itself is also wait-free and thread-safe, it can of course race with the
153f627aab1SPaolo Bonzini  * loop that executes bottom halves unless you are holding the iothread
154f627aab1SPaolo Bonzini  * mutex.  This makes it mostly useless if you are not holding the mutex.
155f627aab1SPaolo Bonzini  *
156f627aab1SPaolo Bonzini  * @bh: The bottom half to be canceled.
157f627aab1SPaolo Bonzini  */
158f627aab1SPaolo Bonzini void qemu_bh_cancel(QEMUBH *bh);
159f627aab1SPaolo Bonzini 
160f627aab1SPaolo Bonzini /**
161f627aab1SPaolo Bonzini  *qemu_bh_delete: Cancel execution of a bottom half and free its resources.
162f627aab1SPaolo Bonzini  *
163f627aab1SPaolo Bonzini  * Deleting a bottom half frees the memory that was allocated for it by
164f627aab1SPaolo Bonzini  * qemu_bh_new.  It also implies canceling the bottom half if it was
165f627aab1SPaolo Bonzini  * scheduled.
166f627aab1SPaolo Bonzini  *
167f627aab1SPaolo Bonzini  * @bh: The bottom half to be deleted.
168f627aab1SPaolo Bonzini  */
169f627aab1SPaolo Bonzini void qemu_bh_delete(QEMUBH *bh);
170f627aab1SPaolo Bonzini 
171cd9ba1ebSPaolo Bonzini /* Return whether there are any pending callbacks from the GSource
172cd9ba1ebSPaolo Bonzini  * attached to the AioContext.
173cd9ba1ebSPaolo Bonzini  *
174cd9ba1ebSPaolo Bonzini  * This is used internally in the implementation of the GSource.
175cd9ba1ebSPaolo Bonzini  */
176cd9ba1ebSPaolo Bonzini bool aio_pending(AioContext *ctx);
177cd9ba1ebSPaolo Bonzini 
1787c0628b2SPaolo Bonzini /* Progress in completing AIO work to occur.  This can issue new pending
1797c0628b2SPaolo Bonzini  * aio as a result of executing I/O completion or bh callbacks.
180bcdc1857SPaolo Bonzini  *
1817c0628b2SPaolo Bonzini  * If there is no pending AIO operation or completion (bottom half),
1822ea9b58fSKevin Wolf  * return false.  If there are pending AIO operations of bottom halves,
1832ea9b58fSKevin Wolf  * return true.
1847c0628b2SPaolo Bonzini  *
1857c0628b2SPaolo Bonzini  * If there are no pending bottom halves, but there are pending AIO
1867c0628b2SPaolo Bonzini  * operations, it may not be possible to make any progress without
1877c0628b2SPaolo Bonzini  * blocking.  If @blocking is true, this function will wait until one
1887c0628b2SPaolo Bonzini  * or more AIO events have completed, to ensure something has moved
1897c0628b2SPaolo Bonzini  * before returning.
1907c0628b2SPaolo Bonzini  */
1917c0628b2SPaolo Bonzini bool aio_poll(AioContext *ctx, bool blocking);
192a76bab49Saliguori 
1939958c351SPaolo Bonzini #ifdef CONFIG_POSIX
1949958c351SPaolo Bonzini /* Returns 1 if there are still outstanding AIO requests; 0 otherwise */
1959958c351SPaolo Bonzini typedef int (AioFlushHandler)(void *opaque);
1969958c351SPaolo Bonzini 
197a76bab49Saliguori /* Register a file descriptor and associated callbacks.  Behaves very similarly
198a76bab49Saliguori  * to qemu_set_fd_handler2.  Unlike qemu_set_fd_handler2, these callbacks will
199c57b6656SKevin Wolf  * be invoked when using qemu_aio_wait().
200a76bab49Saliguori  *
201a76bab49Saliguori  * Code that invokes AIO completion functions should rely on this function
202a76bab49Saliguori  * instead of qemu_set_fd_handler[2].
203a76bab49Saliguori  */
204a915f4bcSPaolo Bonzini void aio_set_fd_handler(AioContext *ctx,
205a915f4bcSPaolo Bonzini                         int fd,
206a76bab49Saliguori                         IOHandler *io_read,
207a76bab49Saliguori                         IOHandler *io_write,
208a76bab49Saliguori                         AioFlushHandler *io_flush,
209a76bab49Saliguori                         void *opaque);
2109958c351SPaolo Bonzini #endif
2119958c351SPaolo Bonzini 
2129958c351SPaolo Bonzini /* Register an event notifier and associated callbacks.  Behaves very similarly
2139958c351SPaolo Bonzini  * to event_notifier_set_handler.  Unlike event_notifier_set_handler, these callbacks
214c57b6656SKevin Wolf  * will be invoked when using qemu_aio_wait().
2159958c351SPaolo Bonzini  *
2169958c351SPaolo Bonzini  * Code that invokes AIO completion functions should rely on this function
2179958c351SPaolo Bonzini  * instead of event_notifier_set_handler.
2189958c351SPaolo Bonzini  */
219a915f4bcSPaolo Bonzini void aio_set_event_notifier(AioContext *ctx,
220a915f4bcSPaolo Bonzini                             EventNotifier *notifier,
221a915f4bcSPaolo Bonzini                             EventNotifierHandler *io_read,
222a915f4bcSPaolo Bonzini                             AioFlushEventNotifierHandler *io_flush);
223a915f4bcSPaolo Bonzini 
224e3713e00SPaolo Bonzini /* Return a GSource that lets the main loop poll the file descriptors attached
225e3713e00SPaolo Bonzini  * to this AioContext.
226e3713e00SPaolo Bonzini  */
227e3713e00SPaolo Bonzini GSource *aio_get_g_source(AioContext *ctx);
228e3713e00SPaolo Bonzini 
229*9b34277dSStefan Hajnoczi /* Return the ThreadPool bound to this AioContext */
230*9b34277dSStefan Hajnoczi struct ThreadPool *aio_get_thread_pool(AioContext *ctx);
231*9b34277dSStefan Hajnoczi 
232a915f4bcSPaolo Bonzini /* Functions to operate on the main QEMU AioContext.  */
233a915f4bcSPaolo Bonzini 
234a915f4bcSPaolo Bonzini bool qemu_aio_wait(void);
2359958c351SPaolo Bonzini void qemu_aio_set_event_notifier(EventNotifier *notifier,
2369958c351SPaolo Bonzini                                  EventNotifierHandler *io_read,
2379958c351SPaolo Bonzini                                  AioFlushEventNotifierHandler *io_flush);
238a76bab49Saliguori 
239a915f4bcSPaolo Bonzini #ifdef CONFIG_POSIX
240a915f4bcSPaolo Bonzini void qemu_aio_set_fd_handler(int fd,
241a915f4bcSPaolo Bonzini                              IOHandler *io_read,
242a915f4bcSPaolo Bonzini                              IOHandler *io_write,
243a915f4bcSPaolo Bonzini                              AioFlushHandler *io_flush,
244a915f4bcSPaolo Bonzini                              void *opaque);
245a915f4bcSPaolo Bonzini #endif
246a915f4bcSPaolo Bonzini 
247a76bab49Saliguori #endif
248