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.Mutex; 26 27 private import glib.c.functions; 28 public import glib.c.types; 29 public import gtkc.glibtypes; 30 31 32 /** 33 * The #GMutex struct is an opaque data structure to represent a mutex 34 * (mutual exclusion). It can be used to protect data against shared 35 * access. 36 * 37 * Take for example the following function: 38 * |[<!-- language="C" --> 39 * int 40 * give_me_next_number (void) 41 * { 42 * static int current_number = 0; 43 * 44 * // now do a very complicated calculation to calculate the new 45 * // number, this might for example be a random number generator 46 * current_number = calc_next_number (current_number); 47 * 48 * return current_number; 49 * } 50 * ]| 51 * It is easy to see that this won't work in a multi-threaded 52 * application. There current_number must be protected against shared 53 * access. A #GMutex can be used as a solution to this problem: 54 * |[<!-- language="C" --> 55 * int 56 * give_me_next_number (void) 57 * { 58 * static GMutex mutex; 59 * static int current_number = 0; 60 * int ret_val; 61 * 62 * g_mutex_lock (&mutex); 63 * ret_val = current_number = calc_next_number (current_number); 64 * g_mutex_unlock (&mutex); 65 * 66 * return ret_val; 67 * } 68 * ]| 69 * Notice that the #GMutex is not initialised to any particular value. 70 * Its placement in static storage ensures that it will be initialised 71 * to all-zeros, which is appropriate. 72 * 73 * If a #GMutex is placed in other contexts (eg: embedded in a struct) 74 * then it must be explicitly initialised using g_mutex_init(). 75 * 76 * A #GMutex should only be accessed via g_mutex_ functions. 77 */ 78 public class Mutex 79 { 80 /** the main Gtk struct */ 81 protected GMutex* gMutex; 82 protected bool ownedRef; 83 84 /** Get the main Gtk struct */ 85 public GMutex* getMutexStruct(bool transferOwnership = false) 86 { 87 if (transferOwnership) 88 ownedRef = false; 89 return gMutex; 90 } 91 92 /** the main Gtk struct as a void* */ 93 protected void* getStruct() 94 { 95 return cast(void*)gMutex; 96 } 97 98 /** 99 * Sets our main struct and passes it to the parent class. 100 */ 101 public this (GMutex* gMutex, bool ownedRef = false) 102 { 103 this.gMutex = gMutex; 104 this.ownedRef = ownedRef; 105 } 106 107 108 /** 109 * Frees the resources allocated to a mutex with g_mutex_init(). 110 * 111 * This function should not be used with a #GMutex that has been 112 * statically allocated. 113 * 114 * Calling g_mutex_clear() on a locked mutex leads to undefined 115 * behaviour. 116 * 117 * Sine: 2.32 118 */ 119 public void clear() 120 { 121 g_mutex_clear(gMutex); 122 } 123 124 /** 125 * Initializes a #GMutex so that it can be used. 126 * 127 * This function is useful to initialize a mutex that has been 128 * allocated on the stack, or as part of a larger structure. 129 * It is not necessary to initialize a mutex that has been 130 * statically allocated. 131 * 132 * |[<!-- language="C" --> 133 * typedef struct { 134 * GMutex m; 135 * ... 136 * } Blob; 137 * 138 * Blob *b; 139 * 140 * b = g_new (Blob, 1); 141 * g_mutex_init (&b->m); 142 * ]| 143 * 144 * To undo the effect of g_mutex_init() when a mutex is no longer 145 * needed, use g_mutex_clear(). 146 * 147 * Calling g_mutex_init() on an already initialized #GMutex leads 148 * to undefined behaviour. 149 * 150 * Since: 2.32 151 */ 152 public void init() 153 { 154 g_mutex_init(gMutex); 155 } 156 157 /** 158 * Locks @mutex. If @mutex is already locked by another thread, the 159 * current thread will block until @mutex is unlocked by the other 160 * thread. 161 * 162 * #GMutex is neither guaranteed to be recursive nor to be 163 * non-recursive. As such, calling g_mutex_lock() on a #GMutex that has 164 * already been locked by the same thread results in undefined behaviour 165 * (including but not limited to deadlocks). 166 */ 167 public void lock() 168 { 169 g_mutex_lock(gMutex); 170 } 171 172 /** 173 * Tries to lock @mutex. If @mutex is already locked by another thread, 174 * it immediately returns %FALSE. Otherwise it locks @mutex and returns 175 * %TRUE. 176 * 177 * #GMutex is neither guaranteed to be recursive nor to be 178 * non-recursive. As such, calling g_mutex_lock() on a #GMutex that has 179 * already been locked by the same thread results in undefined behaviour 180 * (including but not limited to deadlocks or arbitrary return values). 181 * 182 * Returns: %TRUE if @mutex could be locked 183 */ 184 public bool trylock() 185 { 186 return g_mutex_trylock(gMutex) != 0; 187 } 188 189 /** 190 * Unlocks @mutex. If another thread is blocked in a g_mutex_lock() 191 * call for @mutex, it will become unblocked and can lock @mutex itself. 192 * 193 * Calling g_mutex_unlock() on a mutex that is not locked by the 194 * current thread leads to undefined behaviour. 195 */ 196 public void unlock() 197 { 198 g_mutex_unlock(gMutex); 199 } 200 }