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