/* * QEMU I/O task * * Copyright (c) 2015 Red Hat, Inc. * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, see <http://www.gnu.org/licenses/>. * */ #ifndef QIO_TASK_H #define QIO_TASK_H typedef struct QIOTask QIOTask; typedef void (*QIOTaskFunc)(QIOTask *task, gpointer opaque); typedef void (*QIOTaskWorker)(QIOTask *task, gpointer opaque); /** * QIOTask: * * The QIOTask object provides a simple mechanism for reporting * success / failure of long running background operations. * * A object on which the operation is to be performed could have * a public API which accepts a task callback: * * <example> * <title>Task function signature</title> * <programlisting> * void myobject_operation(QMyObject *obj, * QIOTaskFunc *func, * gpointer opaque, * GDestroyNotify notify); * </programlisting> * </example> * * The 'func' parameter is the callback to be invoked, and 'opaque' * is data to pass to it. The optional 'notify' function is used * to free 'opaque' when no longer needed. * * When the operation completes, the 'func' callback will be * invoked, allowing the calling code to determine the result * of the operation. An example QIOTaskFunc implementation may * look like * * <example> * <title>Task callback implementation</title> * <programlisting> * static void myobject_operation_notify(QIOTask *task, * gpointer opaque) * { * Error *err = NULL; * if (qio_task_propagate_error(task, &err)) { * ...deal with the failure... * error_free(err); * } else { * QMyObject *src = QMY_OBJECT(qio_task_get_source(task)); * ...deal with the completion... * } * } * </programlisting> * </example> * * Now, lets say the implementation of the method using the * task wants to set a timer to run once a second checking * for completion of some activity. It would do something * like * * <example> * <title>Task function implementation</title> * <programlisting> * void myobject_operation(QMyObject *obj, * QIOTaskFunc *func, * gpointer opaque, * GDestroyNotify notify) * { * QIOTask *task; * * task = qio_task_new(OBJECT(obj), func, opaque, notify); * * g_timeout_add_full(G_PRIORITY_DEFAULT, * 1000, * myobject_operation_timer, * task, * NULL); * } * </programlisting> * </example> * * It could equally have setup a watch on a file descriptor or * created a background thread, or something else entirely. * Notice that the source object is passed to the task, and * QIOTask will hold a reference on that. This ensure that * the QMyObject instance cannot be garbage collected while * the async task is still in progress. * * In this case, myobject_operation_timer will fire after * 3 secs and do * * <example> * <title>Task timer function</title> * <programlisting> * gboolean myobject_operation_timer(gpointer opaque) * { * QIOTask *task = QIO_TASK(opaque); * Error *err = NULL; * * ...check something important... * if (err) { * qio_task_set_error(task, err); * qio_task_complete(task); * return FALSE; * } else if (...work is completed ...) { * qio_task_complete(task); * return FALSE; * } * ...carry on polling ... * return TRUE; * } * </programlisting> * </example> * * The 'qio_task_complete' call in this method will trigger * the callback func 'myobject_operation_notify' shown * earlier to deal with the results. * * Once this function returns false, object_unref will be called * automatically on the task causing it to be released and the * ref on QMyObject dropped too. * * The QIOTask module can also be used to perform operations * in a background thread context, while still reporting the * results in the main event thread. This allows code which * cannot easily be rewritten to be asychronous (such as DNS * lookups) to be easily run non-blocking. Reporting the * results in the main thread context means that the caller * typically does not need to be concerned about thread * safety wrt the QEMU global mutex. * * For example, the socket_listen() method will block the caller * while DNS lookups take place if given a name, instead of IP * address. The C library often do not provide a practical async * DNS API, so the to get non-blocking DNS lookups in a portable * manner requires use of a thread. So achieve a non-blocking * socket listen using QIOTask would require: * * <example> * static void myobject_listen_worker(QIOTask *task, * gpointer opaque) * { * QMyObject obj = QMY_OBJECT(qio_task_get_source(task)); * SocketAddress *addr = opaque; * Error *err = NULL; * * obj->fd = socket_listen(addr, &err); * qio_task_set_error(task, err); * } * * void myobject_listen_async(QMyObject *obj, * SocketAddress *addr, * QIOTaskFunc *func, * gpointer opaque, * GDestroyNotify notify) * { * QIOTask *task; * SocketAddress *addrCopy; * * addrCopy = QAPI_CLONE(SocketAddress, addr); * task = qio_task_new(OBJECT(obj), func, opaque, notify); * * qio_task_run_in_thread(task, myobject_listen_worker, * addrCopy, * qapi_free_SocketAddress); * } * </example> * * NB, The 'func' callback passed into myobject_listen_async * will be invoked from the main event thread, despite the * actual operation being performed in a different thread. */ /** * qio_task_new: * @source: the object on which the operation is invoked * @func: the callback to invoke when the task completes * @opaque: opaque data to pass to @func when invoked * @destroy: optional callback to free @opaque * * Creates a new task struct to track completion of a * background operation running on the object @source. * When the operation completes or fails, the callback * @func will be invoked. The callback can access the * 'err' attribute in the task object to determine if * the operation was successful or not. * * The returned task will be released when qio_task_complete() * is invoked. * * Returns: the task struct */ QIOTask *qio_task_new(Object *source, QIOTaskFunc func, gpointer opaque, GDestroyNotify destroy); /** * qio_task_run_in_thread: * @task: the task struct * @worker: the function to invoke in a thread * @opaque: opaque data to pass to @worker * @destroy: function to free @opaque * @context: the context to run the complete hook. If %NULL, the * default context will be used. * * Run a task in a background thread. When @worker * returns it will call qio_task_complete() in * the thread that is running the main loop associated * with @context. */ void qio_task_run_in_thread(QIOTask *task, QIOTaskWorker worker, gpointer opaque, GDestroyNotify destroy, GMainContext *context); /** * qio_task_wait_thread: * @task: the task struct * * Wait for completion of a task that was previously * invoked using qio_task_run_in_thread. This MUST * ONLY be invoked if the task has not already * completed, since after the completion callback * is invoked, @task will have been freed. * * To avoid racing with execution of the completion * callback provided with qio_task_new, this method * MUST ONLY be invoked from the thread that is * running the main loop associated with @context * parameter to qio_task_run_in_thread. * * When the thread has completed, the completion * callback provided to qio_task_new will be invoked. * When that callback returns @task will be freed, * so @task must not be referenced after this * method completes. */ void qio_task_wait_thread(QIOTask *task); /** * qio_task_complete: * @task: the task struct * * Invoke the completion callback for @task and * then free its memory. */ void qio_task_complete(QIOTask *task); /** * qio_task_set_error: * @task: the task struct * @err: pointer to the error, or NULL * * Associate an error with the task, which can later * be retrieved with the qio_task_propagate_error() * method. This method takes ownership of @err, so * it is not valid to access it after this call * completes. If @err is NULL this is a no-op. If * this is call multiple times, only the first * provided @err will be recorded, later ones will * be discarded and freed. */ void qio_task_set_error(QIOTask *task, Error *err); /** * qio_task_propagate_error: * @task: the task struct * @errp: pointer to a NULL-initialized error object * * Propagate the error associated with @task * into @errp. * * Returns: true if an error was propagated, false otherwise */ bool qio_task_propagate_error(QIOTask *task, Error **errp); /** * qio_task_set_result_pointer: * @task: the task struct * @result: pointer to the result data * * Associate an opaque result with the task, * which can later be retrieved with the * qio_task_get_result_pointer() method * */ void qio_task_set_result_pointer(QIOTask *task, gpointer result, GDestroyNotify notify); /** * qio_task_get_result_pointer: * @task: the task struct * * Retrieve the opaque result data associated * with the task, if any. * * Returns: the task result, or NULL */ gpointer qio_task_get_result_pointer(QIOTask *task); /** * qio_task_get_source: * @task: the task struct * * Get the source object associated with the background * task. The caller does not own a reference on the * returned Object, and so should call object_ref() * if it wants to keep the object pointer outside the * lifetime of the QIOTask object. * * Returns: the source object */ Object *qio_task_get_source(QIOTask *task); #endif /* QIO_TASK_H */