source: appstream-generator/build/girepo/gio/Cancellable.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

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