thread_pools.sgml   [plain text]

<!-- ##### SECTION Title ##### -->
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>

@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>