include/block/aio.h

   1 /*
   2  * QEMU aio implementation
   3  *
   4  * Copyright IBM, Corp. 2008
   5  *
   6  * Authors:
   7  *  Anthony Liguori   <[email protected]>
   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/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"
  24
  25 typedef struct BlockDriverAIOCB BlockDriverAIOCB;
  26 typedef void BlockDriverCompletionFunc(void *opaque, int ret);
  27
  28 typedef struct AIOCBInfo {
  29     void (*cancel)(BlockDriverAIOCB *acb);
  30     size_t aiocb_size;
  31 } AIOCBInfo;
  32
  33 struct BlockDriverAIOCB {
  34     const AIOCBInfo *aiocb_info;
  35     BlockDriverState *bs;
  36     BlockDriverCompletionFunc *cb;
  37     void *opaque;
  38 };
  39
  40 void *qemu_aio_get(const AIOCBInfo *aiocb_info, BlockDriverState *bs,
  41                    BlockDriverCompletionFunc *cb, void *opaque);
  42 void qemu_aio_release(void *p);
  43
  44 typedef struct AioHandler AioHandler;
  45 typedef void QEMUBHFunc(void *opaque);
  46 typedef void IOHandler(void *opaque);
  47
  48 struct AioContext {
  49     GSource source;
  50
  51     /* Protects all fields from multi-threaded access */
  52     RFifoLock lock;
  53
  54     /* The list of registered AIO handlers */
  55     QLIST_HEAD(, AioHandler) aio_handlers;
  56
  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.
  60      */
  61     int walking_handlers;
  62
  63     /* lock to protect between bh's adders and deleter */
  64     QemuMutex bh_lock;
  65     /* Anchor of the list of Bottom Halves belonging to the context */
  66     struct QEMUBH *first_bh;
  67
  68     /* A simple lock used to protect the first_bh list, and ensure that
  69      * no callbacks are removed while we're walking and dispatching callbacks.
  70      */
  71     int walking_bh;
  72
  73     /* Used for aio_notify.  */
  74     EventNotifier notifier;
  75
  76     /* GPollFDs for aio_poll() */
  77     GArray *pollfds;
  78
  79     /* Thread pool for performing work and receiving completion callbacks */
  80     struct ThreadPool *thread_pool;
  81
  82     /* TimerLists for calling timers - one per clock type */
  83     QEMUTimerListGroup tlg;
  84 };
  85
  86 /**
  87  * aio_context_new: Allocate a new AioContext.
  88  *
  89  * AioContext provide a mini event-loop that can be waited on synchronously.
  90  * They also provide bottom halves, a service to execute a piece of code
  91  * as soon as possible.
  92  */
  93 AioContext *aio_context_new(void);
  94
  95 /**
  96  * aio_context_ref:
  97  * @ctx: The AioContext to operate on.
  98  *
  99  * Add a reference to an AioContext.
 100  */
 101 void aio_context_ref(AioContext *ctx);
 102
 103 /**
 104  * aio_context_unref:
 105  * @ctx: The AioContext to operate on.
 106  *
 107  * Drop a reference to an AioContext.
 108  */
 109 void aio_context_unref(AioContext *ctx);
 110
 111 /* Take ownership of the AioContext.  If the AioContext will be shared between
 112  * threads, a thread must have ownership when calling aio_poll().
 113  *
 114  * Note that multiple threads calling aio_poll() means timers, BHs, and
 115  * callbacks may be invoked from a different thread than they were registered
 116  * from.  Therefore, code must use AioContext acquire/release or use
 117  * fine-grained synchronization to protect shared state if other threads will
 118  * be accessing it simultaneously.
 119  */
 120 void aio_context_acquire(AioContext *ctx);
 121
 122 /* Relinquish ownership of the AioContext. */
 123 void aio_context_release(AioContext *ctx);
 124
 125 /**
 126  * aio_bh_new: Allocate a new bottom half structure.
 127  *
 128  * Bottom halves are lightweight callbacks whose invocation is guaranteed
 129  * to be wait-free, thread-safe and signal-safe.  The #QEMUBH structure
 130  * is opaque and must be allocated prior to its use.
 131  */
 132 QEMUBH *aio_bh_new(AioContext *ctx, QEMUBHFunc *cb, void *opaque);
 133
 134 /**
 135  * aio_notify: Force processing of pending events.
 136  *
 137  * Similar to signaling a condition variable, aio_notify forces
 138  * aio_wait to exit, so that the next call will re-examine pending events.
 139  * The caller of aio_notify will usually call aio_wait again very soon,
 140  * or go through another iteration of the GLib main loop.  Hence, aio_notify
 141  * also has the side effect of recalculating the sets of file descriptors
 142  * that the main loop waits for.
 143  *
 144  * Calling aio_notify is rarely necessary, because for example scheduling
 145  * a bottom half calls it already.
 146  */
 147 void aio_notify(AioContext *ctx);
 148
 149 /**
 150  * aio_bh_poll: Poll bottom halves for an AioContext.
 151  *
 152  * These are internal functions used by the QEMU main loop.
 153  * And notice that multiple occurrences of aio_bh_poll cannot
 154  * be called concurrently
 155  */
 156 int aio_bh_poll(AioContext *ctx);
 157
 158 /**
 159  * qemu_bh_schedule: Schedule a bottom half.
 160  *
 161  * Scheduling a bottom half interrupts the main loop and causes the
 162  * execution of the callback that was passed to qemu_bh_new.
 163  *
 164  * Bottom halves that are scheduled from a bottom half handler are instantly
 165  * invoked.  This can create an infinite loop if a bottom half handler
 166  * schedules itself.
 167  *
 168  * @bh: The bottom half to be scheduled.
 169  */
 170 void qemu_bh_schedule(QEMUBH *bh);
 171
 172 /**
 173  * qemu_bh_cancel: Cancel execution of a bottom half.
 174  *
 175  * Canceling execution of a bottom half undoes the effect of calls to
 176  * qemu_bh_schedule without freeing its resources yet.  While cancellation
 177  * itself is also wait-free and thread-safe, it can of course race with the
 178  * loop that executes bottom halves unless you are holding the iothread
 179  * mutex.  This makes it mostly useless if you are not holding the mutex.
 180  *
 181  * @bh: The bottom half to be canceled.
 182  */
 183 void qemu_bh_cancel(QEMUBH *bh);
 184
 185 /**
 186  *qemu_bh_delete: Cancel execution of a bottom half and free its resources.
 187  *
 188  * Deleting a bottom half frees the memory that was allocated for it by
 189  * qemu_bh_new.  It also implies canceling the bottom half if it was
 190  * scheduled.
 191  * This func is async. The bottom half will do the delete action at the finial
 192  * end.
 193  *
 194  * @bh: The bottom half to be deleted.
 195  */
 196 void qemu_bh_delete(QEMUBH *bh);
 197
 198 /* Return whether there are any pending callbacks from the GSource
 199  * attached to the AioContext.
 200  *
 201  * This is used internally in the implementation of the GSource.
 202  */
 203 bool aio_pending(AioContext *ctx);
 204
 205 /* Progress in completing AIO work to occur.  This can issue new pending
 206  * aio as a result of executing I/O completion or bh callbacks.
 207  *
 208  * If there is no pending AIO operation or completion (bottom half),
 209  * return false.  If there are pending AIO operations of bottom halves,
 210  * return true.
 211  *
 212  * If there are no pending bottom halves, but there are pending AIO
 213  * operations, it may not be possible to make any progress without
 214  * blocking.  If @blocking is true, this function will wait until one
 215  * or more AIO events have completed, to ensure something has moved
 216  * before returning.
 217  */
 218 bool aio_poll(AioContext *ctx, bool blocking);
 219
 220 #ifdef CONFIG_POSIX
 221 /* Register a file descriptor and associated callbacks.  Behaves very similarly
 222  * to qemu_set_fd_handler2.  Unlike qemu_set_fd_handler2, these callbacks will
 223  * be invoked when using aio_poll().
 224  *
 225  * Code that invokes AIO completion functions should rely on this function
 226  * instead of qemu_set_fd_handler[2].
 227  */
 228 void aio_set_fd_handler(AioContext *ctx,
 229                         int fd,
 230                         IOHandler *io_read,
 231                         IOHandler *io_write,
 232                         void *opaque);
 233 #endif
 234
 235 /* Register an event notifier and associated callbacks.  Behaves very similarly
 236  * to event_notifier_set_handler.  Unlike event_notifier_set_handler, these callbacks
 237  * will be invoked when using aio_poll().
 238  *
 239  * Code that invokes AIO completion functions should rely on this function
 240  * instead of event_notifier_set_handler.
 241  */
 242 void aio_set_event_notifier(AioContext *ctx,
 243                             EventNotifier *notifier,
 244                             EventNotifierHandler *io_read);
 245
 246 /* Return a GSource that lets the main loop poll the file descriptors attached
 247  * to this AioContext.
 248  */
 249 GSource *aio_get_g_source(AioContext *ctx);
 250
 251 /* Return the ThreadPool bound to this AioContext */
 252 struct ThreadPool *aio_get_thread_pool(AioContext *ctx);
 253
 254 /**
 255  * aio_timer_new:
 256  * @ctx: the aio context
 257  * @type: the clock type
 258  * @scale: the scale
 259  * @cb: the callback to call on timer expiry
 260  * @opaque: the opaque pointer to pass to the callback
 261  *
 262  * Allocate a new timer attached to the context @ctx.
 263  * The function is responsible for memory allocation.
 264  *
 265  * The preferred interface is aio_timer_init. Use that
 266  * unless you really need dynamic memory allocation.
 267  *
 268  * Returns: a pointer to the new timer
 269  */
 270 static inline QEMUTimer *aio_timer_new(AioContext *ctx, QEMUClockType type,
 271                                        int scale,
 272                                        QEMUTimerCB *cb, void *opaque)
 273 {
 274     return timer_new_tl(ctx->tlg.tl[type], scale, cb, opaque);
 275 }
 276
 277 /**
 278  * aio_timer_init:
 279  * @ctx: the aio context
 280  * @ts: the timer
 281  * @type: the clock type
 282  * @scale: the scale
 283  * @cb: the callback to call on timer expiry
 284  * @opaque: the opaque pointer to pass to the callback
 285  *
 286  * Initialise a new timer attached to the context @ctx.
 287  * The caller is responsible for memory allocation.
 288  */
 289 static inline void aio_timer_init(AioContext *ctx,
 290                                   QEMUTimer *ts, QEMUClockType type,
 291                                   int scale,
 292                                   QEMUTimerCB *cb, void *opaque)
 293 {
 294     timer_init(ts, ctx->tlg.tl[type], scale, cb, opaque);
 295 }
 296
 297 #endif