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

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

Initial release

File size: 7.9 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.Cond;
22
23private import gi.glib;
24public  import gi.glibtypes;
25private import glib.Mutex;
26
27
28/**
29 * The #GCond struct is an opaque data structure that represents a
30 * condition. Threads can block on a #GCond if they find a certain
31 * condition to be false. If other threads change the state of this
32 * condition they signal the #GCond, and that causes the waiting
33 * threads to be woken up.
34 *
35 * Consider the following example of a shared variable.  One or more
36 * threads can wait for data to be published to the variable and when
37 * another thread publishes the data, it can signal one of the waiting
38 * threads to wake up to collect the data.
39 *
40 * Here is an example for using GCond to block a thread until a condition
41 * is satisfied:
42 * |[<!-- language="C" -->
43 * gpointer current_data = NULL;
44 * GMutex data_mutex;
45 * GCond data_cond;
46 *
47 * void
48 * push_data (gpointer data)
49 * {
50 * g_mutex_lock (&data_mutex);
51 * current_data = data;
52 * g_cond_signal (&data_cond);
53 * g_mutex_unlock (&data_mutex);
54 * }
55 *
56 * gpointer
57 * pop_data (void)
58 * {
59 * gpointer data;
60 *
61 * g_mutex_lock (&data_mutex);
62 * while (!current_data)
63 * g_cond_wait (&data_cond, &data_mutex);
64 * data = current_data;
65 * current_data = NULL;
66 * g_mutex_unlock (&data_mutex);
67 *
68 * return data;
69 * }
70 * ]|
71 * Whenever a thread calls pop_data() now, it will wait until
72 * current_data is non-%NULL, i.e. until some other thread
73 * has called push_data().
74 *
75 * The example shows that use of a condition variable must always be
76 * paired with a mutex.  Without the use of a mutex, there would be a
77 * race between the check of @current_data by the while loop in
78 * pop_data() and waiting. Specifically, another thread could set
79 * @current_data after the check, and signal the cond (with nobody
80 * waiting on it) before the first thread goes to sleep. #GCond is
81 * specifically useful for its ability to release the mutex and go
82 * to sleep atomically.
83 *
84 * It is also important to use the g_cond_wait() and g_cond_wait_until()
85 * functions only inside a loop which checks for the condition to be
86 * true.  See g_cond_wait() for an explanation of why the condition may
87 * not be true even after it returns.
88 *
89 * If a #GCond is allocated in static storage then it can be used
90 * without initialisation.  Otherwise, you should call g_cond_init()
91 * on it and g_cond_clear() when done.
92 *
93 * A #GCond should only be accessed via the g_cond_ functions.
94 */
95public class Cond
96{
97        /** the main Gtk struct */
98        protected GCond* gCond;
99        protected bool ownedRef;
100
101        /** Get the main Gtk struct */
102        public GCond* getCondStruct()
103        {
104                return gCond;
105        }
106
107        /** the main Gtk struct as a void* */
108        protected void* getStruct()
109        {
110                return cast(void*)gCond;
111        }
112
113        /**
114         * Sets our main struct and passes it to the parent class.
115         */
116        public this (GCond* gCond, bool ownedRef = false)
117        {
118                this.gCond = gCond;
119                this.ownedRef = ownedRef;
120        }
121
122
123        /**
124         * If threads are waiting for @cond, all of them are unblocked.
125         * If no threads are waiting for @cond, this function has no effect.
126         * It is good practice to lock the same mutex as the waiting threads
127         * while calling this function, though not required.
128         */
129        public void broadcast()
130        {
131                g_cond_broadcast(gCond);
132        }
133
134        /**
135         * Frees the resources allocated to a #GCond with g_cond_init().
136         *
137         * This function should not be used with a #GCond that has been
138         * statically allocated.
139         *
140         * Calling g_cond_clear() for a #GCond on which threads are
141         * blocking leads to undefined behaviour.
142         *
143         * Since: 2.32
144         */
145        public void clear()
146        {
147                g_cond_clear(gCond);
148        }
149
150        /**
151         * Initialises a #GCond so that it can be used.
152         *
153         * This function is useful to initialise a #GCond that has been
154         * allocated as part of a larger structure.  It is not necessary to
155         * initialise a #GCond that has been statically allocated.
156         *
157         * To undo the effect of g_cond_init() when a #GCond is no longer
158         * needed, use g_cond_clear().
159         *
160         * Calling g_cond_init() on an already-initialised #GCond leads
161         * to undefined behaviour.
162         *
163         * Since: 2.32
164         */
165        public void init()
166        {
167                g_cond_init(gCond);
168        }
169
170        /**
171         * If threads are waiting for @cond, at least one of them is unblocked.
172         * If no threads are waiting for @cond, this function has no effect.
173         * It is good practice to hold the same lock as the waiting thread
174         * while calling this function, though not required.
175         */
176        public void signal()
177        {
178                g_cond_signal(gCond);
179        }
180
181        /**
182         * Atomically releases @mutex and waits until @cond is signalled.
183         * When this function returns, @mutex is locked again and owned by the
184         * calling thread.
185         *
186         * When using condition variables, it is possible that a spurious wakeup
187         * may occur (ie: g_cond_wait() returns even though g_cond_signal() was
188         * not called).  It's also possible that a stolen wakeup may occur.
189         * This is when g_cond_signal() is called, but another thread acquires
190         * @mutex before this thread and modifies the state of the program in
191         * such a way that when g_cond_wait() is able to return, the expected
192         * condition is no longer met.
193         *
194         * For this reason, g_cond_wait() must always be used in a loop.  See
195         * the documentation for #GCond for a complete example.
196         *
197         * Params:
198         *     mutex = a #GMutex that is currently locked
199         */
200        public void wait(Mutex mutex)
201        {
202                g_cond_wait(gCond, (mutex is null) ? null : mutex.getMutexStruct());
203        }
204
205        /**
206         * Waits until either @cond is signalled or @end_time has passed.
207         *
208         * As with g_cond_wait() it is possible that a spurious or stolen wakeup
209         * could occur.  For that reason, waiting on a condition variable should
210         * always be in a loop, based on an explicitly-checked predicate.
211         *
212         * %TRUE is returned if the condition variable was signalled (or in the
213         * case of a spurious wakeup).  %FALSE is returned if @end_time has
214         * passed.
215         *
216         * The following code shows how to correctly perform a timed wait on a
217         * condition variable (extending the example presented in the
218         * documentation for #GCond):
219         *
220         * |[<!-- language="C" -->
221         * gpointer
222         * pop_data_timed (void)
223         * {
224         * gint64 end_time;
225         * gpointer data;
226         *
227         * g_mutex_lock (&data_mutex);
228         *
229         * end_time = g_get_monotonic_time () + 5 * G_TIME_SPAN_SECOND;
230         * while (!current_data)
231         * if (!g_cond_wait_until (&data_cond, &data_mutex, end_time))
232         * {
233         * // timeout has passed.
234         * g_mutex_unlock (&data_mutex);
235         * return NULL;
236         * }
237         *
238         * // there is data for us
239         * data = current_data;
240         * current_data = NULL;
241         *
242         * g_mutex_unlock (&data_mutex);
243         *
244         * return data;
245         * }
246         * ]|
247         *
248         * Notice that the end time is calculated once, before entering the
249         * loop and reused.  This is the motivation behind the use of absolute
250         * time on this API -- if a relative time of 5 seconds were passed
251         * directly to the call and a spurious wakeup occurred, the program would
252         * have to start over waiting again (which would lead to a total wait
253         * time of more than 5 seconds).
254         *
255         * Params:
256         *     mutex = a #GMutex that is currently locked
257         *     endTime = the monotonic time to wait until
258         *
259         * Returns: %TRUE on a signal, %FALSE on a timeout
260         *
261         * Since: 2.32
262         */
263        public bool waitUntil(Mutex mutex, long endTime)
264        {
265                return g_cond_wait_until(gCond, (mutex is null) ? null : mutex.getMutexStruct(), endTime) != 0;
266        }
267}
Note: See TracBrowser for help on using the repository browser.