• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<!-- ##### SECTION Title ##### -->
2Thread Pools
3
4<!-- ##### SECTION Short_Description ##### -->
5pools of threads to execute work concurrently
6
7<!-- ##### SECTION Long_Description ##### -->
8<para>
9Sometimes you wish to asynchronously fork out the execution of work and
10continue working in your own thread. If that will happen often, the
11overhead of starting and destroying a thread each time might be too
12high. In such cases reusing already started threads seems like a good
13idea. And it indeed is, but implementing this can be tedious and
14error-prone.
15</para>
16
17<para>
18Therefore GLib provides thread pools for your convenience. An added
19advantage is, that the threads can be shared between the different
20subsystems of your program, when they are using GLib.
21</para>
22
23<para>
24To create a new thread pool, you use g_thread_pool_new(). It is
25destroyed by g_thread_pool_free().
26</para>
27
28<para>
29If you want to execute a certain task within a thread pool, you call
30g_thread_pool_push().
31</para>
32
33<para>
34To get the current number of running threads you call
35g_thread_pool_get_num_threads(). To get the number of still
36unprocessed tasks you call g_thread_pool_unprocessed(). To control the
37maximal number of threads for a thread pool, you use
38g_thread_pool_get_max_threads() and g_thread_pool_set_max_threads().
39</para>
40
41<para>
42Finally you can control the number of unused threads, that are kept
43alive by GLib for future use. The current number can be fetched with
44g_thread_pool_get_num_unused_threads(). The maximal number can be
45controlled by g_thread_pool_get_max_unused_threads() and
46g_thread_pool_set_max_unused_threads(). All currently unused threads
47can be stopped by calling g_thread_pool_stop_unused_threads().
48</para>
49
50<!-- ##### SECTION See_Also ##### -->
51<para>
52<variablelist>
53
54<varlistentry>
55<term>#GThread</term>
56<listitem><para>GLib thread system.</para></listitem>
57</varlistentry>
58
59</variablelist>
60</para>
61
62<!-- ##### SECTION Stability_Level ##### -->
63
64
65<!-- ##### STRUCT GThreadPool ##### -->
66<para>
67The #GThreadPool struct represents a thread pool. It has three public
68read-only members, but the underlying struct is bigger, so you must not
69copy this struct.
70</para>
71
72@func: the function to execute in the threads of this pool
73@user_data: the user data for the threads of this pool
74@exclusive: are all threads exclusive to this pool
75
76<!-- ##### FUNCTION g_thread_pool_new ##### -->
77<para>
78
79</para>
80
81@func:
82@user_data:
83@max_threads:
84@exclusive:
85@error:
86@Returns:
87
88
89<!-- ##### FUNCTION g_thread_pool_push ##### -->
90<para>
91
92</para>
93
94@pool:
95@data:
96@error:
97
98
99<!-- ##### FUNCTION g_thread_pool_set_max_threads ##### -->
100<para>
101
102</para>
103
104@pool:
105@max_threads:
106@error:
107
108
109<!-- ##### FUNCTION g_thread_pool_get_max_threads ##### -->
110<para>
111
112</para>
113
114@pool:
115@Returns:
116
117
118<!-- ##### FUNCTION g_thread_pool_get_num_threads ##### -->
119<para>
120
121</para>
122
123@pool:
124@Returns:
125
126
127<!-- ##### FUNCTION g_thread_pool_unprocessed ##### -->
128<para>
129
130</para>
131
132@pool:
133@Returns:
134
135
136<!-- ##### FUNCTION g_thread_pool_free ##### -->
137<para>
138
139</para>
140
141@pool:
142@immediate:
143@wait_:
144
145
146<!-- ##### FUNCTION g_thread_pool_set_max_unused_threads ##### -->
147<para>
148
149</para>
150
151@max_threads:
152
153
154<!-- ##### FUNCTION g_thread_pool_get_max_unused_threads ##### -->
155<para>
156
157</para>
158
159@Returns:
160
161
162<!-- ##### FUNCTION g_thread_pool_get_num_unused_threads ##### -->
163<para>
164
165</para>
166
167@Returns:
168
169
170<!-- ##### FUNCTION g_thread_pool_stop_unused_threads ##### -->
171<para>
172
173</para>
174
175
176
177<!-- ##### FUNCTION g_thread_pool_set_sort_function ##### -->
178<para>
179
180</para>
181
182@pool:
183@func:
184@user_data:
185
186
187<!-- ##### FUNCTION g_thread_pool_set_max_idle_time ##### -->
188<para>
189
190</para>
191
192@interval:
193
194
195<!-- ##### FUNCTION g_thread_pool_get_max_idle_time ##### -->
196<para>
197
198</para>
199
200@Returns:
201
202
203