include/io/task.h

   1 /*
   2  * QEMU I/O task
   3  *
   4  * Copyright (c) 2015 Red Hat, Inc.
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  18  *
  19  */
  20
  21 #ifndef QIO_TASK_H
  22 #define QIO_TASK_H
  23
  24 #include "qom/object.h"
  25
  26 typedef struct QIOTask QIOTask;
  27
  28 typedef void (*QIOTaskFunc)(QIOTask *task,
  29                             gpointer opaque);
  30
  31 typedef void (*QIOTaskWorker)(QIOTask *task,
  32                               gpointer opaque);
  33
  34 /**
  35  * QIOTask:
  36  *
  37  * The QIOTask object provides a simple mechanism for reporting
  38  * success / failure of long running background operations.
  39  *
  40  * A object on which the operation is to be performed could have
  41  * a public API which accepts a task callback:
  42  *
  43  * <example>
  44  *   <title>Task function signature</title>
  45  *   <programlisting>
  46  *  void myobject_operation(QMyObject *obj,
  47  *                          QIOTaskFunc *func,
  48  *                          gpointer opaque,
  49  *                          GDestroyNotify notify);
  50  *   </programlisting>
  51  * </example>
  52  *
  53  * The 'func' parameter is the callback to be invoked, and 'opaque'
  54  * is data to pass to it. The optional 'notify' function is used
  55  * to free 'opaque' when no longer needed.
  56  *
  57  * When the operation completes, the 'func' callback will be
  58  * invoked, allowing the calling code to determine the result
  59  * of the operation. An example QIOTaskFunc implementation may
  60  * look like
  61  *
  62  * <example>
  63  *   <title>Task callback implementation</title>
  64  *   <programlisting>
  65  *  static void myobject_operation_notify(QIOTask *task,
  66  *                                        gpointer opaque)
  67  *  {
  68  *      Error *err = NULL;
  69  *      if (qio_task_propagate_error(task, &err)) {
  70  *          ...deal with the failure...
  71  *          error_free(err);
  72  *      } else {
  73  *          QMyObject *src = QMY_OBJECT(qio_task_get_source(task));
  74  *          ...deal with the completion...
  75  *      }
  76  *  }
  77  *   </programlisting>
  78  * </example>
  79  *
  80  * Now, lets say the implementation of the method using the
  81  * task wants to set a timer to run once a second checking
  82  * for completion of some activity. It would do something
  83  * like
  84  *
  85  * <example>
  86  *   <title>Task function implementation</title>
  87  *   <programlisting>
  88  *    void myobject_operation(QMyObject *obj,
  89  *                            QIOTaskFunc *func,
  90  *                            gpointer opaque,
  91  *                            GDestroyNotify notify)
  92  *    {
  93  *      QIOTask *task;
  94  *
  95  *      task = qio_task_new(OBJECT(obj), func, opaque, notify);
  96  *
  97  *      g_timeout_add_full(G_PRIORITY_DEFAULT,
  98  *                         1000,
  99  *                         myobject_operation_timer,
 100  *                         task,
 101  *                         NULL);
 102  *    }
 103  *   </programlisting>
 104  * </example>
 105  *
 106  * It could equally have setup a watch on a file descriptor or
 107  * created a background thread, or something else entirely.
 108  * Notice that the source object is passed to the task, and
 109  * QIOTask will hold a reference on that. This ensure that
 110  * the QMyObject instance cannot be garbage collected while
 111  * the async task is still in progress.
 112  *
 113  * In this case, myobject_operation_timer will fire after
 114  * 3 secs and do
 115  *
 116  * <example>
 117  *   <title>Task timer function</title>
 118  *   <programlisting>
 119  *   gboolean myobject_operation_timer(gpointer opaque)
 120  *   {
 121  *      QIOTask *task = QIO_TASK(opaque);
 122  *      Error *err = NULL;
 123  *
 124  *      ...check something important...
 125  *       if (err) {
 126  *           qio_task_set_error(task, err);
 127  *           qio_task_complete(task);
 128  *           return FALSE;
 129  *       } else if (...work is completed ...) {
 130  *           qio_task_complete(task);
 131  *           return FALSE;
 132  *       }
 133  *       ...carry on polling ...
 134  *       return TRUE;
 135  *   }
 136  *   </programlisting>
 137  * </example>
 138  *
 139  * The 'qio_task_complete' call in this method will trigger
 140  * the callback func 'myobject_operation_notify' shown
 141  * earlier to deal with the results.
 142  *
 143  * Once this function returns false, object_unref will be called
 144  * automatically on the task causing it to be released and the
 145  * ref on QMyObject dropped too.
 146  *
 147  * The QIOTask module can also be used to perform operations
 148  * in a background thread context, while still reporting the
 149  * results in the main event thread. This allows code which
 150  * cannot easily be rewritten to be asychronous (such as DNS
 151  * lookups) to be easily run non-blocking. Reporting the
 152  * results in the main thread context means that the caller
 153  * typically does not need to be concerned about thread
 154  * safety wrt the QEMU global mutex.
 155  *
 156  * For example, the socket_listen() method will block the caller
 157  * while DNS lookups take place if given a name, instead of IP
 158  * address. The C library often do not provide a practical async
 159  * DNS API, so the to get non-blocking DNS lookups in a portable
 160  * manner requires use of a thread. So achieve a non-blocking
 161  * socket listen using QIOTask would require:
 162  *
 163  * <example>
 164  *    static void myobject_listen_worker(QIOTask *task,
 165  *                                       gpointer opaque)
 166  *    {
 167  *       QMyObject obj = QMY_OBJECT(qio_task_get_source(task));
 168  *       SocketAddress *addr = opaque;
 169  *       Error *err = NULL;
 170  *
 171  *       obj->fd = socket_listen(addr, &err);
 172  *
 173          qio_task_set_error(task, err);
 174  *    }
 175  *
 176  *    void myobject_listen_async(QMyObject *obj,
 177  *                               SocketAddress *addr,
 178  *                               QIOTaskFunc *func,
 179  *                               gpointer opaque,
 180  *                               GDestroyNotify notify)
 181  *    {
 182  *      QIOTask *task;
 183  *      SocketAddress *addrCopy;
 184  *
 185  *      addrCopy = QAPI_CLONE(SocketAddress, addr);
 186  *      task = qio_task_new(OBJECT(obj), func, opaque, notify);
 187  *
 188  *      qio_task_run_in_thread(task, myobject_listen_worker,
 189  *                             addrCopy,
 190  *                             qapi_free_SocketAddress);
 191  *    }
 192  * </example>
 193  *
 194  * NB, The 'func' callback passed into myobject_listen_async
 195  * will be invoked from the main event thread, despite the
 196  * actual operation being performed in a different thread.
 197  */
 198
 199 /**
 200  * qio_task_new:
 201  * @source: the object on which the operation is invoked
 202  * @func: the callback to invoke when the task completes
 203  * @opaque: opaque data to pass to @func when invoked
 204  * @destroy: optional callback to free @opaque
 205  *
 206  * Creates a new task struct to track completion of a
 207  * background operation running on the object @source.
 208  * When the operation completes or fails, the callback
 209  * @func will be invoked. The callback can access the
 210  * 'err' attribute in the task object to determine if
 211  * the operation was successful or not.
 212  *
 213  * The returned task will be released when qio_task_complete()
 214  * is invoked.
 215  *
 216  * Returns: the task struct
 217  */
 218 QIOTask *qio_task_new(Object *source,
 219                       QIOTaskFunc func,
 220                       gpointer opaque,
 221                       GDestroyNotify destroy);
 222
 223 /**
 224  * qio_task_run_in_thread:
 225  * @task: the task struct
 226  * @worker: the function to invoke in a thread
 227  * @opaque: opaque data to pass to @worker
 228  * @destroy: function to free @opaque
 229  * @context: the context to run the complete hook. If %NULL, the
 230  *           default context will be used.
 231  *
 232  * Run a task in a background thread. When @worker
 233  * returns it will call qio_task_complete() in
 234  * the thread that is running the main loop associated
 235  * with @context.
 236  */
 237 void qio_task_run_in_thread(QIOTask *task,
 238                             QIOTaskWorker worker,
 239                             gpointer opaque,
 240                             GDestroyNotify destroy,
 241                             GMainContext *context);
 242
 243
 244 /**
 245  * qio_task_wait_thread:
 246  * @task: the task struct
 247  *
 248  * Wait for completion of a task that was previously
 249  * invoked using qio_task_run_in_thread. This MUST
 250  * ONLY be invoked if the task has not already
 251  * completed, since after the completion callback
 252  * is invoked, @task will have been freed.
 253  *
 254  * To avoid racing with execution of the completion
 255  * callback provided with qio_task_new, this method
 256  * MUST ONLY be invoked from the thread that is
 257  * running the main loop associated with @context
 258  * parameter to qio_task_run_in_thread.
 259  *
 260  * When the thread has completed, the completion
 261  * callback provided to qio_task_new will be invoked.
 262  * When that callback returns @task will be freed,
 263  * so @task must not be referenced after this
 264  * method completes.
 265  */
 266 void qio_task_wait_thread(QIOTask *task);
 267
 268
 269 /**
 270  * qio_task_complete:
 271  * @task: the task struct
 272  *
 273  * Invoke the completion callback for @task and
 274  * then free its memory.
 275  */
 276 void qio_task_complete(QIOTask *task);
 277
 278
 279 /**
 280  * qio_task_set_error:
 281  * @task: the task struct
 282  * @err: pointer to the error, or NULL
 283  *
 284  * Associate an error with the task, which can later
 285  * be retrieved with the qio_task_propagate_error()
 286  * method. This method takes ownership of @err, so
 287  * it is not valid to access it after this call
 288  * completes. If @err is NULL this is a no-op. If
 289  * this is call multiple times, only the first
 290  * provided @err will be recorded, later ones will
 291  * be discarded and freed.
 292  */
 293 void qio_task_set_error(QIOTask *task,
 294                         Error *err);
 295
 296
 297 /**
 298  * qio_task_propagate_error:
 299  * @task: the task struct
 300  * @errp: pointer to a NULL-initialized error object
 301  *
 302  * Propagate the error associated with @task
 303  * into @errp.
 304  *
 305  * Returns: true if an error was propagated, false otherwise
 306  */
 307 bool qio_task_propagate_error(QIOTask *task,
 308                               Error **errp);
 309
 310
 311 /**
 312  * qio_task_set_result_pointer:
 313  * @task: the task struct
 314  * @result: pointer to the result data
 315  *
 316  * Associate an opaque result with the task,
 317  * which can later be retrieved with the
 318  * qio_task_get_result_pointer() method
 319  *
 320  */
 321 void qio_task_set_result_pointer(QIOTask *task,
 322                                  gpointer result,
 323                                  GDestroyNotify notify);
 324
 325
 326 /**
 327  * qio_task_get_result_pointer:
 328  * @task: the task struct
 329  *
 330  * Retrieve the opaque result data associated
 331  * with the task, if any.
 332  *
 333  * Returns: the task result, or NULL
 334  */
 335 gpointer qio_task_get_result_pointer(QIOTask *task);
 336
 337
 338 /**
 339  * qio_task_get_source:
 340  * @task: the task struct
 341  *
 342  * Get the source object associated with the background
 343  * task. The caller does not own a reference on the
 344  * returned Object, and so should call object_ref()
 345  * if it wants to keep the object pointer outside the
 346  * lifetime of the QIOTask object.
 347  *
 348  * Returns: the source object
 349  */
 350 Object *qio_task_get_source(QIOTask *task);
 351
 352 #endif /* QIO_TASK_H */