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 "qemu-common.h" 25 #include "qom/object.h" 26 27 typedef struct QIOTask QIOTask; 28 29 typedef void (*QIOTaskFunc)(QIOTask *task, 30 gpointer opaque); 31 32 typedef void (*QIOTaskWorker)(QIOTask *task, 33 gpointer opaque); 34 35 /** 36 * QIOTask: 37 * 38 * The QIOTask object provides a simple mechanism for reporting 39 * success / failure of long running background operations. 40 * 41 * A object on which the operation is to be performed could have 42 * a public API which accepts a task callback: 43 * 44 * <example> 45 * <title>Task function signature</title> 46 * <programlisting> 47 * void myobject_operation(QMyObject *obj, 48 * QIOTaskFunc *func, 49 * gpointer opaque, 50 * GDestroyNotify notify); 51 * </programlisting> 52 * </example> 53 * 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. 57 * 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 61 * look like 62 * 63 * <example> 64 * <title>Task callback implementation</title> 65 * <programlisting> 66 * static void myobject_operation_notify(QIOTask *task, 67 * gpointer opaque) 68 * { 69 * Error *err = NULL; 70 * if (qio_task_propagate_error(task, &err)) { 71 * ...deal with the failure... 72 * error_free(err); 73 * } else { 74 * QMyObject *src = QMY_OBJECT(qio_task_get_source(task)); 75 * ...deal with the completion... 76 * } 77 * } 78 * </programlisting> 79 * </example> 80 * 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 84 * like 85 * 86 * <example> 87 * <title>Task function implementation</title> 88 * <programlisting> 89 * void myobject_operation(QMyObject *obj, 90 * QIOTaskFunc *func, 91 * gpointer opaque, 92 * GDestroyNotify notify) 93 * { 94 * QIOTask *task; 95 * 96 * task = qio_task_new(OBJECT(obj), func, opaque, notify); 97 * 98 * g_timeout_add_full(G_PRIORITY_DEFAULT, 99 * 1000, 100 * myobject_operation_timer, 101 * task, 102 * NULL); 103 * } 104 * </programlisting> 105 * </example> 106 * 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. 113 * 114 * In this case, myobject_operation_timer will fire after 115 * 3 secs and do 116 * 117 * <example> 118 * <title>Task timer function</title> 119 * <programlisting> 120 * gboolean myobject_operation_timer(gpointer opaque) 121 * { 122 * QIOTask *task = QIO_TASK(opaque); 123 * Error *err;* 124 * 125 * ...check something important... 126 * if (err) { 127 * qio_task_set_error(task, err); 128 * qio_task_complete(task); 129 * return FALSE; 130 * } else if (...work is completed ...) { 131 * qio_task_complete(task); 132 * return FALSE; 133 * } 134 * ...carry on polling ... 135 * return TRUE; 136 * } 137 * </programlisting> 138 * </example> 139 * 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. 143 * 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. 147 * 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. 156 * 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: 163 * 164 * <example> 165 * static void myobject_listen_worker(QIOTask *task, 166 * gpointer opaque) 167 * { 168 * QMyObject obj = QMY_OBJECT(qio_task_get_source(task)); 169 * SocketAddress *addr = opaque; 170 * Error *err = NULL; 171 * 172 * obj->fd = socket_listen(addr, &err); 173 * 174 qio_task_set_error(task, err); 175 * } 176 * 177 * void myobject_listen_async(QMyObject *obj, 178 * SocketAddress *addr, 179 * QIOTaskFunc *func, 180 * gpointer opaque, 181 * GDestroyNotify notify) 182 * { 183 * QIOTask *task; 184 * SocketAddress *addrCopy; 185 * 186 * addrCopy = QAPI_CLONE(SocketAddress, addr); 187 * task = qio_task_new(OBJECT(obj), func, opaque, notify); 188 * 189 * qio_task_run_in_thread(task, myobject_listen_worker, 190 * addrCopy, 191 * qapi_free_SocketAddress); 192 * } 193 * </example> 194 * 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. 198 */ 199 200 /** 201 * qio_task_new: 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 206 * 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. 213 * 214 * The returned task will be released when qio_task_complete() 215 * is invoked. 216 * 217 * Returns: the task struct 218 */ 219 QIOTask *qio_task_new(Object *source, 220 QIOTaskFunc func, 221 gpointer opaque, 222 GDestroyNotify destroy); 223 224 /** 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. 232 * 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 236 * with @context. 237 */ 238 void qio_task_run_in_thread(QIOTask *task, 239 QIOTaskWorker worker, 240 gpointer opaque, 241 GDestroyNotify destroy, 242 GMainContext *context); 243 244 245 /** 246 * qio_task_wait_thread: 247 * @task: the task struct 248 * 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. 254 * 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. 260 * 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 265 * method completes. 266 */ 267 void qio_task_wait_thread(QIOTask *task); 268 269 270 /** 271 * qio_task_complete: 272 * @task: the task struct 273 * 274 * Invoke the completion callback for @task and 275 * then free its memory. 276 */ 277 void qio_task_complete(QIOTask *task); 278 279 280 /** 281 * qio_task_set_error: 282 * @task: the task struct 283 * @err: pointer to the error, or NULL 284 * 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. 293 */ 294 void qio_task_set_error(QIOTask *task, 295 Error *err); 296 297 298 /** 299 * qio_task_propagate_error: 300 * @task: the task struct 301 * @errp: pointer to a NULL-initialized error object 302 * 303 * Propagate the error associated with @task 304 * into @errp. 305 * 306 * Returns: true if an error was propagated, false otherwise 307 */ 308 bool qio_task_propagate_error(QIOTask *task, 309 Error **errp); 310 311 312 /** 313 * qio_task_set_result_pointer: 314 * @task: the task struct 315 * @result: pointer to the result data 316 * 317 * Associate an opaque result with the task, 318 * which can later be retrieved with the 319 * qio_task_get_result_pointer() method 320 * 321 */ 322 void qio_task_set_result_pointer(QIOTask *task, 323 gpointer result, 324 GDestroyNotify notify); 325 326 327 /** 328 * qio_task_get_result_pointer: 329 * @task: the task struct 330 * 331 * Retrieve the opaque result data associated 332 * with the task, if any. 333 * 334 * Returns: the task result, or NULL 335 */ 336 gpointer qio_task_get_result_pointer(QIOTask *task); 337 338 339 /** 340 * qio_task_get_source: 341 * @task: the task struct 342 * 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. 348 * 349 * Returns: the source object 350 */ 351 Object *qio_task_get_source(QIOTask *task); 352 353 #endif /* QIO_TASK_H */ 354