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