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