From d81506a154ba387e339dfb5ff6acddac1e4866c5 Mon Sep 17 00:00:00 2001 From: Ryan Lortie Date: Sun, 31 Jan 2010 00:18:09 -0500 Subject: [PATCH] GThreadPool: move docs from tmpl to .c --- docs/reference/glib/tmpl/.gitignore | 1 + docs/reference/glib/tmpl/thread_pools.sgml | 202 --------------------- glib/gthreadpool.c | 50 +++++ 3 files changed, 51 insertions(+), 202 deletions(-) delete mode 100644 docs/reference/glib/tmpl/thread_pools.sgml diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore index 12d1162bd..4aaebc064 100644 --- a/docs/reference/glib/tmpl/.gitignore +++ b/docs/reference/glib/tmpl/.gitignore @@ -18,5 +18,6 @@ relations.sgml sequence.sgml shell.sgml string_chunks.sgml +thread_pools.sgml threads.sgml timers.sgml diff --git a/docs/reference/glib/tmpl/thread_pools.sgml b/docs/reference/glib/tmpl/thread_pools.sgml deleted file mode 100644 index df6baed0d..000000000 --- a/docs/reference/glib/tmpl/thread_pools.sgml +++ /dev/null @@ -1,202 +0,0 @@ - -Thread Pools - - -pools of threads to execute work concurrently - - - -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(). - - - - - - - -#GThread -GLib thread system. - - - - - - - - - - -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. - - -@func: the function to execute in the threads of this pool -@user_data: the user data for the threads of this pool -@exclusive: are all threads exclusive to this pool - - - - - - -@func: -@user_data: -@max_threads: -@exclusive: -@error: -@Returns: - - - - - - - -@pool: -@data: -@error: - - - - - - - -@pool: -@max_threads: -@error: - - - - - - - -@pool: -@Returns: - - - - - - - -@pool: -@Returns: - - - - - - - -@pool: -@Returns: - - - - - - - -@pool: -@immediate: -@wait_: - - - - - - - -@max_threads: - - - - - - - -@Returns: - - - - - - - -@Returns: - - - - - - - - - - - - - - -@pool: -@func: -@user_data: - - - - - - - -@interval: - - - - - - - -@Returns: - - diff --git a/glib/gthreadpool.c b/glib/gthreadpool.c index 2059a999d..3ece1b445 100644 --- a/glib/gthreadpool.c +++ b/glib/gthreadpool.c @@ -29,11 +29,61 @@ #include "glib.h" #include "galias.h" +/** + * SECTION: thread_pools + * @title: Thread Pools + * @short_description: pools of threads to execute work concurrently + * @see_also: + * #GThread GLib thread + * system. + * + * + * 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"); */ typedef struct _GRealThreadPool GRealThreadPool; +/** + * GThreadPool: + * @func: the function to execute in the threads of this pool + * @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. + **/ struct _GRealThreadPool { GThreadPool pool;