From d0287599037fb2c0e8bfa9c6af8095a6cc973bc3 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 24 Sep 2023 23:34:39 -0400 Subject: [PATCH] docs: Drop the threadpool SECTION Move the contents to the GThreadPool struct docs. Helps: #3037 --- glib/gthreadpool.c | 66 ++++++++++++++++++---------------------------- 1 file changed, 26 insertions(+), 40 deletions(-) diff --git a/glib/gthreadpool.c b/glib/gthreadpool.c index c18de89d0..15e3737c2 100644 --- a/glib/gthreadpool.c +++ b/glib/gthreadpool.c @@ -37,43 +37,6 @@ #include "gtimer.h" #include "gutils.h" -/** - * SECTION:thread_pools - * @title: Thread Pools - * @short_description: pools of threads to execute work concurrently - * @see_also: #GThread - * - * Sometimes you wish to asynchronously fork out the execution of work - * and continue working in your own thread. If that will happen often, - * the overhead of starting and destroying a thread each time might be - * too high. In such cases reusing already started threads seems like a - * good idea. And it indeed is, but implementing this can be tedious - * and error-prone. - * - * Therefore GLib provides thread pools for your convenience. An added - * advantage is, that the threads can be shared between the different - * subsystems of your program, when they are using GLib. - * - * To create a new thread pool, you use g_thread_pool_new(). - * It is destroyed by g_thread_pool_free(). - * - * If you want to execute a certain task within a thread pool, - * you call g_thread_pool_push(). - * - * To get the current number of running threads you call - * g_thread_pool_get_num_threads(). To get the number of still - * unprocessed tasks you call g_thread_pool_unprocessed(). To control - * the maximal number of threads for a thread pool, you use - * g_thread_pool_get_max_threads() and g_thread_pool_set_max_threads(). - * - * Finally you can control the number of unused threads, that are kept - * alive by GLib for future use. The current number can be fetched with - * g_thread_pool_get_num_unused_threads(). The maximal number can be - * controlled by g_thread_pool_get_max_unused_threads() and - * g_thread_pool_set_max_unused_threads(). All currently unused threads - * can be stopped by calling g_thread_pool_stop_unused_threads(). - */ - #define DEBUG_MSG(x) /* #define DEBUG_MSG(args) g_printerr args ; g_printerr ("\n"); */ @@ -85,9 +48,32 @@ typedef struct _GRealThreadPool GRealThreadPool; * @user_data: the user data for the threads of this pool * @exclusive: are all threads exclusive to this pool * - * The #GThreadPool struct represents a thread pool. It has three - * public read-only members, but the underlying struct is bigger, - * so you must not copy this struct. + * The `GThreadPool` struct represents a thread pool. + * + * A thread pool is useful when you wish to asynchronously fork out the execution of work + * and continue working in your own thread. If that will happen often, the overhead of starting + * and destroying a thread each time might be too high. In such cases reusing already started + * threads seems like a good idea. And it indeed is, but implementing this can be tedious + * and error-prone. + * + * Therefore GLib provides thread pools for your convenience. An added advantage is, that the + * threads can be shared between the different subsystems of your program, when they are using GLib. + * + * To create a new thread pool, you use [method@GLib.ThreadPool.new]. + * It is destroyed by [method@GLib.ThreadPool.free]. + * + * If you want to execute a certain task within a thread pool, use [method@GLib.ThreadPool.push]. + * + * To get the current number of running threads you call [method@GLib.ThreadPool.get_num_threads]. + * To get the number of still unprocessed tasks you call [method@GLib.ThreadPool.unprocessed]. + * To control the maximum number of threads for a thread pool, you use + * [method@GLib.ThreadPool.get_max_threads]. and [method@GLib.ThreadPool.set_max_threads]. + * + * Finally you can control the number of unused threads, that are kept alive by GLib for future use. + * The current number can be fetched with [method@GLib.ThreadPool.get_num_unused_threads]. + * The maximum number can be controlled by [method@GLib.ThreadPool.get_max_unused_threads] and + * [method@GLib.ThreadPool.set_max_unused_threads]. All currently unused threads + * can be stopped by calling [method@GLib.ThreadPool.stop_unused_threads()]. */ struct _GRealThreadPool {