[glib] GThreadPool: move docs from tmpl to .c

[Ryan Lortie <ryanl src gnome org>]

commit d81506a154ba387e339dfb5ff6acddac1e4866c5
Author: Ryan Lortie <desrt desrt ca>
Date:   Sun Jan 31 00:18:09 2010 -0500

    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(-)
---
diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore
index 12d1162..4aaebc0 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/glib/gthreadpool.c b/glib/gthreadpool.c
index 2059a99..3ece1b4 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: <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;