include/block/aio.h

   1 /*
   2  * QEMU aio implementation
   3  *
   4  * Copyright IBM, Corp. 2008
   5  *
   6  * Authors:
   7  *  Anthony Liguori   <aliguori@us.ibm.com>
   8  *
   9  * This work is licensed under the terms of the GNU GPL, version 2.  See
  10  * the COPYING file in the top-level directory.
  11  *
  12  */
  13
  14 #ifndef QEMU_AIO_H
  15 #define QEMU_AIO_H
  16
  17 #include "qemu-common.h"
  18 #include "qemu/queue.h"
  19 #include "qemu/event_notifier.h"
  20 #include "qemu/thread.h"
  21
  22 typedef struct BlockDriverAIOCB BlockDriverAIOCB;
  23 typedef void BlockDriverCompletionFunc(void *opaque, int ret);
  24
  25 typedef struct AIOCBInfo {
  26     void (*cancel)(BlockDriverAIOCB *acb);
  27     size_t aiocb_size;
  28 } AIOCBInfo;
  29
  30 struct BlockDriverAIOCB {
  31     const AIOCBInfo *aiocb_info;
  32     BlockDriverState *bs;
  33     BlockDriverCompletionFunc *cb;
  34     void *opaque;
  35 };
  36
  37 void *qemu_aio_get(const AIOCBInfo *aiocb_info, BlockDriverState *bs,
  38                    BlockDriverCompletionFunc *cb, void *opaque);
  39 void qemu_aio_release(void *p);
  40
  41 typedef struct AioHandler AioHandler;
  42 typedef void QEMUBHFunc(void *opaque);
  43 typedef void IOHandler(void *opaque);
  44
  45 typedef struct AioContext {
  46     GSource source;
  47
  48     /* The list of registered AIO handlers */
  49     QLIST_HEAD(, AioHandler) aio_handlers;
  50
  51     /* This is a simple lock used to protect the aio_handlers list.
  52      * Specifically, it's used to ensure that no callbacks are removed while
  53      * we're walking and dispatching callbacks.
  54      */
  55     int walking_handlers;
  56
  57     /* lock to protect between bh's adders and deleter */
  58     QemuMutex bh_lock;
  59     /* Anchor of the list of Bottom Halves belonging to the context */
  60     struct QEMUBH *first_bh;
  61
  62     /* A simple lock used to protect the first_bh list, and ensure that
  63      * no callbacks are removed while we're walking and dispatching callbacks.
  64      */
  65     int walking_bh;
  66
  67     /* Used for aio_notify.  */
  68     EventNotifier notifier;
  69
  70     /* GPollFDs for aio_poll() */
  71     GArray *pollfds;
  72
  73     /* Thread pool for performing work and receiving completion callbacks */
  74     struct ThreadPool *thread_pool;
  75 } AioContext;
  76
  77 /* Returns 1 if there are still outstanding AIO requests; 0 otherwise */
  78 typedef int (AioFlushEventNotifierHandler)(EventNotifier *e);
  79
  80 /**
  81  * aio_context_new: Allocate a new AioContext.
  82  *
  83  * AioContext provide a mini event-loop that can be waited on synchronously.
  84  * They also provide bottom halves, a service to execute a piece of code
  85  * as soon as possible.
  86  */
  87 AioContext *aio_context_new(void);
  88
  89 /**
  90  * aio_context_ref:
  91  * @ctx: The AioContext to operate on.
  92  *
  93  * Add a reference to an AioContext.
  94  */
  95 void aio_context_ref(AioContext *ctx);
  96
  97 /**
  98  * aio_context_unref:
  99  * @ctx: The AioContext to operate on.
 100  *
 101  * Drop a reference to an AioContext.
 102  */
 103 void aio_context_unref(AioContext *ctx);
 104
 105 /**
 106  * aio_bh_new: Allocate a new bottom half structure.
 107  *
 108  * Bottom halves are lightweight callbacks whose invocation is guaranteed
 109  * to be wait-free, thread-safe and signal-safe.  The #QEMUBH structure
 110  * is opaque and must be allocated prior to its use.
 111  */
 112 QEMUBH *aio_bh_new(AioContext *ctx, QEMUBHFunc *cb, void *opaque);
 113
 114 /**
 115  * aio_notify: Force processing of pending events.
 116  *
 117  * Similar to signaling a condition variable, aio_notify forces
 118  * aio_wait to exit, so that the next call will re-examine pending events.
 119  * The caller of aio_notify will usually call aio_wait again very soon,
 120  * or go through another iteration of the GLib main loop.  Hence, aio_notify
 121  * also has the side effect of recalculating the sets of file descriptors
 122  * that the main loop waits for.
 123  *
 124  * Calling aio_notify is rarely necessary, because for example scheduling
 125  * a bottom half calls it already.
 126  */
 127 void aio_notify(AioContext *ctx);
 128
 129 /**
 130  * aio_bh_poll: Poll bottom halves for an AioContext.
 131  *
 132  * These are internal functions used by the QEMU main loop.
 133  * And notice that multiple occurrences of aio_bh_poll cannot
 134  * be called concurrently
 135  */
 136 int aio_bh_poll(AioContext *ctx);
 137
 138 /**
 139  * qemu_bh_schedule: Schedule a bottom half.
 140  *
 141  * Scheduling a bottom half interrupts the main loop and causes the
 142  * execution of the callback that was passed to qemu_bh_new.
 143  *
 144  * Bottom halves that are scheduled from a bottom half handler are instantly
 145  * invoked.  This can create an infinite loop if a bottom half handler
 146  * schedules itself.
 147  *
 148  * @bh: The bottom half to be scheduled.
 149  */
 150 void qemu_bh_schedule(QEMUBH *bh);
 151
 152 /**
 153  * qemu_bh_cancel: Cancel execution of a bottom half.
 154  *
 155  * Canceling execution of a bottom half undoes the effect of calls to
 156  * qemu_bh_schedule without freeing its resources yet.  While cancellation
 157  * itself is also wait-free and thread-safe, it can of course race with the
 158  * loop that executes bottom halves unless you are holding the iothread
 159  * mutex.  This makes it mostly useless if you are not holding the mutex.
 160  *
 161  * @bh: The bottom half to be canceled.
 162  */
 163 void qemu_bh_cancel(QEMUBH *bh);
 164
 165 /**
 166  *qemu_bh_delete: Cancel execution of a bottom half and free its resources.
 167  *
 168  * Deleting a bottom half frees the memory that was allocated for it by
 169  * qemu_bh_new.  It also implies canceling the bottom half if it was
 170  * scheduled.
 171  * This func is async. The bottom half will do the delete action at the finial
 172  * end.
 173  *
 174  * @bh: The bottom half to be deleted.
 175  */
 176 void qemu_bh_delete(QEMUBH *bh);
 177
 178 /* Return whether there are any pending callbacks from the GSource
 179  * attached to the AioContext.
 180  *
 181  * This is used internally in the implementation of the GSource.
 182  */
 183 bool aio_pending(AioContext *ctx);
 184
 185 /* Progress in completing AIO work to occur.  This can issue new pending
 186  * aio as a result of executing I/O completion or bh callbacks.
 187  *
 188  * If there is no pending AIO operation or completion (bottom half),
 189  * return false.  If there are pending AIO operations of bottom halves,
 190  * return true.
 191  *
 192  * If there are no pending bottom halves, but there are pending AIO
 193  * operations, it may not be possible to make any progress without
 194  * blocking.  If @blocking is true, this function will wait until one
 195  * or more AIO events have completed, to ensure something has moved
 196  * before returning.
 197  */
 198 bool aio_poll(AioContext *ctx, bool blocking);
 199
 200 #ifdef CONFIG_POSIX
 201 /* Returns 1 if there are still outstanding AIO requests; 0 otherwise */
 202 typedef int (AioFlushHandler)(void *opaque);
 203
 204 /* Register a file descriptor and associated callbacks.  Behaves very similarly
 205  * to qemu_set_fd_handler2.  Unlike qemu_set_fd_handler2, these callbacks will
 206  * be invoked when using qemu_aio_wait().
 207  *
 208  * Code that invokes AIO completion functions should rely on this function
 209  * instead of qemu_set_fd_handler[2].
 210  */
 211 void aio_set_fd_handler(AioContext *ctx,
 212                         int fd,
 213                         IOHandler *io_read,
 214                         IOHandler *io_write,
 215                         AioFlushHandler *io_flush,
 216                         void *opaque);
 217 #endif
 218
 219 /* Register an event notifier and associated callbacks.  Behaves very similarly
 220  * to event_notifier_set_handler.  Unlike event_notifier_set_handler, these callbacks
 221  * will be invoked when using qemu_aio_wait().
 222  *
 223  * Code that invokes AIO completion functions should rely on this function
 224  * instead of event_notifier_set_handler.
 225  */
 226 void aio_set_event_notifier(AioContext *ctx,
 227                             EventNotifier *notifier,
 228                             EventNotifierHandler *io_read,
 229                             AioFlushEventNotifierHandler *io_flush);
 230
 231 /* Return a GSource that lets the main loop poll the file descriptors attached
 232  * to this AioContext.
 233  */
 234 GSource *aio_get_g_source(AioContext *ctx);
 235
 236 /* Return the ThreadPool bound to this AioContext */
 237 struct ThreadPool *aio_get_thread_pool(AioContext *ctx);
 238
 239 /* Functions to operate on the main QEMU AioContext.  */
 240
 241 bool qemu_aio_wait(void);
 242 void qemu_aio_set_event_notifier(EventNotifier *notifier,
 243                                  EventNotifierHandler *io_read,
 244                                  AioFlushEventNotifierHandler *io_flush);
 245
 246 #ifdef CONFIG_POSIX
 247 void qemu_aio_set_fd_handler(int fd,
 248                              IOHandler *io_read,
 249                              IOHandler *io_write,
 250                              AioFlushHandler *io_flush,
 251                              void *opaque);
 252 #endif
 253
 254 #endif