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