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.RWLock; 26 27 private import gtkc.glib; 28 public import gtkc.glibtypes; 29 30 31 /** 32 * The GRWLock struct is an opaque data structure to represent a 33 * reader-writer lock. It is similar to a #GMutex in that it allows 34 * multiple threads to coordinate access to a shared resource. 35 * 36 * The difference to a mutex is that a reader-writer lock discriminates 37 * between read-only ('reader') and full ('writer') access. While only 38 * one thread at a time is allowed write access (by holding the 'writer' 39 * lock via g_rw_lock_writer_lock()), multiple threads can gain 40 * simultaneous read-only access (by holding the 'reader' lock via 41 * g_rw_lock_reader_lock()). 42 * 43 * Here is an example for an array with access functions: 44 * |[<!-- language="C" --> 45 * GRWLock lock; 46 * GPtrArray *array; 47 * 48 * gpointer 49 * my_array_get (guint index) 50 * { 51 * gpointer retval = NULL; 52 * 53 * if (!array) 54 * return NULL; 55 * 56 * g_rw_lock_reader_lock (&lock); 57 * if (index < array->len) 58 * retval = g_ptr_array_index (array, index); 59 * g_rw_lock_reader_unlock (&lock); 60 * 61 * return retval; 62 * } 63 * 64 * void 65 * my_array_set (guint index, gpointer data) 66 * { 67 * g_rw_lock_writer_lock (&lock); 68 * 69 * if (!array) 70 * array = g_ptr_array_new (); 71 * 72 * if (index >= array->len) 73 * g_ptr_array_set_size (array, index+1); 74 * g_ptr_array_index (array, index) = data; 75 * 76 * g_rw_lock_writer_unlock (&lock); 77 * } 78 * ]| 79 * This example shows an array which can be accessed by many readers 80 * (the my_array_get() function) simultaneously, whereas the writers 81 * (the my_array_set() function) will only be allowed one at a time 82 * and only if no readers currently access the array. This is because 83 * of the potentially dangerous resizing of the array. Using these 84 * functions is fully multi-thread safe now. 85 * 86 * If a #GRWLock is allocated in static storage then it can be used 87 * without initialisation. Otherwise, you should call 88 * g_rw_lock_init() on it and g_rw_lock_clear() when done. 89 * 90 * A GRWLock should only be accessed with the g_rw_lock_ functions. 91 * 92 * Since: 2.32 93 */ 94 public class RWLock 95 { 96 /** the main Gtk struct */ 97 protected GRWLock* gRWLock; 98 protected bool ownedRef; 99 100 /** Get the main Gtk struct */ 101 public GRWLock* getRWLockStruct(bool transferOwnership = false) 102 { 103 if (transferOwnership) 104 ownedRef = false; 105 return gRWLock; 106 } 107 108 /** the main Gtk struct as a void* */ 109 protected void* getStruct() 110 { 111 return cast(void*)gRWLock; 112 } 113 114 /** 115 * Sets our main struct and passes it to the parent class. 116 */ 117 public this (GRWLock* gRWLock, bool ownedRef = false) 118 { 119 this.gRWLock = gRWLock; 120 this.ownedRef = ownedRef; 121 } 122 123 124 /** 125 * Frees the resources allocated to a lock with g_rw_lock_init(). 126 * 127 * This function should not be used with a #GRWLock that has been 128 * statically allocated. 129 * 130 * Calling g_rw_lock_clear() when any thread holds the lock 131 * leads to undefined behaviour. 132 * 133 * Sine: 2.32 134 */ 135 public void clear() 136 { 137 g_rw_lock_clear(gRWLock); 138 } 139 140 /** 141 * Initializes a #GRWLock so that it can be used. 142 * 143 * This function is useful to initialize a lock that has been 144 * allocated on the stack, or as part of a larger structure. It is not 145 * necessary to initialise a reader-writer lock that has been statically 146 * allocated. 147 * 148 * |[<!-- language="C" --> 149 * typedef struct { 150 * GRWLock l; 151 * ... 152 * } Blob; 153 * 154 * Blob *b; 155 * 156 * b = g_new (Blob, 1); 157 * g_rw_lock_init (&b->l); 158 * ]| 159 * 160 * To undo the effect of g_rw_lock_init() when a lock is no longer 161 * needed, use g_rw_lock_clear(). 162 * 163 * Calling g_rw_lock_init() on an already initialized #GRWLock leads 164 * to undefined behaviour. 165 * 166 * Since: 2.32 167 */ 168 public void init() 169 { 170 g_rw_lock_init(gRWLock); 171 } 172 173 /** 174 * Obtain a read lock on @rw_lock. If another thread currently holds 175 * the write lock on @rw_lock or blocks waiting for it, the current 176 * thread will block. Read locks can be taken recursively. 177 * 178 * It is implementation-defined how many threads are allowed to 179 * hold read locks on the same lock simultaneously. 180 * 181 * Since: 2.32 182 */ 183 public void readerLock() 184 { 185 g_rw_lock_reader_lock(gRWLock); 186 } 187 188 /** 189 * Tries to obtain a read lock on @rw_lock and returns %TRUE if 190 * the read lock was successfully obtained. Otherwise it 191 * returns %FALSE. 192 * 193 * Returns: %TRUE if @rw_lock could be locked 194 * 195 * Since: 2.32 196 */ 197 public bool readerTrylock() 198 { 199 return g_rw_lock_reader_trylock(gRWLock) != 0; 200 } 201 202 /** 203 * Release a read lock on @rw_lock. 204 * 205 * Calling g_rw_lock_reader_unlock() on a lock that is not held 206 * by the current thread leads to undefined behaviour. 207 * 208 * Since: 2.32 209 */ 210 public void readerUnlock() 211 { 212 g_rw_lock_reader_unlock(gRWLock); 213 } 214 215 /** 216 * Obtain a write lock on @rw_lock. If any thread already holds 217 * a read or write lock on @rw_lock, the current thread will block 218 * until all other threads have dropped their locks on @rw_lock. 219 * 220 * Since: 2.32 221 */ 222 public void writerLock() 223 { 224 g_rw_lock_writer_lock(gRWLock); 225 } 226 227 /** 228 * Tries to obtain a write lock on @rw_lock. If any other thread holds 229 * a read or write lock on @rw_lock, it immediately returns %FALSE. 230 * Otherwise it locks @rw_lock and returns %TRUE. 231 * 232 * Returns: %TRUE if @rw_lock could be locked 233 * 234 * Since: 2.32 235 */ 236 public bool writerTrylock() 237 { 238 return g_rw_lock_writer_trylock(gRWLock) != 0; 239 } 240 241 /** 242 * Release a write lock on @rw_lock. 243 * 244 * Calling g_rw_lock_writer_unlock() on a lock that is not held 245 * by the current thread leads to undefined behaviour. 246 * 247 * Since: 2.32 248 */ 249 public void writerUnlock() 250 { 251 g_rw_lock_writer_unlock(gRWLock); 252 } 253 }