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