Added GThreadPool documentation.

2001-04-03  Sebastian Wilhelmi  <wilhelmi@ira.uka.de>

	* glib/tmpl/thread_pools.sgml: Added GThreadPool documentation.

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 897388d..d0afa9a 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -5,6 +5,8 @@
 
        * glib/tmpl/threads.sgml: Updated.
 
+       * glib/tmpl/thread_pools.sgml: Added GThreadPool documentation.
+
 Mon Mar 26 14:20:36 2001  Owen Taylor  <otaylor@redhat.com>
 
        * glib/Makefile.am (SCAN_OPTIONS): Add --deprecated-guards

diff --git a/docs/reference/glib/tmpl/thread_pools.sgml b/docs/reference/glib/tmpl/thread_pools.sgml
index 5d4d0dd..01e103c 100644 (file)
--- a/docs/reference/glib/tmpl/thread_pools.sgml
+++ b/docs/reference/glib/tmpl/thread_pools.sgml
@@ -2,29 +2,76 @@
 Thread Pools
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Pools of threads to execute work concurrently
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+Sometimes you wish to asyncronously 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 to
+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>
 
 <!-- ##### STRUCT GThreadPool ##### -->
 <para>
-
+The #GThreadPool struct represents a thread pool. It has six public
+read-only members, but the underlying struct is bigger, so you must not copy
+this struct.
 </para>
 
-@thread_func: 
-@stack_size: 
-@bound: 
-@priority: 
-@exclusive: 
-@user_data: 
+@thread_func: the function to execute in the threads of this pool
+@stack_size: the stack size for the threads of this pool
+@bound: are the threads of this pool bound?
+@priority: the priority of the threads of this pool
+@exclusive: are all threads exclusive to this pool
+@user_data: the user data for the threads of this pool
 
 <!-- ##### FUNCTION g_thread_pool_new ##### -->
 <para>