X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=gio%2Fgtask.c;h=51259bd54244c75c0878011ec59096c438447fbb;hb=2a53b4d0e2c98a14aedf31e38f0ad1fb2e8fe26f;hp=0a80c24b869248c5ae493805b4915256e41cb832;hpb=e261b9c0308495ef03a5171fec734323748b599d;p=platform%2Fupstream%2Fglib.git diff --git a/gio/gtask.c b/gio/gtask.c index 0a80c24..51259bd 100644 --- a/gio/gtask.c +++ b/gio/gtask.c @@ -13,9 +13,7 @@ * 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, write to the - * Free Software Foundation, Inc., 59 Temple Place, Suite 330, - * Boston, MA 02111-1307, USA. + * Public License along with this library; if not, see . */ #include "config.h" @@ -27,33 +25,32 @@ /** * SECTION:gtask - * @short_description: Cancellable synchronous or asynchronous task and result + * @short_description: Cancellable synchronous or asynchronous task + * and result * @include: gio/gio.h * @see_also: #GAsyncResult * - * - * A #GTask represents and manages a cancellable "task". - * - * - * Asynchronous operations - * - * The most common usage of #GTask is as a #GAsyncResult, to - * manage data during an asynchronous operation. You call - * g_task_new() in the "start" method, followed by - * g_task_set_task_data() and the like if you need to keep some - * additional data associated with the task, and then pass the - * task object around through your asynchronous operation. - * Eventually, you will call a method such as - * g_task_return_pointer() or g_task_return_error(), which will - * save the value you give it and then invoke the task's callback - * function (waiting until the next next iteration of the main - * loop first, if necessary). The caller will pass the #GTask back - * to the operation's finish function (as a #GAsyncResult), and - * you can use g_task_propagate_pointer() or the like to extract - * the return value. - * - * GTask as a GAsyncResult - * + * A #GTask represents and manages a cancellable "task". + * + * ## Asynchronous operations + * + * The most common usage of #GTask is as a #GAsyncResult, to + * manage data during an asynchronous operation. You call + * g_task_new() in the "start" method, followed by + * g_task_set_task_data() and the like if you need to keep some + * additional data associated with the task, and then pass the + * task object around through your asynchronous operation. + * Eventually, you will call a method such as + * g_task_return_pointer() or g_task_return_error(), which will + * save the value you give it and then invoke the task's callback + * function (waiting until the next iteration of the main + * loop first, if necessary). The caller will pass the #GTask back + * to the operation's finish function (as a #GAsyncResult), and + * you can use g_task_propagate_pointer() or the like to extract + * the return value. + * + * Here is an example for using GTask as a GAsyncResult: + * |[ * typedef struct { * CakeFrostingType frosting; * char *message; @@ -85,13 +82,13 @@ * if (!cake_decorate (cake, decoration->frosting, decoration->message, &error)) * { * g_object_unref (cake); - * /* g_task_return_error() takes ownership of error */ + * // g_task_return_error() takes ownership of error * g_task_return_error (task, error); * g_object_unref (task); * return; * } * - * g_task_return_pointer (result, cake, g_object_unref); + * g_task_return_pointer (task, cake, g_object_unref); * g_object_unref (task); * } * @@ -122,7 +119,7 @@ * cake = _baker_get_cached_cake (self, radius, flavor, frosting, message); * if (cake != NULL) * { - * /* _baker_get_cached_cake() returns a reffed cake */ + * // _baker_get_cached_cake() returns a reffed cake * g_task_return_pointer (task, cake, g_object_unref); * g_object_unref (task); * return; @@ -145,25 +142,22 @@ * * return g_task_propagate_pointer (G_TASK (result), error); * } - * - * - * - * - * Chained asynchronous operations - * - * #GTask also tries to simplify asynchronous operations that - * internally chain together several smaller asynchronous - * operations. g_task_get_cancellable(), g_task_get_context(), and - * g_task_get_priority() allow you to get back the task's - * #GCancellable, #GMainContext, and I/O priority when starting a new - * subtask, so you don't have to keep track of them yourself. - * g_task_attach_source() simplifies the case of waiting for a - * source to fire (automatically using the correct #GMainContext - * and priority). - * - * Chained asynchronous operations - * + * ]| + * + * ## Chained asynchronous operations + * + * #GTask also tries to simplify asynchronous operations that + * internally chain together several smaller asynchronous + * operations. g_task_get_cancellable(), g_task_get_context(), + * and g_task_get_priority() allow you to get back the task's + * #GCancellable, #GMainContext, and [I/O priority][io-priority] + * when starting a new subtask, so you don't have to keep track + * of them yourself. g_task_attach_source() simplifies the case + * of waiting for a source to fire (automatically using the correct + * #GMainContext and priority). + * + * Here is an example for chained asynchronous operations: + * |[ * typedef struct { * Cake *cake; * CakeFrostingType frosting; @@ -195,9 +189,8 @@ * return; * } * - * /* baking_data_free() will drop its ref on the cake, so - * * we have to take another here to give to the caller. - * */ + * // baking_data_free() will drop its ref on the cake, so we have to + * // take another here to give to the caller. * g_task_return_pointer (result, g_object_ref (cake), g_object_unref); * g_object_unref (task); * } @@ -231,8 +224,8 @@ * * bd->cake = cake; * - * /* Bail out now if the user has already cancelled */ - * if (g_task_return_error_if_cancelled (g_task_get_cancellable (task))) + * // Bail out now if the user has already cancelled + * if (g_task_return_error_if_cancelled (task)) * { * g_object_unref (task); * return; @@ -245,9 +238,8 @@ * GSource *source; * * source = cake_decorator_wait_source_new (cake); - * /* Attach @source to @task's GMainContext and have it call - * * decorator_ready() when it is ready. - * */ + * // Attach @source to @task's GMainContext and have it call + * // decorator_ready() when it is ready. * g_task_attach_source (task, source, * G_CALLBACK (decorator_ready)); * g_source_unref (source); @@ -288,19 +280,17 @@ * * return g_task_propagate_pointer (G_TASK (result), error); * } - * - * - * - * - * Asynchronous operations from synchronous ones - * - * You can use g_task_run_in_thread() to turn a synchronous - * operation into an asynchronous one, by running it in a thread - * which will then dispatch the result back to the caller's - * #GMainContext when it completes. - * - * g_task_run_in_thread() - * + * ]| + * + * ## Asynchronous operations from synchronous ones + * + * You can use g_task_run_in_thread() to turn a synchronous + * operation into an asynchronous one, by running it in a thread + * which will then dispatch the result back to the caller's + * #GMainContext when it completes. + * + * Running a task in a thread: + * |[ * typedef struct { * guint radius; * CakeFlavor flavor; @@ -356,6 +346,7 @@ * task = g_task_new (self, cancellable, callback, user_data); * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); * g_task_run_in_thread (task, bake_cake_thread); + * g_object_unref (task); * } * * Cake * @@ -367,26 +358,24 @@ * * return g_task_propagate_pointer (G_TASK (result), error); * } - * - * - * - * - * Adding cancellability to uncancellable tasks - * - * Finally, g_task_run_in_thread() and g_task_run_in_thread_sync() - * can be used to turn an uncancellable operation into a - * cancellable one. If you call g_task_set_return_on_cancel(), - * passing %TRUE, then if the task's #GCancellable is cancelled, - * it will return control back to the caller immediately, while - * allowing the task thread to continue running in the background - * (and simply discarding its result when it finally does finish). - * Provided that the task thread is careful about how it uses - * locks and other externally-visible resources, this allows you - * to make "GLib-friendly" asynchronous and cancellable - * synchronous variants of blocking APIs. - * - * g_task_set_return_on_cancel() - * + * ]| + * + * ## Adding cancellability to uncancellable tasks + * + * Finally, g_task_run_in_thread() and g_task_run_in_thread_sync() + * can be used to turn an uncancellable operation into a + * cancellable one. If you call g_task_set_return_on_cancel(), + * passing %TRUE, then if the task's #GCancellable is cancelled, + * it will return control back to the caller immediately, while + * allowing the task thread to continue running in the background + * (and simply discarding its result when it finally does finish). + * Provided that the task thread is careful about how it uses + * locks and other externally-visible resources, this allows you + * to make "GLib-friendly" asynchronous and cancellable + * synchronous variants of blocking APIs. + * + * Cancelling a task: + * |[ * static void * bake_cake_thread (GTask *task, * gpointer source_object, @@ -407,22 +396,20 @@ * return; * } * - * /* If the task has already been cancelled, then we don't - * * want to add the cake to the cake cache. Likewise, we don't - * * want to have the task get cancelled in the middle of - * * updating the cache. g_task_set_return_on_cancel() will - * * return %TRUE here if it managed to disable return-on-cancel, - * * or %FALSE if the task was cancelled before it could. - * */ + * // If the task has already been cancelled, then we don't want to add + * // the cake to the cake cache. Likewise, we don't want to have the + * // task get cancelled in the middle of updating the cache. + * // g_task_set_return_on_cancel() will return %TRUE here if it managed + * // to disable return-on-cancel, or %FALSE if the task was cancelled + * // before it could. * if (g_task_set_return_on_cancel (task, FALSE)) * { - * /* If the caller cancels at this point, their - * * GAsyncReadyCallback won't be invoked until we return, - * * so we don't have to worry that this code will run at - * * the same time as that code does. But if there were - * * other functions that might look at the cake cache, - * * then we'd probably need a GMutex here as well. - * */ + * // If the caller cancels at this point, their + * // GAsyncReadyCallback won't be invoked until we return, + * // so we don't have to worry that this code will run at + * // the same time as that code does. But if there were + * // other functions that might look at the cake cache, + * // then we'd probably need a GMutex here as well. * baker_add_cake_to_cache (baker, cake); * g_task_return_pointer (task, cake, g_object_unref); * } @@ -442,7 +429,8 @@ * GTask *task; * * cake_data = g_slice_new (CakeData); - * /* ... */ + * + * ... * * task = g_task_new (self, cancellable, callback, user_data); * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); @@ -464,7 +452,8 @@ * Cake *cake; * * cake_data = g_slice_new (CakeData); - * /* ... */ + * + * ... * * task = g_task_new (self, cancellable, NULL, NULL); * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); @@ -475,81 +464,63 @@ * g_object_unref (task); * return cake; * } - * - * - * - * - * Porting from <literal>GSimpleAsyncResult</literal> - * - * #GTask's API attempts to be simpler than #GSimpleAsyncResult's - * in several ways: - * - * - * - * You can save task-specific data with g_task_set_task_data(), and - * retrieve it later with g_task_get_task_data(). This replaces the - * abuse of g_simple_async_result_set_op_res_gpointer() for the same - * purpose with #GSimpleAsyncResult. - * - * - * In addition to the task data, #GTask also keeps track of the - * priority, #GCancellable, and - * #GMainContext associated with the task, so tasks that consist of - * a chain of simpler asynchronous operations will have easy access - * to those values when starting each sub-task. - * - * - * g_task_return_error_if_cancelled() provides simplified - * handling for cancellation. In addition, cancellation - * overrides any other #GTask return value by default, like - * #GSimpleAsyncResult does when - * g_simple_async_result_set_check_cancellable() is called. - * (You can use g_task_set_check_cancellable() to turn off that - * behavior.) On the other hand, g_task_run_in_thread() - * guarantees that it will always run your - * task_func, even if the task's #GCancellable - * is already cancelled before the task gets a chance to run; - * you can start your task_func with a - * g_task_return_error_if_cancelled() check if you need the - * old behavior. - * - * - * The "return" methods (eg, g_task_return_pointer()) - * automatically cause the task to be "completed" as well, and - * there is no need to worry about the "complete" vs "complete - * in idle" distinction. (#GTask automatically figures out - * whether the task's callback can be invoked directly, or - * if it needs to be sent to another #GMainContext, or delayed - * until the next iteration of the current #GMainContext.) - * - * - * The "finish" functions for #GTask-based operations are generally - * much simpler than #GSimpleAsyncResult ones, normally consisting - * of only a single call to g_task_propagate_pointer() or the like. - * Since g_task_propagate_pointer() "steals" the return value from - * the #GTask, it is not necessary to juggle pointers around to - * prevent it from being freed twice. - * - * - * With #GSimpleAsyncResult, it was common to call - * g_simple_async_result_propagate_error() from the - * _finish() wrapper function, and have - * virtual method implementations only deal with successful - * returns. This behavior is deprecated, because it makes it - * difficult for a subclass to chain to a parent class's async - * methods. Instead, the wrapper function should just be a - * simple wrapper, and the virtual method should call an - * appropriate g_task_propagate_ function. - * Note that wrapper methods can now use - * g_async_result_legacy_propagate_error() to do old-style - * #GSimpleAsyncResult error-returning behavior, and - * g_async_result_is_tagged() to check if a result is tagged as - * having come from the _async() wrapper - * function (for "short-circuit" results, such as when passing - * 0 to g_input_stream_read_async()). - * - * - * + * ]| + * + * ## Porting from GSimpleAsyncResult + * + * #GTask's API attempts to be simpler than #GSimpleAsyncResult's + * in several ways: + * - You can save task-specific data with g_task_set_task_data(), and + * retrieve it later with g_task_get_task_data(). This replaces the + * abuse of g_simple_async_result_set_op_res_gpointer() for the same + * purpose with #GSimpleAsyncResult. + * - In addition to the task data, #GTask also keeps track of the + * [priority][io-priority], #GCancellable, and + * #GMainContext associated with the task, so tasks that consist of + * a chain of simpler asynchronous operations will have easy access + * to those values when starting each sub-task. + * - g_task_return_error_if_cancelled() provides simplified + * handling for cancellation. In addition, cancellation + * overrides any other #GTask return value by default, like + * #GSimpleAsyncResult does when + * g_simple_async_result_set_check_cancellable() is called. + * (You can use g_task_set_check_cancellable() to turn off that + * behavior.) On the other hand, g_task_run_in_thread() + * guarantees that it will always run your + * `task_func`, even if the task's #GCancellable + * is already cancelled before the task gets a chance to run; + * you can start your `task_func` with a + * g_task_return_error_if_cancelled() check if you need the + * old behavior. + * - The "return" methods (eg, g_task_return_pointer()) + * automatically cause the task to be "completed" as well, and + * there is no need to worry about the "complete" vs "complete + * in idle" distinction. (#GTask automatically figures out + * whether the task's callback can be invoked directly, or + * if it needs to be sent to another #GMainContext, or delayed + * until the next iteration of the current #GMainContext.) + * - The "finish" functions for #GTask-based operations are generally + * much simpler than #GSimpleAsyncResult ones, normally consisting + * of only a single call to g_task_propagate_pointer() or the like. + * Since g_task_propagate_pointer() "steals" the return value from + * the #GTask, it is not necessary to juggle pointers around to + * prevent it from being freed twice. + * - With #GSimpleAsyncResult, it was common to call + * g_simple_async_result_propagate_error() from the + * `_finish()` wrapper function, and have + * virtual method implementations only deal with successful + * returns. This behavior is deprecated, because it makes it + * difficult for a subclass to chain to a parent class's async + * methods. Instead, the wrapper function should just be a + * simple wrapper, and the virtual method should call an + * appropriate `g_task_propagate_` function. + * Note that wrapper methods can now use + * g_async_result_legacy_propagate_error() to do old-style + * #GSimpleAsyncResult error-returning behavior, and + * g_async_result_is_tagged() to check if a result is tagged as + * having come from the `_async()` wrapper + * function (for "short-circuit" results, such as when passing + * 0 to g_input_stream_read_async()). */ /** @@ -569,7 +540,7 @@ struct _GTask { GDestroyNotify task_data_destroy; GMainContext *context; - guint64 creation_time; + gint64 creation_time; gint priority; GCancellable *cancellable; gboolean check_cancellable; @@ -584,6 +555,7 @@ struct _GTask { gboolean thread_cancelled; gboolean synchronous; gboolean thread_complete; + gboolean blocking_other_task; GError *error; union { @@ -613,6 +585,8 @@ G_DEFINE_TYPE_WITH_CODE (GTask, g_task, G_TYPE_OBJECT, g_task_thread_pool_init ();) static GThreadPool *task_pool; +static GMutex task_pool_mutex; +static GPrivate task_private = G_PRIVATE_INIT (NULL); static void g_task_init (GTask *task) @@ -637,6 +611,9 @@ g_task_finalize (GObject *object) if (task->result_destroy && task->result.pointer) task->result_destroy (task->result.pointer); + if (task->error) + g_error_free (task->error); + if (G_TASK_IS_THREADED (task)) { g_mutex_clear (&task->lock); @@ -655,9 +632,8 @@ g_task_finalize (GObject *object) * @callback_data: (closure): user data passed to @callback. * * Creates a #GTask acting on @source_object, which will eventually be - * used to invoke @callback in the current thread-default main - * context. + * used to invoke @callback in the current + * [thread-default main context][g-main-context-push-thread-default]. * * Call this in the "start" method of your asynchronous method, and * pass the #GTask around throughout the asynchronous operation. You @@ -804,8 +780,7 @@ g_task_set_task_data (GTask *task, /** * g_task_set_priority: * @task: the #GTask - * @priority: the priority - * of the request. + * @priority: the [priority][io-priority] of the request * * Sets @task's priority. If you do not call this, it will default to * %G_PRIORITY_DEFAULT. @@ -982,9 +957,9 @@ g_task_ref_source_object (GAsyncResult *res) * g_task_get_task_data: * @task: a #GTask * - * Gets @task's task_data. + * Gets @task's `task_data`. * - * Returns: (transfer none): @task's task_data. + * Returns: (transfer none): @task's `task_data`. * * Since: 2.36 */ @@ -1015,9 +990,9 @@ g_task_get_priority (GTask *task) * @task: a #GTask * * Gets the #GMainContext that @task will return its result in (that - * is, the context that was the thread-default main - * context at the point when @task was created). + * is, the context that was the + * [thread-default main context][g-main-context-push-thread-default] + * at the point when @task was created). * * This will always return a non-%NULL value, even if the task's * context is the default #GMainContext. @@ -1084,7 +1059,7 @@ g_task_get_return_on_cancel (GTask *task) * * Gets @task's source tag. See g_task_set_source_tag(). * - * Return value: (transfer none): @task's source tag + * Returns: (transfer none): @task's source tag * * Since: 2.36 */ @@ -1161,6 +1136,7 @@ g_task_return (GTask *task, /* Otherwise, complete in the next iteration */ source = g_idle_source_new (); g_task_attach_source (task, source, complete_in_idle_cb); + g_source_set_name (source, "[gio] complete_in_idle_cb"); g_source_unref (source); } @@ -1185,8 +1161,8 @@ g_task_return (GTask *task, * g_task_set_return_on_cancel() for more details. * * Other than in that case, @task will be completed when the - * #GTaskThreadFunc returns, not when it calls - * a g_task_return_ function. + * #GTaskThreadFunc returns, not when it calls a + * `g_task_return_` function. * * Since: 2.36 */ @@ -1208,6 +1184,15 @@ g_task_thread_complete (GTask *task) } task->thread_complete = TRUE; + + if (task->blocking_other_task) + { + g_mutex_lock (&task_pool_mutex); + g_thread_pool_set_max_threads (task_pool, + g_thread_pool_get_max_threads (task_pool) - 1, + NULL); + g_mutex_unlock (&task_pool_mutex); + } g_mutex_unlock (&task->lock); if (task->cancellable) @@ -1225,9 +1210,13 @@ g_task_thread_pool_thread (gpointer thread_data, { GTask *task = thread_data; + g_private_set (&task_private, task); + task->task_func (task, task->source_object, task->task_data, task->cancellable); g_task_thread_complete (task); + + g_private_set (&task_private, NULL); g_object_unref (task); } @@ -1285,15 +1274,33 @@ g_task_start_task_thread (GTask *task, return; } + /* This introduces a reference count loop between the GTask and + * GCancellable, but is necessary to avoid a race on finalising the GTask + * between task_thread_cancelled() (in one thread) and + * g_task_thread_complete() (in another). + * + * Accordingly, the signal handler *must* be removed once the task has + * completed. + */ g_signal_connect_data (task->cancellable, "cancelled", G_CALLBACK (task_thread_cancelled), g_object_ref (task), task_thread_cancelled_disconnect_notify, 0); } - g_thread_pool_push (task_pool, g_object_ref (task), &task->error); - if (task->error) - task->thread_complete = TRUE; + g_thread_pool_push (task_pool, g_object_ref (task), NULL); + if (g_private_get (&task_private)) + { + /* This thread is being spawned from another GTask thread, so + * bump up max-threads so we don't starve. + */ + g_mutex_lock (&task_pool_mutex); + if (g_thread_pool_set_max_threads (task_pool, + g_thread_pool_get_max_threads (task_pool) + 1, + NULL)) + task->blocking_other_task = TRUE; + g_mutex_unlock (&task_pool_mutex); + } } /** @@ -1345,7 +1352,7 @@ g_task_run_in_thread (GTask *task, * See #GTaskThreadFunc for more details about how @task_func is handled. * * Normally this is used with tasks created with a %NULL - * callback, but note that even if the task does + * `callback`, but note that even if the task does * have a callback, it will not be invoked when @task_func returns. * * Since: 2.36 @@ -1376,10 +1383,8 @@ g_task_run_in_thread_sync (GTask *task, * * A utility function for dealing with async operations where you need * to wait for a #GSource to trigger. Attaches @source to @task's - * #GMainContext with @task's priority, and sets @source's callback - * to @callback, with @task as the callback's - * user_data. + * #GMainContext with @task's [priority][io-priority], and sets @source's + * callback to @callback, with @task as the callback's `user_data`. * * This takes a reference on @task until @source is destroyed. * @@ -1665,7 +1670,7 @@ g_task_return_new_error (GTask *task, * g_task_return_pointer() for more discussion of exactly what this * means). * - * Return value: %TRUE if @task has been cancelled, %FALSE if not + * Returns: %TRUE if @task has been cancelled, %FALSE if not * * Since: 2.36 */ @@ -1723,7 +1728,7 @@ g_task_had_error (GTask *task) * source object (or that @source_object is %NULL and @result has no * source object). This can be used in g_return_if_fail() checks. * - * Return value: %TRUE if @result and @source_object are valid, %FALSE + * Returns: %TRUE if @result and @source_object are valid, %FALSE * if not * * Since: 2.36 @@ -1747,12 +1752,19 @@ g_task_compare_priority (gconstpointer a, const GTask *tb = b; gboolean a_cancelled, b_cancelled; + /* Tasks that are causing other tasks to block have higher + * priority. + */ + if (ta->blocking_other_task && !tb->blocking_other_task) + return -1; + else if (tb->blocking_other_task && !ta->blocking_other_task) + return 1; + + /* Let already-cancelled tasks finish right away */ a_cancelled = (ta->check_cancellable && g_cancellable_is_cancelled (ta->cancellable)); b_cancelled = (tb->check_cancellable && g_cancellable_is_cancelled (tb->cancellable)); - - /* Let already-cancelled tasks finish right away */ if (a_cancelled && !b_cancelled) return -1; else if (b_cancelled && !a_cancelled) @@ -1766,7 +1778,7 @@ static void g_task_thread_pool_init (void) { task_pool = g_thread_pool_new (g_task_thread_pool_thread, NULL, - 100, FALSE, NULL); + 10, FALSE, NULL); g_assert (task_pool != NULL); g_thread_pool_set_sort_function (task_pool, g_task_compare_priority, NULL);