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 private import gtkd.Loader; 34 35 36 /** 37 * The #GThread struct represents a running thread. This struct 38 * is returned by g_thread_new() or g_thread_try_new(). You can 39 * obtain the #GThread struct representing the current thread by 40 * calling g_thread_self(). 41 * 42 * GThread is refcounted, see g_thread_ref() and g_thread_unref(). 43 * The thread represented by it holds a reference while it is running, 44 * and g_thread_join() consumes the reference that it is given, so 45 * it is normally not necessary to manage GThread references 46 * explicitly. 47 * 48 * The structure is opaque -- none of its fields may be directly 49 * accessed. 50 */ 51 public class Thread 52 { 53 /** the main Gtk struct */ 54 protected GThread* gThread; 55 protected bool ownedRef; 56 57 /** Get the main Gtk struct */ 58 public GThread* getThreadStruct(bool transferOwnership = false) 59 { 60 if (transferOwnership) 61 ownedRef = false; 62 return gThread; 63 } 64 65 /** the main Gtk struct as a void* */ 66 protected void* getStruct() 67 { 68 return cast(void*)gThread; 69 } 70 71 /** 72 * Sets our main struct and passes it to the parent class. 73 */ 74 public this (GThread* gThread, bool ownedRef = false) 75 { 76 this.gThread = gThread; 77 this.ownedRef = ownedRef; 78 } 79 80 ~this () 81 { 82 if ( Linker.isLoaded(LIBRARY_GLIB) && ownedRef ) 83 g_thread_unref(gThread); 84 } 85 86 87 /** 88 * This function is the same as g_thread_new() except that 89 * it allows for the possibility of failure. 90 * 91 * If a thread can not be created (due to resource limits), 92 * @error is set and %NULL is returned. 93 * 94 * Params: 95 * name = an (optional) name for the new thread 96 * func = a function to execute in the new thread 97 * data = an argument to supply to the new thread 98 * 99 * Returns: the new #GThread, or %NULL if an error occurred 100 * 101 * Since: 2.32 102 * 103 * Throws: GException on failure. 104 * Throws: ConstructionException GTK+ fails to create the object. 105 */ 106 public this(string name, GThreadFunc func, void* data) 107 { 108 GError* err = null; 109 110 auto __p = g_thread_try_new(Str.toStringz(name), func, data, &err); 111 112 if (err !is null) 113 { 114 throw new GException( new ErrorG(err) ); 115 } 116 117 if(__p is null) 118 { 119 throw new ConstructionException("null returned by try_new"); 120 } 121 122 this(cast(GThread*) __p); 123 } 124 125 /** 126 * Waits until @thread finishes, i.e. the function @func, as 127 * given to g_thread_new(), returns or g_thread_exit() is called. 128 * If @thread has already terminated, then g_thread_join() 129 * returns immediately. 130 * 131 * Any thread can wait for any other thread by calling g_thread_join(), 132 * not just its 'creator'. Calling g_thread_join() from multiple threads 133 * for the same @thread leads to undefined behaviour. 134 * 135 * The value returned by @func or given to g_thread_exit() is 136 * returned by this function. 137 * 138 * g_thread_join() consumes the reference to the passed-in @thread. 139 * This will usually cause the #GThread struct and associated resources 140 * to be freed. Use g_thread_ref() to obtain an extra reference if you 141 * want to keep the GThread alive beyond the g_thread_join() call. 142 * 143 * Returns: the return value of the thread 144 */ 145 public void* join() 146 { 147 return g_thread_join(gThread); 148 } 149 150 alias doref = ref_; 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 ref_() 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); 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 }