GThreadPool: move docs from tmpl to .c

diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore
index 12d1162..4aaebc0 100644 (file)
--- 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 (file)
index df6baed..0000000
--- a/docs/reference/glib/tmpl/thread_pools.sgml
+++ /dev/null
@@ -1,202 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-Thread Pools
-
-<!-- ##### SECTION Short_Description ##### -->
-pools of threads to execute work concurrently
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-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.
-</para>
-
-<para>
-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.
-</para>
-
-<para>
-To create a new thread pool, you use g_thread_pool_new(). It is
-destroyed by g_thread_pool_free().
-</para>
-
-<para>
-If you want to execute a certain task within a thread pool, you call
-g_thread_pool_push().
-</para>
-
-<para>
-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().
-</para>
-
-<para>
-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().
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-<variablelist>
-
-<varlistentry>
-<term>#GThread</term>
-<listitem><para>GLib thread system.</para></listitem>
-</varlistentry>
-
-</variablelist>
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GThreadPool ##### -->
-<para>
-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.
-</para>
-
-@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
-
-<!-- ##### FUNCTION g_thread_pool_new ##### -->
-<para>
-
-</para>
-
-@func: 
-@user_data: 
-@max_threads: 
-@exclusive: 
-@error: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_thread_pool_push ##### -->
-<para>
-
-</para>
-
-@pool: 
-@data: 
-@error: 
-
-
-<!-- ##### FUNCTION g_thread_pool_set_max_threads ##### -->
-<para>
-
-</para>
-
-@pool: 
-@max_threads: 
-@error: 
-
-
-<!-- ##### FUNCTION g_thread_pool_get_max_threads ##### -->
-<para>
-
-</para>
-
-@pool: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_thread_pool_get_num_threads ##### -->
-<para>
-
-</para>
-
-@pool: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_thread_pool_unprocessed ##### -->
-<para>
-
-</para>
-
-@pool: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_thread_pool_free ##### -->
-<para>
-
-</para>
-
-@pool: 
-@immediate: 
-@wait_: 
-
-
-<!-- ##### FUNCTION g_thread_pool_set_max_unused_threads ##### -->
-<para>
-
-</para>
-
-@max_threads: 
-
-
-<!-- ##### FUNCTION g_thread_pool_get_max_unused_threads ##### -->
-<para>
-
-</para>
-
-@Returns: 
-
-
-<!-- ##### FUNCTION g_thread_pool_get_num_unused_threads ##### -->
-<para>
-
-</para>
-
-@Returns: 
-
-
-<!-- ##### FUNCTION g_thread_pool_stop_unused_threads ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### FUNCTION g_thread_pool_set_sort_function ##### -->
-<para>
-
-</para>
-
-@pool: 
-@func: 
-@user_data: 
-
-
-<!-- ##### FUNCTION g_thread_pool_set_max_idle_time ##### -->
-<para>
-
-</para>
-
-@interval: 
-
-
-<!-- ##### FUNCTION g_thread_pool_get_max_idle_time ##### -->
-<para>
-
-</para>
-
-@Returns: 
-
-

diff --git a/glib/gthreadpool.c b/glib/gthreadpool.c
index 2059a99..3ece1b4 100644 (file)
--- 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: <para> <variablelist> <varlistentry>
+ *            <term>#GThread</term> <listitem><para>GLib thread
+ *            system.</para></listitem> </varlistentry> </variablelist>
+ *            </para>
+ *
+ * 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;