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