4 * Copyright (c) 2015 Red Hat, Inc.
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.
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.
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/>.
24 #include "qemu-common.h"
25 #include "qom/object.h"
27 typedef struct QIOTask QIOTask
;
29 typedef void (*QIOTaskFunc
)(QIOTask
*task
,
32 typedef void (*QIOTaskWorker
)(QIOTask
*task
,
38 * The QIOTask object provides a simple mechanism for reporting
39 * success / failure of long running background operations.
41 * A object on which the operation is to be performed could have
42 * a public API which accepts a task callback:
45 * <title>Task function signature</title>
47 * void myobject_operation(QMyObject *obj,
50 * GDestroyNotify notify);
54 * The 'func' parameter is the callback to be invoked, and 'opaque'
55 * is data to pass to it. The optional 'notify' function is used
56 * to free 'opaque' when no longer needed.
58 * When the operation completes, the 'func' callback will be
59 * invoked, allowing the calling code to determine the result
60 * of the operation. An example QIOTaskFunc implementation may
64 * <title>Task callback implementation</title>
66 * static void myobject_operation_notify(QIOTask *task,
70 * if (qio_task_propagate_error(task, &err)) {
71 * ...deal with the failure...
74 * QMyObject *src = QMY_OBJECT(qio_task_get_source(task));
75 * ...deal with the completion...
81 * Now, lets say the implementation of the method using the
82 * task wants to set a timer to run once a second checking
83 * for completion of some activity. It would do something
87 * <title>Task function implementation</title>
89 * void myobject_operation(QMyObject *obj,
92 * GDestroyNotify notify)
96 * task = qio_task_new(OBJECT(obj), func, opaque, notify);
98 * g_timeout_add_full(G_PRIORITY_DEFAULT,
100 * myobject_operation_timer,
107 * It could equally have setup a watch on a file descriptor or
108 * created a background thread, or something else entirely.
109 * Notice that the source object is passed to the task, and
110 * QIOTask will hold a reference on that. This ensure that
111 * the QMyObject instance cannot be garbage collected while
112 * the async task is still in progress.
114 * In this case, myobject_operation_timer will fire after
118 * <title>Task timer function</title>
120 * gboolean myobject_operation_timer(gpointer opaque)
122 * QIOTask *task = QIO_TASK(opaque);
125 * ...check something important...
127 * qio_task_set_error(task, err);
128 * qio_task_complete(task);
130 * } else if (...work is completed ...) {
131 * qio_task_complete(task);
134 * ...carry on polling ...
140 * The 'qio_task_complete' call in this method will trigger
141 * the callback func 'myobject_operation_notify' shown
142 * earlier to deal with the results.
144 * Once this function returns false, object_unref will be called
145 * automatically on the task causing it to be released and the
146 * ref on QMyObject dropped too.
148 * The QIOTask module can also be used to perform operations
149 * in a background thread context, while still reporting the
150 * results in the main event thread. This allows code which
151 * cannot easily be rewritten to be asychronous (such as DNS
152 * lookups) to be easily run non-blocking. Reporting the
153 * results in the main thread context means that the caller
154 * typically does not need to be concerned about thread
155 * safety wrt the QEMU global mutex.
157 * For example, the socket_listen() method will block the caller
158 * while DNS lookups take place if given a name, instead of IP
159 * address. The C library often do not provide a practical async
160 * DNS API, so the to get non-blocking DNS lookups in a portable
161 * manner requires use of a thread. So achieve a non-blocking
162 * socket listen using QIOTask would require:
165 * static void myobject_listen_worker(QIOTask *task,
168 * QMyObject obj = QMY_OBJECT(qio_task_get_source(task));
169 * SocketAddress *addr = opaque;
172 * obj->fd = socket_listen(addr, &err);
174 qio_task_set_error(task, err);
177 * void myobject_listen_async(QMyObject *obj,
178 * SocketAddress *addr,
181 * GDestroyNotify notify)
184 * SocketAddress *addrCopy;
186 * addrCopy = QAPI_CLONE(SocketAddress, addr);
187 * task = qio_task_new(OBJECT(obj), func, opaque, notify);
189 * qio_task_run_in_thread(task, myobject_listen_worker,
191 * qapi_free_SocketAddress);
195 * NB, The 'func' callback passed into myobject_listen_async
196 * will be invoked from the main event thread, despite the
197 * actual operation being performed in a different thread.
202 * @source: the object on which the operation is invoked
203 * @func: the callback to invoke when the task completes
204 * @opaque: opaque data to pass to @func when invoked
205 * @destroy: optional callback to free @opaque
207 * Creates a new task struct to track completion of a
208 * background operation running on the object @source.
209 * When the operation completes or fails, the callback
210 * @func will be invoked. The callback can access the
211 * 'err' attribute in the task object to determine if
212 * the operation was successful or not.
214 * The returned task will be released when qio_task_complete()
217 * Returns: the task struct
219 QIOTask
*qio_task_new(Object
*source
,
222 GDestroyNotify destroy
);
225 * qio_task_run_in_thread:
226 * @task: the task struct
227 * @worker: the function to invoke in a thread
228 * @opaque: opaque data to pass to @worker
229 * @destroy: function to free @opaque
230 * @context: the context to run the complete hook. If %NULL, the
231 * default context will be used.
233 * Run a task in a background thread. When @worker
234 * returns it will call qio_task_complete() in
235 * the thread that is running the main loop associated
238 void qio_task_run_in_thread(QIOTask
*task
,
239 QIOTaskWorker worker
,
241 GDestroyNotify destroy
,
242 GMainContext
*context
);
246 * qio_task_wait_thread:
247 * @task: the task struct
249 * Wait for completion of a task that was previously
250 * invoked using qio_task_run_in_thread. This MUST
251 * ONLY be invoked if the task has not already
252 * completed, since after the completion callback
253 * is invoked, @task will have been freed.
255 * To avoid racing with execution of the completion
256 * callback provided with qio_task_new, this method
257 * MUST ONLY be invoked from the thread that is
258 * running the main loop associated with @context
259 * parameter to qio_task_run_in_thread.
261 * When the thread has completed, the completion
262 * callback provided to qio_task_new will be invoked.
263 * When that callback returns @task will be freed,
264 * so @task must not be referenced after this
267 void qio_task_wait_thread(QIOTask
*task
);
272 * @task: the task struct
274 * Invoke the completion callback for @task and
275 * then free its memory.
277 void qio_task_complete(QIOTask
*task
);
281 * qio_task_set_error:
282 * @task: the task struct
283 * @err: pointer to the error, or NULL
285 * Associate an error with the task, which can later
286 * be retrieved with the qio_task_propagate_error()
287 * method. This method takes ownership of @err, so
288 * it is not valid to access it after this call
289 * completes. If @err is NULL this is a no-op. If
290 * this is call multiple times, only the first
291 * provided @err will be recorded, later ones will
292 * be discarded and freed.
294 void qio_task_set_error(QIOTask
*task
,
299 * qio_task_propagate_error:
300 * @task: the task struct
301 * @errp: pointer to a NULL-initialized error object
303 * Propagate the error associated with @task
306 * Returns: true if an error was propagated, false otherwise
308 bool qio_task_propagate_error(QIOTask
*task
,
313 * qio_task_set_result_pointer:
314 * @task: the task struct
315 * @result: pointer to the result data
317 * Associate an opaque result with the task,
318 * which can later be retrieved with the
319 * qio_task_get_result_pointer() method
322 void qio_task_set_result_pointer(QIOTask
*task
,
324 GDestroyNotify notify
);
328 * qio_task_get_result_pointer:
329 * @task: the task struct
331 * Retrieve the opaque result data associated
332 * with the task, if any.
334 * Returns: the task result, or NULL
336 gpointer
qio_task_get_result_pointer(QIOTask
*task
);
340 * qio_task_get_source:
341 * @task: the task struct
343 * Get the source object associated with the background
344 * task. The caller does not own a reference on the
345 * returned Object, and so should call object_ref()
346 * if it wants to keep the object pointer outside the
347 * lifetime of the QIOTask object.
349 * Returns: the source object
351 Object
*qio_task_get_source(QIOTask
*task
);
353 #endif /* QIO_TASK_H */