| /* |
| * 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 asynchronous (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 BQL. |
| * |
| * 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 */ |
