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.Thread;
26 
27 private import glib.ConstructionException;
28 private import glib.ErrorG;
29 private import glib.GException;
30 private import glib.Str;
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 #GThread struct represents a running thread. This struct
39  * is returned by g_thread_new() or g_thread_try_new(). You can
40  * obtain the #GThread struct representing the current thread by
41  * calling g_thread_self().
42  * 
43  * GThread is refcounted, see g_thread_ref() and g_thread_unref().
44  * The thread represented by it holds a reference while it is running,
45  * and g_thread_join() consumes the reference that it is given, so
46  * it is normally not necessary to manage GThread references
47  * explicitly.
48  * 
49  * The structure is opaque -- none of its fields may be directly
50  * accessed.
51  */
52 public class Thread
53 {
54 	/** the main Gtk struct */
55 	protected GThread* gThread;
56 	protected bool ownedRef;
57 
58 	/** Get the main Gtk struct */
59 	public GThread* getThreadStruct(bool transferOwnership = false)
60 	{
61 		if (transferOwnership)
62 			ownedRef = false;
63 		return gThread;
64 	}
65 
66 	/** the main Gtk struct as a void* */
67 	protected void* getStruct()
68 	{
69 		return cast(void*)gThread;
70 	}
71 
72 	/**
73 	 * Sets our main struct and passes it to the parent class.
74 	 */
75 	public this (GThread* gThread, bool ownedRef = false)
76 	{
77 		this.gThread = gThread;
78 		this.ownedRef = ownedRef;
79 	}
80 
81 	~this ()
82 	{
83 		if ( Linker.isLoaded(LIBRARY_GLIB) && ownedRef )
84 			g_thread_unref(gThread);
85 	}
86 
87 
88 	/**
89 	 * This function is the same as g_thread_new() except that
90 	 * it allows for the possibility of failure.
91 	 *
92 	 * If a thread can not be created (due to resource limits),
93 	 * @error is set and %NULL is returned.
94 	 *
95 	 * Params:
96 	 *     name = an (optional) name for the new thread
97 	 *     func = a function to execute in the new thread
98 	 *     data = an argument to supply to the new thread
99 	 *
100 	 * Returns: the new #GThread, or %NULL if an error occurred
101 	 *
102 	 * Since: 2.32
103 	 *
104 	 * Throws: GException on failure.
105 	 * Throws: ConstructionException GTK+ fails to create the object.
106 	 */
107 	public this(string name, GThreadFunc func, void* data)
108 	{
109 		GError* err = null;
110 
111 		auto p = g_thread_try_new(Str.toStringz(name), func, data, &err);
112 
113 		if (err !is null)
114 		{
115 			throw new GException( new ErrorG(err) );
116 		}
117 
118 		if(p is null)
119 		{
120 			throw new ConstructionException("null returned by try_new");
121 		}
122 
123 		this(cast(GThread*) p);
124 	}
125 
126 	/**
127 	 * Waits until @thread finishes, i.e. the function @func, as
128 	 * given to g_thread_new(), returns or g_thread_exit() is called.
129 	 * If @thread has already terminated, then g_thread_join()
130 	 * returns immediately.
131 	 *
132 	 * Any thread can wait for any other thread by calling g_thread_join(),
133 	 * not just its 'creator'. Calling g_thread_join() from multiple threads
134 	 * for the same @thread leads to undefined behaviour.
135 	 *
136 	 * The value returned by @func or given to g_thread_exit() is
137 	 * returned by this function.
138 	 *
139 	 * g_thread_join() consumes the reference to the passed-in @thread.
140 	 * This will usually cause the #GThread struct and associated resources
141 	 * to be freed. Use g_thread_ref() to obtain an extra reference if you
142 	 * want to keep the GThread alive beyond the g_thread_join() call.
143 	 *
144 	 * Returns: the return value of the thread
145 	 */
146 	public void* join()
147 	{
148 		return g_thread_join(gThread);
149 	}
150 
151 	/**
152 	 * Increase the reference count on @thread.
153 	 *
154 	 * Returns: a new reference to @thread
155 	 *
156 	 * Since: 2.32
157 	 */
158 	public Thread doref()
159 	{
160 		auto p = g_thread_ref(gThread);
161 
162 		if(p is null)
163 		{
164 			return null;
165 		}
166 
167 		return new Thread(cast(GThread*) p, true);
168 	}
169 
170 	/**
171 	 * Decrease the reference count on @thread, possibly freeing all
172 	 * resources associated with it.
173 	 *
174 	 * Note that each thread holds a reference to its #GThread while
175 	 * it is running, so it is safe to drop your own reference to it
176 	 * if you don't need it anymore.
177 	 *
178 	 * Since: 2.32
179 	 */
180 	public void unref()
181 	{
182 		g_thread_unref(gThread);
183 	}
184 
185 	/** */
186 	public static GQuark errorQuark()
187 	{
188 		return g_thread_error_quark();
189 	}
190 
191 	/**
192 	 * Terminates the current thread.
193 	 *
194 	 * If another thread is waiting for us using g_thread_join() then the
195 	 * waiting thread will be woken up and get @retval as the return value
196 	 * of g_thread_join().
197 	 *
198 	 * Calling g_thread_exit() with a parameter @retval is equivalent to
199 	 * returning @retval from the function @func, as given to g_thread_new().
200 	 *
201 	 * You must only call g_thread_exit() from a thread that you created
202 	 * yourself with g_thread_new() or related APIs. You must not call
203 	 * this function from a thread created with another threading library
204 	 * or or from within a #GThreadPool.
205 	 *
206 	 * Params:
207 	 *     retval = the return value of this thread
208 	 */
209 	public static void exit(void* retval)
210 	{
211 		g_thread_exit(retval);
212 	}
213 
214 	/**
215 	 * This function returns the #GThread corresponding to the
216 	 * current thread. Note that this function does not increase
217 	 * the reference count of the returned struct.
218 	 *
219 	 * This function will return a #GThread even for threads that
220 	 * were not created by GLib (i.e. those created by other threading
221 	 * APIs). This may be useful for thread identification purposes
222 	 * (i.e. comparisons) but you must not use GLib functions (such
223 	 * as g_thread_join()) on these threads.
224 	 *
225 	 * Returns: the #GThread representing the current thread
226 	 */
227 	public static Thread self()
228 	{
229 		auto p = g_thread_self();
230 
231 		if(p is null)
232 		{
233 			return null;
234 		}
235 
236 		return new Thread(cast(GThread*) p, true);
237 	}
238 
239 	/**
240 	 * Causes the calling thread to voluntarily relinquish the CPU, so
241 	 * that other threads can run.
242 	 *
243 	 * This function is often used as a method to make busy wait less evil.
244 	 */
245 	public static void yield()
246 	{
247 		g_thread_yield();
248 	}
249 
250 	/**
251 	 * Sets the indicated @lock_bit in @address.  If the bit is already
252 	 * set, this call will block until g_bit_unlock() unsets the
253 	 * corresponding bit.
254 	 *
255 	 * Attempting to lock on two different bits within the same integer is
256 	 * not supported and will very probably cause deadlocks.
257 	 *
258 	 * The value of the bit that is set is (1u << @bit).  If @bit is not
259 	 * between 0 and 31 then the result is undefined.
260 	 *
261 	 * This function accesses @address atomically.  All other accesses to
262 	 * @address must be atomic in order for this function to work
263 	 * reliably.
264 	 *
265 	 * Params:
266 	 *     address = a pointer to an integer
267 	 *     lockBit = a bit value between 0 and 31
268 	 *
269 	 * Since: 2.24
270 	 */
271 	public static void bitLock(int* address, int lockBit)
272 	{
273 		g_bit_lock(address, lockBit);
274 	}
275 
276 	/**
277 	 * Sets the indicated @lock_bit in @address, returning %TRUE if
278 	 * successful.  If the bit is already set, returns %FALSE immediately.
279 	 *
280 	 * Attempting to lock on two different bits within the same integer is
281 	 * not supported.
282 	 *
283 	 * The value of the bit that is set is (1u << @bit).  If @bit is not
284 	 * between 0 and 31 then the result is undefined.
285 	 *
286 	 * This function accesses @address atomically.  All other accesses to
287 	 * @address must be atomic in order for this function to work
288 	 * reliably.
289 	 *
290 	 * Params:
291 	 *     address = a pointer to an integer
292 	 *     lockBit = a bit value between 0 and 31
293 	 *
294 	 * Returns: %TRUE if the lock was acquired
295 	 *
296 	 * Since: 2.24
297 	 */
298 	public static bool bitTrylock(int* address, int lockBit)
299 	{
300 		return g_bit_trylock(address, lockBit) != 0;
301 	}
302 
303 	/**
304 	 * Clears the indicated @lock_bit in @address.  If another thread is
305 	 * currently blocked in g_bit_lock() on this same bit then it will be
306 	 * woken up.
307 	 *
308 	 * This function accesses @address atomically.  All other accesses to
309 	 * @address must be atomic in order for this function to work
310 	 * reliably.
311 	 *
312 	 * Params:
313 	 *     address = a pointer to an integer
314 	 *     lockBit = a bit value between 0 and 31
315 	 *
316 	 * Since: 2.24
317 	 */
318 	public static void bitUnlock(int* address, int lockBit)
319 	{
320 		g_bit_unlock(address, lockBit);
321 	}
322 
323 	/**
324 	 * Determine the approximate number of threads that the system will
325 	 * schedule simultaneously for this process.  This is intended to be
326 	 * used as a parameter to g_thread_pool_new() for CPU bound tasks and
327 	 * similar cases.
328 	 *
329 	 * Returns: Number of schedulable threads, always greater than 0
330 	 *
331 	 * Since: 2.36
332 	 */
333 	public static uint getNumProcessors()
334 	{
335 		return g_get_num_processors();
336 	}
337 
338 	/**
339 	 * This is equivalent to g_bit_lock, but working on pointers (or other
340 	 * pointer-sized values).
341 	 *
342 	 * For portability reasons, you may only lock on the bottom 32 bits of
343 	 * the pointer.
344 	 *
345 	 * Params:
346 	 *     address = a pointer to a #gpointer-sized value
347 	 *     lockBit = a bit value between 0 and 31
348 	 *
349 	 * Since: 2.30
350 	 */
351 	public static void pointerBitLock(void* address, int lockBit)
352 	{
353 		g_pointer_bit_lock(address, lockBit);
354 	}
355 
356 	/**
357 	 * This is equivalent to g_bit_trylock, but working on pointers (or
358 	 * other pointer-sized values).
359 	 *
360 	 * For portability reasons, you may only lock on the bottom 32 bits of
361 	 * the pointer.
362 	 *
363 	 * Params:
364 	 *     address = a pointer to a #gpointer-sized value
365 	 *     lockBit = a bit value between 0 and 31
366 	 *
367 	 * Returns: %TRUE if the lock was acquired
368 	 *
369 	 * Since: 2.30
370 	 */
371 	public static bool pointerBitTrylock(void* address, int lockBit)
372 	{
373 		return g_pointer_bit_trylock(address, lockBit) != 0;
374 	}
375 
376 	/**
377 	 * This is equivalent to g_bit_unlock, but working on pointers (or other
378 	 * pointer-sized values).
379 	 *
380 	 * For portability reasons, you may only lock on the bottom 32 bits of
381 	 * the pointer.
382 	 *
383 	 * Params:
384 	 *     address = a pointer to a #gpointer-sized value
385 	 *     lockBit = a bit value between 0 and 31
386 	 *
387 	 * Since: 2.30
388 	 */
389 	public static void pointerBitUnlock(void* address, int lockBit)
390 	{
391 		g_pointer_bit_unlock(address, lockBit);
392 	}
393 }