1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module glib.ThreadPool;
26 
27 private import glib.ConstructionException;
28 private import glib.ErrorG;
29 private import glib.GException;
30 private import glib.MemorySlice;
31 private import glib.c.functions;
32 public  import glib.c.types;
33 public  import gtkc.glibtypes;
34 private import gtkd.Loader;
35 
36 
37 /**
38  * The #GThreadPool struct represents a thread pool. It has three
39  * public read-only members, but the underlying struct is bigger,
40  * so you must not copy this struct.
41  */
42 public final class ThreadPool
43 {
44 	/** the main Gtk struct */
45 	protected GThreadPool* gThreadPool;
46 	protected bool ownedRef;
47 
48 	/** Get the main Gtk struct */
49 	public GThreadPool* getThreadPoolStruct(bool transferOwnership = false)
50 	{
51 		if (transferOwnership)
52 			ownedRef = false;
53 		return gThreadPool;
54 	}
55 
56 	/** the main Gtk struct as a void* */
57 	protected void* getStruct()
58 	{
59 		return cast(void*)gThreadPool;
60 	}
61 
62 	/**
63 	 * Sets our main struct and passes it to the parent class.
64 	 */
65 	public this (GThreadPool* gThreadPool, bool ownedRef = false)
66 	{
67 		this.gThreadPool = gThreadPool;
68 		this.ownedRef = ownedRef;
69 	}
70 
71 	~this ()
72 	{
73 		if ( Linker.isLoaded(LIBRARY_GLIB) && ownedRef )
74 			sliceFree(gThreadPool);
75 	}
76 
77 
78 	/**
79 	 * the function to execute in the threads of this pool
80 	 */
81 	public @property GFunc func()
82 	{
83 		return gThreadPool.func;
84 	}
85 
86 	/** Ditto */
87 	public @property void func(GFunc value)
88 	{
89 		gThreadPool.func = value;
90 	}
91 
92 	/**
93 	 * the user data for the threads of this pool
94 	 */
95 	public @property void* userData()
96 	{
97 		return gThreadPool.userData;
98 	}
99 
100 	/** Ditto */
101 	public @property void userData(void* value)
102 	{
103 		gThreadPool.userData = value;
104 	}
105 
106 	/**
107 	 * are all threads exclusive to this pool
108 	 */
109 	public @property bool exclusive()
110 	{
111 		return gThreadPool.exclusive != 0;
112 	}
113 
114 	/** Ditto */
115 	public @property void exclusive(bool value)
116 	{
117 		gThreadPool.exclusive = value;
118 	}
119 
120 	/**
121 	 * Frees all resources allocated for @pool.
122 	 *
123 	 * If @immediate is %TRUE, no new task is processed for @pool.
124 	 * Otherwise @pool is not freed before the last task is processed.
125 	 * Note however, that no thread of this pool is interrupted while
126 	 * processing a task. Instead at least all still running threads
127 	 * can finish their tasks before the @pool is freed.
128 	 *
129 	 * If @wait_ is %TRUE, the functions does not return before all
130 	 * tasks to be processed (dependent on @immediate, whether all
131 	 * or only the currently running) are ready.
132 	 * Otherwise the function returns immediately.
133 	 *
134 	 * After calling this function @pool must not be used anymore.
135 	 *
136 	 * Params:
137 	 *     immediate = should @pool shut down immediately?
138 	 *     wait = should the function wait for all tasks to be finished?
139 	 */
140 	public void free(bool immediate, bool wait)
141 	{
142 		g_thread_pool_free(gThreadPool, immediate, wait);
143 	}
144 
145 	/**
146 	 * Returns the maximal number of threads for @pool.
147 	 *
148 	 * Returns: the maximal number of threads
149 	 */
150 	public int getMaxThreads()
151 	{
152 		return g_thread_pool_get_max_threads(gThreadPool);
153 	}
154 
155 	/**
156 	 * Returns the number of threads currently running in @pool.
157 	 *
158 	 * Returns: the number of threads currently running
159 	 */
160 	public uint getNumThreads()
161 	{
162 		return g_thread_pool_get_num_threads(gThreadPool);
163 	}
164 
165 	/**
166 	 * Moves the item to the front of the queue of unprocessed
167 	 * items, so that it will be processed next.
168 	 *
169 	 * Params:
170 	 *     data = an unprocessed item in the pool
171 	 *
172 	 * Returns: %TRUE if the item was found and moved
173 	 *
174 	 * Since: 2.46
175 	 */
176 	public bool moveToFront(void* data)
177 	{
178 		return g_thread_pool_move_to_front(gThreadPool, data) != 0;
179 	}
180 
181 	/**
182 	 * Inserts @data into the list of tasks to be executed by @pool.
183 	 *
184 	 * When the number of currently running threads is lower than the
185 	 * maximal allowed number of threads, a new thread is started (or
186 	 * reused) with the properties given to g_thread_pool_new().
187 	 * Otherwise, @data stays in the queue until a thread in this pool
188 	 * finishes its previous task and processes @data.
189 	 *
190 	 * @error can be %NULL to ignore errors, or non-%NULL to report
191 	 * errors. An error can only occur when a new thread couldn't be
192 	 * created. In that case @data is simply appended to the queue of
193 	 * work to do.
194 	 *
195 	 * Before version 2.32, this function did not return a success status.
196 	 *
197 	 * Params:
198 	 *     data = a new task for @pool
199 	 *
200 	 * Returns: %TRUE on success, %FALSE if an error occurred
201 	 *
202 	 * Throws: GException on failure.
203 	 */
204 	public bool push(void* data)
205 	{
206 		GError* err = null;
207 
208 		auto p = g_thread_pool_push(gThreadPool, data, &err) != 0;
209 
210 		if (err !is null)
211 		{
212 			throw new GException( new ErrorG(err) );
213 		}
214 
215 		return p;
216 	}
217 
218 	/**
219 	 * Sets the maximal allowed number of threads for @pool.
220 	 * A value of -1 means that the maximal number of threads
221 	 * is unlimited. If @pool is an exclusive thread pool, setting
222 	 * the maximal number of threads to -1 is not allowed.
223 	 *
224 	 * Setting @max_threads to 0 means stopping all work for @pool.
225 	 * It is effectively frozen until @max_threads is set to a non-zero
226 	 * value again.
227 	 *
228 	 * A thread is never terminated while calling @func, as supplied by
229 	 * g_thread_pool_new(). Instead the maximal number of threads only
230 	 * has effect for the allocation of new threads in g_thread_pool_push().
231 	 * A new thread is allocated, whenever the number of currently
232 	 * running threads in @pool is smaller than the maximal number.
233 	 *
234 	 * @error can be %NULL to ignore errors, or non-%NULL to report
235 	 * errors. An error can only occur when a new thread couldn't be
236 	 * created.
237 	 *
238 	 * Before version 2.32, this function did not return a success status.
239 	 *
240 	 * Params:
241 	 *     maxThreads = a new maximal number of threads for @pool,
242 	 *         or -1 for unlimited
243 	 *
244 	 * Returns: %TRUE on success, %FALSE if an error occurred
245 	 *
246 	 * Throws: GException on failure.
247 	 */
248 	public bool setMaxThreads(int maxThreads)
249 	{
250 		GError* err = null;
251 
252 		auto p = g_thread_pool_set_max_threads(gThreadPool, maxThreads, &err) != 0;
253 
254 		if (err !is null)
255 		{
256 			throw new GException( new ErrorG(err) );
257 		}
258 
259 		return p;
260 	}
261 
262 	/**
263 	 * Sets the function used to sort the list of tasks. This allows the
264 	 * tasks to be processed by a priority determined by @func, and not
265 	 * just in the order in which they were added to the pool.
266 	 *
267 	 * Note, if the maximum number of threads is more than 1, the order
268 	 * that threads are executed cannot be guaranteed 100%. Threads are
269 	 * scheduled by the operating system and are executed at random. It
270 	 * cannot be assumed that threads are executed in the order they are
271 	 * created.
272 	 *
273 	 * Params:
274 	 *     func = the #GCompareDataFunc used to sort the list of tasks.
275 	 *         This function is passed two tasks. It should return
276 	 *         0 if the order in which they are handled does not matter,
277 	 *         a negative value if the first task should be processed before
278 	 *         the second or a positive value if the second task should be
279 	 *         processed first.
280 	 *     userData = user data passed to @func
281 	 *
282 	 * Since: 2.10
283 	 */
284 	public void setSortFunction(GCompareDataFunc func, void* userData)
285 	{
286 		g_thread_pool_set_sort_function(gThreadPool, func, userData);
287 	}
288 
289 	/**
290 	 * Returns the number of tasks still unprocessed in @pool.
291 	 *
292 	 * Returns: the number of unprocessed tasks
293 	 */
294 	public uint unprocessed()
295 	{
296 		return g_thread_pool_unprocessed(gThreadPool);
297 	}
298 
299 	/**
300 	 * This function will return the maximum @interval that a
301 	 * thread will wait in the thread pool for new tasks before
302 	 * being stopped.
303 	 *
304 	 * If this function returns 0, threads waiting in the thread
305 	 * pool for new work are not stopped.
306 	 *
307 	 * Returns: the maximum @interval (milliseconds) to wait
308 	 *     for new tasks in the thread pool before stopping the
309 	 *     thread
310 	 *
311 	 * Since: 2.10
312 	 */
313 	public static uint getMaxIdleTime()
314 	{
315 		return g_thread_pool_get_max_idle_time();
316 	}
317 
318 	/**
319 	 * Returns the maximal allowed number of unused threads.
320 	 *
321 	 * Returns: the maximal number of unused threads
322 	 */
323 	public static int getMaxUnusedThreads()
324 	{
325 		return g_thread_pool_get_max_unused_threads();
326 	}
327 
328 	/**
329 	 * Returns the number of currently unused threads.
330 	 *
331 	 * Returns: the number of currently unused threads
332 	 */
333 	public static uint getNumUnusedThreads()
334 	{
335 		return g_thread_pool_get_num_unused_threads();
336 	}
337 
338 	/**
339 	 * This function creates a new thread pool.
340 	 *
341 	 * Whenever you call g_thread_pool_push(), either a new thread is
342 	 * created or an unused one is reused. At most @max_threads threads
343 	 * are running concurrently for this thread pool. @max_threads = -1
344 	 * allows unlimited threads to be created for this thread pool. The
345 	 * newly created or reused thread now executes the function @func
346 	 * with the two arguments. The first one is the parameter to
347 	 * g_thread_pool_push() and the second one is @user_data.
348 	 *
349 	 * The parameter @exclusive determines whether the thread pool owns
350 	 * all threads exclusive or shares them with other thread pools.
351 	 * If @exclusive is %TRUE, @max_threads threads are started
352 	 * immediately and they will run exclusively for this thread pool
353 	 * until it is destroyed by g_thread_pool_free(). If @exclusive is
354 	 * %FALSE, threads are created when needed and shared between all
355 	 * non-exclusive thread pools. This implies that @max_threads may
356 	 * not be -1 for exclusive thread pools. Besides, exclusive thread
357 	 * pools are not affected by g_thread_pool_set_max_idle_time()
358 	 * since their threads are never considered idle and returned to the
359 	 * global pool.
360 	 *
361 	 * @error can be %NULL to ignore errors, or non-%NULL to report
362 	 * errors. An error can only occur when @exclusive is set to %TRUE
363 	 * and not all @max_threads threads could be created.
364 	 * See #GThreadError for possible errors that may occur.
365 	 * Note, even in case of error a valid #GThreadPool is returned.
366 	 *
367 	 * Params:
368 	 *     func = a function to execute in the threads of the new thread pool
369 	 *     userData = user data that is handed over to @func every time it
370 	 *         is called
371 	 *     maxThreads = the maximal number of threads to execute concurrently
372 	 *         in  the new thread pool, -1 means no limit
373 	 *     exclusive = should this thread pool be exclusive?
374 	 *
375 	 * Returns: the new #GThreadPool
376 	 *
377 	 * Throws: GException on failure.
378 	 * Throws: ConstructionException GTK+ fails to create the object.
379 	 */
380 	public this(GFunc func, void* userData, int maxThreads, bool exclusive)
381 	{
382 		GError* err = null;
383 
384 		auto p = g_thread_pool_new(func, userData, maxThreads, exclusive, &err);
385 
386 		if (err !is null)
387 		{
388 			throw new GException( new ErrorG(err) );
389 		}
390 
391 		if(p is null)
392 		{
393 			throw new ConstructionException("null returned by new");
394 		}
395 
396 		this(cast(GThreadPool*) p);
397 	}
398 
399 	/**
400 	 * This function will set the maximum @interval that a thread
401 	 * waiting in the pool for new tasks can be idle for before
402 	 * being stopped. This function is similar to calling
403 	 * g_thread_pool_stop_unused_threads() on a regular timeout,
404 	 * except this is done on a per thread basis.
405 	 *
406 	 * By setting @interval to 0, idle threads will not be stopped.
407 	 *
408 	 * The default value is 15000 (15 seconds).
409 	 *
410 	 * Params:
411 	 *     interval = the maximum @interval (in milliseconds)
412 	 *         a thread can be idle
413 	 *
414 	 * Since: 2.10
415 	 */
416 	public static void setMaxIdleTime(uint interval)
417 	{
418 		g_thread_pool_set_max_idle_time(interval);
419 	}
420 
421 	/**
422 	 * Sets the maximal number of unused threads to @max_threads.
423 	 * If @max_threads is -1, no limit is imposed on the number
424 	 * of unused threads.
425 	 *
426 	 * The default value is 2.
427 	 *
428 	 * Params:
429 	 *     maxThreads = maximal number of unused threads
430 	 */
431 	public static void setMaxUnusedThreads(int maxThreads)
432 	{
433 		g_thread_pool_set_max_unused_threads(maxThreads);
434 	}
435 
436 	/**
437 	 * Stops all currently unused threads. This does not change the
438 	 * maximal number of unused threads. This function can be used to
439 	 * regularly stop all unused threads e.g. from g_timeout_add().
440 	 */
441 	public static void stopUnusedThreads()
442 	{
443 		g_thread_pool_stop_unused_threads();
444 	}
445 }