source: appstream-generator/build/girepo/glib/RWLock.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

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