include/io/task.h

2  * QEMU I/O task
26 typedef void (*QIOTaskFunc)(QIOTask *task,
29 typedef void (*QIOTaskWorker)(QIOTask *task,
39  * a public API which accepts a task callback:
42  *   <title>Task function signature</title>
61  *   <title>Task callback implementation</title>
63  *  static void myobject_operation_notify(QIOTask *task,
67  *      if (qio_task_propagate_error(task, &err)) {
71  *          QMyObject *src = QMY_OBJECT(qio_task_get_source(task));
79  * task wants to set a timer to run once a second checking
84  *   <title>Task function implementation</title>
91  *      QIOTask *task;
93  *      task = qio_task_new(OBJECT(obj), func, opaque, notify);
98  *                         task,
106  * Notice that the source object is passed to the task, and
109  * the async task is still in progress.
115  *   <title>Task timer function</title>
119  *      QIOTask *task = QIO_TASK(opaque);
124  *           qio_task_set_error(task, err);
125  *           qio_task_complete(task);
128  *           qio_task_complete(task);
142  * automatically on the task causing it to be released and the
162  *    static void myobject_listen_worker(QIOTask *task,
165  *       QMyObject obj = QMY_OBJECT(qio_task_get_source(task));
171          qio_task_set_error(task, err);
180  *      QIOTask *task;
184  *      task = qio_task_new(OBJECT(obj), func, opaque, notify);
186  *      qio_task_run_in_thread(task, myobject_listen_worker,
200  * @func: the callback to invoke when the task completes
204  * Creates a new task struct to track completion of a
208  * 'err' attribute in the task object to determine if
211  * The returned task will be released when qio_task_complete()
214  * Returns: the task struct
223  * @task: the task struct
230  * Run a task in a background thread. When @worker
235 void qio_task_run_in_thread(QIOTask *task,
244  * @task: the task struct
246  * Wait for completion of a task that was previously
248  * ONLY be invoked if the task has not already
250  * is invoked, @task will have been freed.
260  * When that callback returns @task will be freed,
261  * so @task must not be referenced after this
264 void qio_task_wait_thread(QIOTask *task);
269  * @task: the task struct
271  * Invoke the completion callback for @task and
274 void qio_task_complete(QIOTask *task);
279  * @task: the task struct
282  * Associate an error with the task, which can later
291 void qio_task_set_error(QIOTask *task,
297  * @task: the task struct
300  * Propagate the error associated with @task
305 bool qio_task_propagate_error(QIOTask *task,
311  * @task: the task struct
314  * Associate an opaque result with the task,
319 void qio_task_set_result_pointer(QIOTask *task,
326  * @task: the task struct
329  * with the task, if any.
331  * Returns: the task result, or NULL
333 gpointer qio_task_get_result_pointer(QIOTask *task);
338  * @task: the task struct
341  * task. The caller does not own a reference on the
348 Object *qio_task_get_source(QIOTask *task);