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 	alias doref = ref_;
152 	/**
153 	 * Increase the reference count on @thread.
154 	 *
155 	 * Returns: a new reference to @thread
156 	 *
157 	 * Since: 2.32
158 	 */
159 	public Thread ref_()
160 	{
161 		auto p = g_thread_ref(gThread);
162 
163 		if(p is null)
164 		{
165 			return null;
166 		}
167 
168 		return new Thread(cast(GThread*) p, true);
169 	}
170 
171 	/**
172 	 * Decrease the reference count on @thread, possibly freeing all
173 	 * resources associated with it.
174 	 *
175 	 * Note that each thread holds a reference to its #GThread while
176 	 * it is running, so it is safe to drop your own reference to it
177 	 * if you don't need it anymore.
178 	 *
179 	 * Since: 2.32
180 	 */
181 	public void unref()
182 	{
183 		g_thread_unref(gThread);
184 	}
185 
186 	/** */
187 	public static GQuark errorQuark()
188 	{
189 		return g_thread_error_quark();
190 	}
191 
192 	/**
193 	 * Terminates the current thread.
194 	 *
195 	 * If another thread is waiting for us using g_thread_join() then the
196 	 * waiting thread will be woken up and get @retval as the return value
197 	 * of g_thread_join().
198 	 *
199 	 * Calling g_thread_exit() with a parameter @retval is equivalent to
200 	 * returning @retval from the function @func, as given to g_thread_new().
201 	 *
202 	 * You must only call g_thread_exit() from a thread that you created
203 	 * yourself with g_thread_new() or related APIs. You must not call
204 	 * this function from a thread created with another threading library
205 	 * or or from within a #GThreadPool.
206 	 *
207 	 * Params:
208 	 *     retval = the return value of this thread
209 	 */
210 	public static void exit(void* retval)
211 	{
212 		g_thread_exit(retval);
213 	}
214 
215 	/**
216 	 * This function returns the #GThread corresponding to the
217 	 * current thread. Note that this function does not increase
218 	 * the reference count of the returned struct.
219 	 *
220 	 * This function will return a #GThread even for threads that
221 	 * were not created by GLib (i.e. those created by other threading
222 	 * APIs). This may be useful for thread identification purposes
223 	 * (i.e. comparisons) but you must not use GLib functions (such
224 	 * as g_thread_join()) on these threads.
225 	 *
226 	 * Returns: the #GThread representing the current thread
227 	 */
228 	public static Thread self()
229 	{
230 		auto p = g_thread_self();
231 
232 		if(p is null)
233 		{
234 			return null;
235 		}
236 
237 		return new Thread(cast(GThread*) p, true);
238 	}
239 
240 	/**
241 	 * Causes the calling thread to voluntarily relinquish the CPU, so
242 	 * that other threads can run.
243 	 *
244 	 * This function is often used as a method to make busy wait less evil.
245 	 */
246 	public static void yield()
247 	{
248 		g_thread_yield();
249 	}
250 
251 	/**
252 	 * Sets the indicated @lock_bit in @address.  If the bit is already
253 	 * set, this call will block until g_bit_unlock() unsets the
254 	 * corresponding bit.
255 	 *
256 	 * Attempting to lock on two different bits within the same integer is
257 	 * not supported and will very probably cause deadlocks.
258 	 *
259 	 * The value of the bit that is set is (1u << @bit).  If @bit is not
260 	 * between 0 and 31 then the result is undefined.
261 	 *
262 	 * This function accesses @address atomically.  All other accesses to
263 	 * @address must be atomic in order for this function to work
264 	 * reliably.
265 	 *
266 	 * Params:
267 	 *     address = a pointer to an integer
268 	 *     lockBit = a bit value between 0 and 31
269 	 *
270 	 * Since: 2.24
271 	 */
272 	public static void bitLock(int* address, int lockBit)
273 	{
274 		g_bit_lock(address, lockBit);
275 	}
276 
277 	/**
278 	 * Sets the indicated @lock_bit in @address, returning %TRUE if
279 	 * successful.  If the bit is already set, returns %FALSE immediately.
280 	 *
281 	 * Attempting to lock on two different bits within the same integer is
282 	 * not supported.
283 	 *
284 	 * The value of the bit that is set is (1u << @bit).  If @bit is not
285 	 * between 0 and 31 then the result is undefined.
286 	 *
287 	 * This function accesses @address atomically.  All other accesses to
288 	 * @address must be atomic in order for this function to work
289 	 * reliably.
290 	 *
291 	 * Params:
292 	 *     address = a pointer to an integer
293 	 *     lockBit = a bit value between 0 and 31
294 	 *
295 	 * Returns: %TRUE if the lock was acquired
296 	 *
297 	 * Since: 2.24
298 	 */
299 	public static bool bitTrylock(int* address, int lockBit)
300 	{
301 		return g_bit_trylock(address, lockBit) != 0;
302 	}
303 
304 	/**
305 	 * Clears the indicated @lock_bit in @address.  If another thread is
306 	 * currently blocked in g_bit_lock() on this same bit then it will be
307 	 * woken up.
308 	 *
309 	 * This function accesses @address atomically.  All other accesses to
310 	 * @address must be atomic in order for this function to work
311 	 * reliably.
312 	 *
313 	 * Params:
314 	 *     address = a pointer to an integer
315 	 *     lockBit = a bit value between 0 and 31
316 	 *
317 	 * Since: 2.24
318 	 */
319 	public static void bitUnlock(int* address, int lockBit)
320 	{
321 		g_bit_unlock(address, lockBit);
322 	}
323 
324 	/**
325 	 * Determine the approximate number of threads that the system will
326 	 * schedule simultaneously for this process.  This is intended to be
327 	 * used as a parameter to g_thread_pool_new() for CPU bound tasks and
328 	 * similar cases.
329 	 *
330 	 * Returns: Number of schedulable threads, always greater than 0
331 	 *
332 	 * Since: 2.36
333 	 */
334 	public static uint getNumProcessors()
335 	{
336 		return g_get_num_processors();
337 	}
338 
339 	/**
340 	 * This is equivalent to g_bit_lock, but working on pointers (or other
341 	 * pointer-sized values).
342 	 *
343 	 * For portability reasons, you may only lock on the bottom 32 bits of
344 	 * the pointer.
345 	 *
346 	 * Params:
347 	 *     address = a pointer to a #gpointer-sized value
348 	 *     lockBit = a bit value between 0 and 31
349 	 *
350 	 * Since: 2.30
351 	 */
352 	public static void pointerBitLock(void* address, int lockBit)
353 	{
354 		g_pointer_bit_lock(address, lockBit);
355 	}
356 
357 	/**
358 	 * This is equivalent to g_bit_trylock, but working on pointers (or
359 	 * other pointer-sized values).
360 	 *
361 	 * For portability reasons, you may only lock on the bottom 32 bits of
362 	 * the pointer.
363 	 *
364 	 * Params:
365 	 *     address = a pointer to a #gpointer-sized value
366 	 *     lockBit = a bit value between 0 and 31
367 	 *
368 	 * Returns: %TRUE if the lock was acquired
369 	 *
370 	 * Since: 2.30
371 	 */
372 	public static bool pointerBitTrylock(void* address, int lockBit)
373 	{
374 		return g_pointer_bit_trylock(address, lockBit) != 0;
375 	}
376 
377 	/**
378 	 * This is equivalent to g_bit_unlock, but working on pointers (or other
379 	 * pointer-sized values).
380 	 *
381 	 * For portability reasons, you may only lock on the bottom 32 bits of
382 	 * the pointer.
383 	 *
384 	 * Params:
385 	 *     address = a pointer to a #gpointer-sized value
386 	 *     lockBit = a bit value between 0 and 31
387 	 *
388 	 * Since: 2.30
389 	 */
390 	public static void pointerBitUnlock(void* address, int lockBit)
391 	{
392 		g_pointer_bit_unlock(address, lockBit);
393 	}
394 }