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