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 	protected bool ownedRef;
104 
105 	/** Get the main Gtk struct */
106 	public GCond* getCondStruct(bool transferOwnership = false)
107 	{
108 		if (transferOwnership)
109 			ownedRef = false;
110 		return gCond;
111 	}
112 
113 	/** the main Gtk struct as a void* */
114 	protected void* getStruct()
115 	{
116 		return cast(void*)gCond;
117 	}
118 
119 	/**
120 	 * Sets our main struct and passes it to the parent class.
121 	 */
122 	public this (GCond* gCond, bool ownedRef = false)
123 	{
124 		this.gCond = gCond;
125 		this.ownedRef = ownedRef;
126 	}
127 
128 
129 	/**
130 	 * If threads are waiting for @cond, all of them are unblocked.
131 	 * If no threads are waiting for @cond, this function has no effect.
132 	 * It is good practice to lock the same mutex as the waiting threads
133 	 * while calling this function, though not required.
134 	 */
135 	public void broadcast()
136 	{
137 		g_cond_broadcast(gCond);
138 	}
139 
140 	/**
141 	 * Frees the resources allocated to a #GCond with g_cond_init().
142 	 *
143 	 * This function should not be used with a #GCond that has been
144 	 * statically allocated.
145 	 *
146 	 * Calling g_cond_clear() for a #GCond on which threads are
147 	 * blocking leads to undefined behaviour.
148 	 *
149 	 * Since: 2.32
150 	 */
151 	public void clear()
152 	{
153 		g_cond_clear(gCond);
154 	}
155 
156 	/**
157 	 * Initialises a #GCond so that it can be used.
158 	 *
159 	 * This function is useful to initialise a #GCond that has been
160 	 * allocated as part of a larger structure.  It is not necessary to
161 	 * initialise a #GCond that has been statically allocated.
162 	 *
163 	 * To undo the effect of g_cond_init() when a #GCond is no longer
164 	 * needed, use g_cond_clear().
165 	 *
166 	 * Calling g_cond_init() on an already-initialised #GCond leads
167 	 * to undefined behaviour.
168 	 *
169 	 * Since: 2.32
170 	 */
171 	public void init()
172 	{
173 		g_cond_init(gCond);
174 	}
175 
176 	/**
177 	 * If threads are waiting for @cond, at least one of them is unblocked.
178 	 * If no threads are waiting for @cond, this function has no effect.
179 	 * It is good practice to hold the same lock as the waiting thread
180 	 * while calling this function, though not required.
181 	 */
182 	public void signal()
183 	{
184 		g_cond_signal(gCond);
185 	}
186 
187 	/**
188 	 * Atomically releases @mutex and waits until @cond is signalled.
189 	 * When this function returns, @mutex is locked again and owned by the
190 	 * calling thread.
191 	 *
192 	 * When using condition variables, it is possible that a spurious wakeup
193 	 * may occur (ie: g_cond_wait() returns even though g_cond_signal() was
194 	 * not called).  It's also possible that a stolen wakeup may occur.
195 	 * This is when g_cond_signal() is called, but another thread acquires
196 	 * @mutex before this thread and modifies the state of the program in
197 	 * such a way that when g_cond_wait() is able to return, the expected
198 	 * condition is no longer met.
199 	 *
200 	 * For this reason, g_cond_wait() must always be used in a loop.  See
201 	 * the documentation for #GCond for a complete example.
202 	 *
203 	 * Params:
204 	 *     mutex = a #GMutex that is currently locked
205 	 */
206 	public void wait(Mutex mutex)
207 	{
208 		g_cond_wait(gCond, (mutex is null) ? null : mutex.getMutexStruct());
209 	}
210 
211 	/**
212 	 * Waits until either @cond is signalled or @end_time has passed.
213 	 *
214 	 * As with g_cond_wait() it is possible that a spurious or stolen wakeup
215 	 * could occur.  For that reason, waiting on a condition variable should
216 	 * always be in a loop, based on an explicitly-checked predicate.
217 	 *
218 	 * %TRUE is returned if the condition variable was signalled (or in the
219 	 * case of a spurious wakeup).  %FALSE is returned if @end_time has
220 	 * passed.
221 	 *
222 	 * The following code shows how to correctly perform a timed wait on a
223 	 * condition variable (extending the example presented in the
224 	 * documentation for #GCond):
225 	 *
226 	 * |[<!-- language="C" -->
227 	 * gpointer
228 	 * pop_data_timed (void)
229 	 * {
230 	 * gint64 end_time;
231 	 * gpointer data;
232 	 *
233 	 * g_mutex_lock (&data_mutex);
234 	 *
235 	 * end_time = g_get_monotonic_time () + 5 * G_TIME_SPAN_SECOND;
236 	 * while (!current_data)
237 	 * if (!g_cond_wait_until (&data_cond, &data_mutex, end_time))
238 	 * {
239 	 * // timeout has passed.
240 	 * g_mutex_unlock (&data_mutex);
241 	 * return NULL;
242 	 * }
243 	 *
244 	 * // there is data for us
245 	 * data = current_data;
246 	 * current_data = NULL;
247 	 *
248 	 * g_mutex_unlock (&data_mutex);
249 	 *
250 	 * return data;
251 	 * }
252 	 * ]|
253 	 *
254 	 * Notice that the end time is calculated once, before entering the
255 	 * loop and reused.  This is the motivation behind the use of absolute
256 	 * time on this API -- if a relative time of 5 seconds were passed
257 	 * directly to the call and a spurious wakeup occurred, the program would
258 	 * have to start over waiting again (which would lead to a total wait
259 	 * time of more than 5 seconds).
260 	 *
261 	 * Params:
262 	 *     mutex = a #GMutex that is currently locked
263 	 *     endTime = the monotonic time to wait until
264 	 *
265 	 * Returns: %TRUE on a signal, %FALSE on a timeout
266 	 *
267 	 * Since: 2.32
268 	 */
269 	public bool waitUntil(Mutex mutex, long endTime)
270 	{
271 		return g_cond_wait_until(gCond, (mutex is null) ? null : mutex.getMutexStruct(), endTime) != 0;
272 	}
273 }