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