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 99 /** Get the main Gtk struct */ 100 public GRWLock* getRWLockStruct() 101 { 102 return gRWLock; 103 } 104 105 /** the main Gtk struct as a void* */ 106 protected void* getStruct() 107 { 108 return cast(void*)gRWLock; 109 } 110 111 /** 112 * Sets our main struct and passes it to the parent class. 113 */ 114 public this (GRWLock* gRWLock) 115 { 116 this.gRWLock = gRWLock; 117 } 118 119 120 /** 121 * Frees the resources allocated to a lock with g_rw_lock_init(). 122 * 123 * This function should not be used with a #GRWLock that has been 124 * statically allocated. 125 * 126 * Calling g_rw_lock_clear() when any thread holds the lock 127 * leads to undefined behaviour. 128 * 129 * Sine: 2.32 130 */ 131 public void clear() 132 { 133 g_rw_lock_clear(gRWLock); 134 } 135 136 /** 137 * Initializes a #GRWLock so that it can be used. 138 * 139 * This function is useful to initialize a lock that has been 140 * allocated on the stack, or as part of a larger structure. It is not 141 * necessary to initialise a reader-writer lock that has been statically 142 * allocated. 143 * 144 * |[<!-- language="C" --> 145 * typedef struct { 146 * GRWLock l; 147 * ... 148 * } Blob; 149 * 150 * Blob *b; 151 * 152 * b = g_new (Blob, 1); 153 * g_rw_lock_init (&b->l); 154 * ]| 155 * 156 * To undo the effect of g_rw_lock_init() when a lock is no longer 157 * needed, use g_rw_lock_clear(). 158 * 159 * Calling g_rw_lock_init() on an already initialized #GRWLock leads 160 * to undefined behaviour. 161 * 162 * Since: 2.32 163 */ 164 public void init() 165 { 166 g_rw_lock_init(gRWLock); 167 } 168 169 /** 170 * Obtain a read lock on @rw_lock. If another thread currently holds 171 * the write lock on @rw_lock or blocks waiting for it, the current 172 * thread will block. Read locks can be taken recursively. 173 * 174 * It is implementation-defined how many threads are allowed to 175 * hold read locks on the same lock simultaneously. 176 * 177 * Since: 2.32 178 */ 179 public void readerLock() 180 { 181 g_rw_lock_reader_lock(gRWLock); 182 } 183 184 /** 185 * Tries to obtain a read lock on @rw_lock and returns %TRUE if 186 * the read lock was successfully obtained. Otherwise it 187 * returns %FALSE. 188 * 189 * Return: %TRUE if @rw_lock could be locked 190 * 191 * Since: 2.32 192 */ 193 public bool readerTrylock() 194 { 195 return g_rw_lock_reader_trylock(gRWLock) != 0; 196 } 197 198 /** 199 * Release a read lock on @rw_lock. 200 * 201 * Calling g_rw_lock_reader_unlock() on a lock that is not held 202 * by the current thread leads to undefined behaviour. 203 * 204 * Since: 2.32 205 */ 206 public void readerUnlock() 207 { 208 g_rw_lock_reader_unlock(gRWLock); 209 } 210 211 /** 212 * Obtain a write lock on @rw_lock. If any thread already holds 213 * a read or write lock on @rw_lock, the current thread will block 214 * until all other threads have dropped their locks on @rw_lock. 215 * 216 * Since: 2.32 217 */ 218 public void writerLock() 219 { 220 g_rw_lock_writer_lock(gRWLock); 221 } 222 223 /** 224 * Tries to obtain a write lock on @rw_lock. If any other thread holds 225 * a read or write lock on @rw_lock, it immediately returns %FALSE. 226 * Otherwise it locks @rw_lock and returns %TRUE. 227 * 228 * Return: %TRUE if @rw_lock could be locked 229 * 230 * Since: 2.32 231 */ 232 public bool writerTrylock() 233 { 234 return g_rw_lock_writer_trylock(gRWLock) != 0; 235 } 236 237 /** 238 * Release a write lock on @rw_lock. 239 * 240 * Calling g_rw_lock_writer_unlock() on a lock that is not held 241 * by the current thread leads to undefined behaviour. 242 * 243 * Since: 2.32 244 */ 245 public void writerUnlock() 246 { 247 g_rw_lock_writer_unlock(gRWLock); 248 } 249 }