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