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 gio.Cancellable; 26 27 private import glib.ConstructionException; 28 private import glib.ErrorG; 29 private import glib.GException; 30 private import glib.Source; 31 private import gobject.ObjectG; 32 private import gobject.Signals; 33 public import gtkc.gdktypes; 34 private import gtkc.gio; 35 public import gtkc.giotypes; 36 37 38 /** 39 * GCancellable is a thread-safe operation cancellation stack used 40 * throughout GIO to allow for cancellation of synchronous and 41 * asynchronous operations. 42 */ 43 public class Cancellable : ObjectG 44 { 45 /** the main Gtk struct */ 46 protected GCancellable* gCancellable; 47 48 /** Get the main Gtk struct */ 49 public GCancellable* getCancellableStruct() 50 { 51 return gCancellable; 52 } 53 54 /** the main Gtk struct as a void* */ 55 protected override void* getStruct() 56 { 57 return cast(void*)gCancellable; 58 } 59 60 protected override void setStruct(GObject* obj) 61 { 62 gCancellable = cast(GCancellable*)obj; 63 super.setStruct(obj); 64 } 65 66 /** 67 * Sets our main struct and passes it to the parent class. 68 */ 69 public this (GCancellable* gCancellable, bool ownedRef = false) 70 { 71 this.gCancellable = gCancellable; 72 super(cast(GObject*)gCancellable, ownedRef); 73 } 74 75 /** 76 */ 77 78 public static GType getType() 79 { 80 return g_cancellable_get_type(); 81 } 82 83 /** 84 * Creates a new #GCancellable object. 85 * 86 * Applications that want to start one or more operations 87 * that should be cancellable should create a #GCancellable 88 * and pass it to the operations. 89 * 90 * One #GCancellable can be used in multiple consecutive 91 * operations or in multiple concurrent operations. 92 * 93 * Return: a #GCancellable. 94 * 95 * Throws: ConstructionException GTK+ fails to create the object. 96 */ 97 public this() 98 { 99 auto p = g_cancellable_new(); 100 101 if(p is null) 102 { 103 throw new ConstructionException("null returned by new"); 104 } 105 106 this(cast(GCancellable*) p, true); 107 } 108 109 /** 110 * Gets the top cancellable from the stack. 111 * 112 * Return: a #GCancellable from the top 113 * of the stack, or %NULL if the stack is empty. 114 */ 115 public static Cancellable getCurrent() 116 { 117 auto p = g_cancellable_get_current(); 118 119 if(p is null) 120 { 121 return null; 122 } 123 124 return ObjectG.getDObject!(Cancellable)(cast(GCancellable*) p); 125 } 126 127 /** 128 * Will set @cancellable to cancelled, and will emit the 129 * #GCancellable::cancelled signal. (However, see the warning about 130 * race conditions in the documentation for that signal if you are 131 * planning to connect to it.) 132 * 133 * This function is thread-safe. In other words, you can safely call 134 * it from a thread other than the one running the operation that was 135 * passed the @cancellable. 136 * 137 * The convention within gio is that cancelling an asynchronous 138 * operation causes it to complete asynchronously. That is, if you 139 * cancel the operation from the same thread in which it is running, 140 * then the operation's #GAsyncReadyCallback will not be invoked until 141 * the application returns to the main loop. 142 */ 143 public void cancel() 144 { 145 g_cancellable_cancel(gCancellable); 146 } 147 148 /** 149 * Convenience function to connect to the #GCancellable::cancelled 150 * signal. Also handles the race condition that may happen 151 * if the cancellable is cancelled right before connecting. 152 * 153 * @callback is called at most once, either directly at the 154 * time of the connect if @cancellable is already cancelled, 155 * or when @cancellable is cancelled in some thread. 156 * 157 * @data_destroy_func will be called when the handler is 158 * disconnected, or immediately if the cancellable is already 159 * cancelled. 160 * 161 * See #GCancellable::cancelled for details on how to use this. 162 * 163 * Since GLib 2.40, the lock protecting @cancellable is not held when 164 * @callback is invoked. This lifts a restriction in place for 165 * earlier GLib versions which now makes it easier to write cleanup 166 * code that unconditionally invokes e.g. g_cancellable_cancel(). 167 * 168 * Params: 169 * callback = The #GCallback to connect. 170 * data = Data to pass to @callback. 171 * dataDestroyFunc = Free function for @data or %NULL. 172 * 173 * Return: The id of the signal handler or 0 if @cancellable has already 174 * been cancelled. 175 * 176 * Since: 2.22 177 */ 178 public gulong connect(GCallback callback, void* data, GDestroyNotify dataDestroyFunc) 179 { 180 return g_cancellable_connect(gCancellable, callback, data, dataDestroyFunc); 181 } 182 183 /** 184 * Disconnects a handler from a cancellable instance similar to 185 * g_signal_handler_disconnect(). Additionally, in the event that a 186 * signal handler is currently running, this call will block until the 187 * handler has finished. Calling this function from a 188 * #GCancellable::cancelled signal handler will therefore result in a 189 * deadlock. 190 * 191 * This avoids a race condition where a thread cancels at the 192 * same time as the cancellable operation is finished and the 193 * signal handler is removed. See #GCancellable::cancelled for 194 * details on how to use this. 195 * 196 * If @cancellable is %NULL or @handler_id is %0 this function does 197 * nothing. 198 * 199 * Params: 200 * handlerId = Handler id of the handler to be disconnected, or %0. 201 * 202 * Since: 2.22 203 */ 204 public void disconnect(gulong handlerId) 205 { 206 g_cancellable_disconnect(gCancellable, handlerId); 207 } 208 209 /** 210 * Gets the file descriptor for a cancellable job. This can be used to 211 * implement cancellable operations on Unix systems. The returned fd will 212 * turn readable when @cancellable is cancelled. 213 * 214 * You are not supposed to read from the fd yourself, just check for 215 * readable status. Reading to unset the readable status is done 216 * with g_cancellable_reset(). 217 * 218 * After a successful return from this function, you should use 219 * g_cancellable_release_fd() to free up resources allocated for 220 * the returned file descriptor. 221 * 222 * See also g_cancellable_make_pollfd(). 223 * 224 * Return: A valid file descriptor. %-1 if the file descriptor 225 * is not supported, or on errors. 226 */ 227 public int getFd() 228 { 229 return g_cancellable_get_fd(gCancellable); 230 } 231 232 /** 233 * Checks if a cancellable job has been cancelled. 234 * 235 * Return: %TRUE if @cancellable is cancelled, 236 * FALSE if called with %NULL or if item is not cancelled. 237 */ 238 public bool isCancelled() 239 { 240 return g_cancellable_is_cancelled(gCancellable) != 0; 241 } 242 243 /** 244 * Creates a #GPollFD corresponding to @cancellable; this can be passed 245 * to g_poll() and used to poll for cancellation. This is useful both 246 * for unix systems without a native poll and for portability to 247 * windows. 248 * 249 * When this function returns %TRUE, you should use 250 * g_cancellable_release_fd() to free up resources allocated for the 251 * @pollfd. After a %FALSE return, do not call g_cancellable_release_fd(). 252 * 253 * If this function returns %FALSE, either no @cancellable was given or 254 * resource limits prevent this function from allocating the necessary 255 * structures for polling. (On Linux, you will likely have reached 256 * the maximum number of file descriptors.) The suggested way to handle 257 * these cases is to ignore the @cancellable. 258 * 259 * You are not supposed to read from the fd yourself, just check for 260 * readable status. Reading to unset the readable status is done 261 * with g_cancellable_reset(). 262 * 263 * Params: 264 * pollfd = a pointer to a #GPollFD 265 * 266 * Return: %TRUE if @pollfd was successfully initialized, %FALSE on 267 * failure to prepare the cancellable. 268 * 269 * Since: 2.22 270 */ 271 public bool makePollfd(GPollFD* pollfd) 272 { 273 return g_cancellable_make_pollfd(gCancellable, pollfd) != 0; 274 } 275 276 /** 277 * Pops @cancellable off the cancellable stack (verifying that @cancellable 278 * is on the top of the stack). 279 */ 280 public void popCurrent() 281 { 282 g_cancellable_pop_current(gCancellable); 283 } 284 285 /** 286 * Pushes @cancellable onto the cancellable stack. The current 287 * cancellable can then be received using g_cancellable_get_current(). 288 * 289 * This is useful when implementing cancellable operations in 290 * code that does not allow you to pass down the cancellable object. 291 * 292 * This is typically called automatically by e.g. #GFile operations, 293 * so you rarely have to call this yourself. 294 */ 295 public void pushCurrent() 296 { 297 g_cancellable_push_current(gCancellable); 298 } 299 300 /** 301 * Releases a resources previously allocated by g_cancellable_get_fd() 302 * or g_cancellable_make_pollfd(). 303 * 304 * For compatibility reasons with older releases, calling this function 305 * is not strictly required, the resources will be automatically freed 306 * when the @cancellable is finalized. However, the @cancellable will 307 * block scarce file descriptors until it is finalized if this function 308 * is not called. This can cause the application to run out of file 309 * descriptors when many #GCancellables are used at the same time. 310 * 311 * Since: 2.22 312 */ 313 public void releaseFd() 314 { 315 g_cancellable_release_fd(gCancellable); 316 } 317 318 /** 319 * Resets @cancellable to its uncancelled state. 320 * 321 * If cancellable is currently in use by any cancellable operation 322 * then the behavior of this function is undefined. 323 */ 324 public void reset() 325 { 326 g_cancellable_reset(gCancellable); 327 } 328 329 /** 330 * If the @cancellable is cancelled, sets the error to notify 331 * that the operation was cancelled. 332 * 333 * Return: %TRUE if @cancellable was cancelled, %FALSE if it was not 334 * 335 * Throws: GException on failure. 336 */ 337 public bool setErrorIfCancelled() 338 { 339 GError* err = null; 340 341 auto p = g_cancellable_set_error_if_cancelled(gCancellable, &err) != 0; 342 343 if (err !is null) 344 { 345 throw new GException( new ErrorG(err) ); 346 } 347 348 return p; 349 } 350 351 /** 352 * Creates a source that triggers if @cancellable is cancelled and 353 * calls its callback of type #GCancellableSourceFunc. This is 354 * primarily useful for attaching to another (non-cancellable) source 355 * with g_source_add_child_source() to add cancellability to it. 356 * 357 * For convenience, you can call this with a %NULL #GCancellable, 358 * in which case the source will never trigger. 359 * 360 * Return: the new #GSource. 361 * 362 * Since: 2.28 363 */ 364 public Source sourceNew() 365 { 366 auto p = g_cancellable_source_new(gCancellable); 367 368 if(p is null) 369 { 370 return null; 371 } 372 373 return new Source(cast(GSource*) p); 374 } 375 376 int[string] connectedSignals; 377 378 void delegate(Cancellable)[] onCancelledListeners; 379 /** 380 * Emitted when the operation has been cancelled. 381 * 382 * Can be used by implementations of cancellable operations. If the 383 * operation is cancelled from another thread, the signal will be 384 * emitted in the thread that cancelled the operation, not the 385 * thread that is running the operation. 386 * 387 * Note that disconnecting from this signal (or any signal) in a 388 * multi-threaded program is prone to race conditions. For instance 389 * it is possible that a signal handler may be invoked even after 390 * a call to g_signal_handler_disconnect() for that handler has 391 * already returned. 392 * 393 * There is also a problem when cancellation happens right before 394 * connecting to the signal. If this happens the signal will 395 * unexpectedly not be emitted, and checking before connecting to 396 * the signal leaves a race condition where this is still happening. 397 * 398 * In order to make it safe and easy to connect handlers there 399 * are two helper functions: g_cancellable_connect() and 400 * g_cancellable_disconnect() which protect against problems 401 * like this. 402 * 403 * An example of how to us this: 404 * |[<!-- language="C" --> 405 * // Make sure we don't do unnecessary work if already cancelled 406 * if (g_cancellable_set_error_if_cancelled (cancellable, error)) 407 * return; 408 * 409 * // Set up all the data needed to be able to handle cancellation 410 * // of the operation 411 * my_data = my_data_new (...); 412 * 413 * id = 0; 414 * if (cancellable) 415 * id = g_cancellable_connect (cancellable, 416 * G_CALLBACK (cancelled_handler) 417 * data, NULL); 418 * 419 * // cancellable operation here... 420 * 421 * g_cancellable_disconnect (cancellable, id); 422 * 423 * // cancelled_handler is never called after this, it is now safe 424 * // to free the data 425 * my_data_free (my_data); 426 * ]| 427 * 428 * Note that the cancelled signal is emitted in the thread that 429 * the user cancelled from, which may be the main thread. So, the 430 * cancellable signal should not do something that can block. 431 */ 432 void addOnCancelled(void delegate(Cancellable) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 433 { 434 if ( "cancelled" !in connectedSignals ) 435 { 436 Signals.connectData( 437 this, 438 "cancelled", 439 cast(GCallback)&callBackCancelled, 440 cast(void*)this, 441 null, 442 connectFlags); 443 connectedSignals["cancelled"] = 1; 444 } 445 onCancelledListeners ~= dlg; 446 } 447 extern(C) static void callBackCancelled(GCancellable* cancellableStruct, Cancellable _cancellable) 448 { 449 foreach ( void delegate(Cancellable) dlg; _cancellable.onCancelledListeners ) 450 { 451 dlg(_cancellable); 452 } 453 } 454 }