source: appstream-generator/build/girepo/gobject/Closure.d @ 4841

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

Initial release

File size: 15.8 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 gobject.Closure;
22
23private import gi.gobject;
24public  import gi.gobjecttypes;
25private import glib.ConstructionException;
26private import glib.Source;
27private import gobject.ObjectG;
28private import gobject.Value;
29
30
31/**
32 * A #GClosure represents a callback supplied by the programmer. It
33 * will generally comprise a function of some kind and a marshaller
34 * used to call it. It is the responsibility of the marshaller to
35 * convert the arguments for the invocation from #GValues into
36 * a suitable form, perform the callback on the converted arguments,
37 * and transform the return value back into a #GValue.
38 *
39 * In the case of C programs, a closure usually just holds a pointer
40 * to a function and maybe a data argument, and the marshaller
41 * converts between #GValue and native C types. The GObject
42 * library provides the #GCClosure type for this purpose. Bindings for
43 * other languages need marshallers which convert between #GValue<!--
44 * -->s and suitable representations in the runtime of the language in
45 * order to use functions written in that languages as callbacks.
46 *
47 * Within GObject, closures play an important role in the
48 * implementation of signals. When a signal is registered, the
49 * @c_marshaller argument to g_signal_new() specifies the default C
50 * marshaller for any closure which is connected to this
51 * signal. GObject provides a number of C marshallers for this
52 * purpose, see the g_cclosure_marshal_*() functions. Additional C
53 * marshallers can be generated with the [glib-genmarshal][glib-genmarshal]
54 * utility.  Closures can be explicitly connected to signals with
55 * g_signal_connect_closure(), but it usually more convenient to let
56 * GObject create a closure automatically by using one of the
57 * g_signal_connect_*() functions which take a callback function/user
58 * data pair.
59 *
60 * Using closures has a number of important advantages over a simple
61 * callback function/data pointer combination:
62 *
63 * - Closures allow the callee to get the types of the callback parameters,
64 * which means that language bindings don't have to write individual glue
65 * for each callback type.
66 *
67 * - The reference counting of #GClosure makes it easy to handle reentrancy
68 * right; if a callback is removed while it is being invoked, the closure
69 * and its parameters won't be freed until the invocation finishes.
70 *
71 * - g_closure_invalidate() and invalidation notifiers allow callbacks to be
72 * automatically removed when the objects they point to go away.
73 */
74public class Closure
75{
76        /** the main Gtk struct */
77        protected GClosure* gClosure;
78        protected bool ownedRef;
79
80        /** Get the main Gtk struct */
81        public GClosure* getClosureStruct()
82        {
83                return gClosure;
84        }
85
86        /** the main Gtk struct as a void* */
87        protected void* getStruct()
88        {
89                return cast(void*)gClosure;
90        }
91
92        /**
93         * Sets our main struct and passes it to the parent class.
94         */
95        public this (GClosure* gClosure, bool ownedRef = false)
96        {
97                this.gClosure = gClosure;
98                this.ownedRef = ownedRef;
99        }
100
101
102        /** */
103        public static GType getType()
104        {
105                return g_closure_get_type();
106        }
107
108        /**
109         * A variant of g_closure_new_simple() which stores @object in the
110         * @data field of the closure and calls g_object_watch_closure() on
111         * @object and the created closure. This function is mainly useful
112         * when implementing new types of closures.
113         *
114         * Params:
115         *     sizeofClosure = the size of the structure to allocate, must be at least
116         *         `sizeof (GClosure)`
117         *     object = a #GObject pointer to store in the @data field of the newly
118         *         allocated #GClosure
119         *
120         * Returns: a newly allocated #GClosure
121         *
122         * Throws: ConstructionException GTK+ fails to create the object.
123         */
124        public this(uint sizeofClosure, ObjectG object)
125        {
126                auto p = g_closure_new_object(sizeofClosure, (object is null) ? null : object.getObjectGStruct());
127               
128                if(p is null)
129                {
130                        throw new ConstructionException("null returned by new_object");
131                }
132               
133                this(cast(GClosure*) p);
134        }
135
136        /**
137         * Allocates a struct of the given size and initializes the initial
138         * part as a #GClosure. This function is mainly useful when
139         * implementing new types of closures.
140         *
141         * |[<!-- language="C" -->
142         * typedef struct _MyClosure MyClosure;
143         * struct _MyClosure
144         * {
145         * GClosure closure;
146         * // extra data goes here
147         * };
148         *
149         * static void
150         * my_closure_finalize (gpointer  notify_data,
151         * GClosure *closure)
152         * {
153         * MyClosure *my_closure = (MyClosure *)closure;
154         *
155         * // free extra data here
156         * }
157         *
158         * MyClosure *my_closure_new (gpointer data)
159         * {
160         * GClosure *closure;
161         * MyClosure *my_closure;
162         *
163         * closure = g_closure_new_simple (sizeof (MyClosure), data);
164         * my_closure = (MyClosure *) closure;
165         *
166         * // initialize extra data here
167         *
168         * g_closure_add_finalize_notifier (closure, notify_data,
169         * my_closure_finalize);
170         * return my_closure;
171         * }
172         * ]|
173         *
174         * Params:
175         *     sizeofClosure = the size of the structure to allocate, must be at least
176         *         `sizeof (GClosure)`
177         *     data = data to store in the @data field of the newly allocated #GClosure
178         *
179         * Returns: a newly allocated #GClosure
180         *
181         * Throws: ConstructionException GTK+ fails to create the object.
182         */
183        public this(uint sizeofClosure, void* data)
184        {
185                auto p = g_closure_new_simple(sizeofClosure, data);
186               
187                if(p is null)
188                {
189                        throw new ConstructionException("null returned by new_simple");
190                }
191               
192                this(cast(GClosure*) p);
193        }
194
195        /**
196         * Registers a finalization notifier which will be called when the
197         * reference count of @closure goes down to 0. Multiple finalization
198         * notifiers on a single closure are invoked in unspecified order. If
199         * a single call to g_closure_unref() results in the closure being
200         * both invalidated and finalized, then the invalidate notifiers will
201         * be run before the finalize notifiers.
202         *
203         * Params:
204         *     notifyData = data to pass to @notify_func
205         *     notifyFunc = the callback function to register
206         */
207        public void addFinalizeNotifier(void* notifyData, GClosureNotify notifyFunc)
208        {
209                g_closure_add_finalize_notifier(gClosure, notifyData, notifyFunc);
210        }
211
212        /**
213         * Registers an invalidation notifier which will be called when the
214         * @closure is invalidated with g_closure_invalidate(). Invalidation
215         * notifiers are invoked before finalization notifiers, in an
216         * unspecified order.
217         *
218         * Params:
219         *     notifyData = data to pass to @notify_func
220         *     notifyFunc = the callback function to register
221         */
222        public void addInvalidateNotifier(void* notifyData, GClosureNotify notifyFunc)
223        {
224                g_closure_add_invalidate_notifier(gClosure, notifyData, notifyFunc);
225        }
226
227        /**
228         * Adds a pair of notifiers which get invoked before and after the
229         * closure callback, respectively. This is typically used to protect
230         * the extra arguments for the duration of the callback. See
231         * g_object_watch_closure() for an example of marshal guards.
232         *
233         * Params:
234         *     preMarshalData = data to pass to @pre_marshal_notify
235         *     preMarshalNotify = a function to call before the closure callback
236         *     postMarshalData = data to pass to @post_marshal_notify
237         *     postMarshalNotify = a function to call after the closure callback
238         */
239        public void addMarshalGuards(void* preMarshalData, GClosureNotify preMarshalNotify, void* postMarshalData, GClosureNotify postMarshalNotify)
240        {
241                g_closure_add_marshal_guards(gClosure, preMarshalData, preMarshalNotify, postMarshalData, postMarshalNotify);
242        }
243
244        /**
245         * Sets a flag on the closure to indicate that its calling
246         * environment has become invalid, and thus causes any future
247         * invocations of g_closure_invoke() on this @closure to be
248         * ignored. Also, invalidation notifiers installed on the closure will
249         * be called at this point. Note that unless you are holding a
250         * reference to the closure yourself, the invalidation notifiers may
251         * unref the closure and cause it to be destroyed, so if you need to
252         * access the closure after calling g_closure_invalidate(), make sure
253         * that you've previously called g_closure_ref().
254         *
255         * Note that g_closure_invalidate() will also be called when the
256         * reference count of a closure drops to zero (unless it has already
257         * been invalidated before).
258         */
259        public void invalidate()
260        {
261                g_closure_invalidate(gClosure);
262        }
263
264        /**
265         * Invokes the closure, i.e. executes the callback represented by the @closure.
266         *
267         * Params:
268         *     returnValue = a #GValue to store the return
269         *         value. May be %NULL if the callback of @closure
270         *         doesn't return a value.
271         *     nParamValues = the length of the @param_values array
272         *     paramValues = an array of
273         *         #GValues holding the arguments on which to
274         *         invoke the callback of @closure
275         *     invocationHint = a context-dependent invocation hint
276         */
277        public void invoke(Value returnValue, Value[] paramValues, void* invocationHint)
278        {
279                GValue[] paramValuesArray = new GValue[paramValues.length];
280                for ( int i = 0; i < paramValues.length; i++ )
281                {
282                        paramValuesArray[i] = *(paramValues[i].getValueStruct());
283                }
284               
285                g_closure_invoke(gClosure, (returnValue is null) ? null : returnValue.getValueStruct(), cast(uint)paramValues.length, paramValuesArray.ptr, invocationHint);
286        }
287
288        /**
289         * Increments the reference count on a closure to force it staying
290         * alive while the caller holds a pointer to it.
291         *
292         * Returns: The @closure passed in, for convenience
293         */
294        public Closure doref()
295        {
296                auto p = g_closure_ref(gClosure);
297               
298                if(p is null)
299                {
300                        return null;
301                }
302               
303                return ObjectG.getDObject!(Closure)(cast(GClosure*) p);
304        }
305
306        /**
307         * Removes a finalization notifier.
308         *
309         * Notice that notifiers are automatically removed after they are run.
310         *
311         * Params:
312         *     notifyData = data which was passed to g_closure_add_finalize_notifier()
313         *         when registering @notify_func
314         *     notifyFunc = the callback function to remove
315         */
316        public void removeFinalizeNotifier(void* notifyData, GClosureNotify notifyFunc)
317        {
318                g_closure_remove_finalize_notifier(gClosure, notifyData, notifyFunc);
319        }
320
321        /**
322         * Removes an invalidation notifier.
323         *
324         * Notice that notifiers are automatically removed after they are run.
325         *
326         * Params:
327         *     notifyData = data which was passed to g_closure_add_invalidate_notifier()
328         *         when registering @notify_func
329         *     notifyFunc = the callback function to remove
330         */
331        public void removeInvalidateNotifier(void* notifyData, GClosureNotify notifyFunc)
332        {
333                g_closure_remove_invalidate_notifier(gClosure, notifyData, notifyFunc);
334        }
335
336        /**
337         * Sets the marshaller of @closure. The `marshal_data`
338         * of @marshal provides a way for a meta marshaller to provide additional
339         * information to the marshaller. (See g_closure_set_meta_marshal().) For
340         * GObject's C predefined marshallers (the g_cclosure_marshal_*()
341         * functions), what it provides is a callback function to use instead of
342         * @closure->callback.
343         *
344         * Params:
345         *     marshal = a #GClosureMarshal function
346         */
347        public void setMarshal(GClosureMarshal marshal)
348        {
349                g_closure_set_marshal(gClosure, marshal);
350        }
351
352        /**
353         * Sets the meta marshaller of @closure.  A meta marshaller wraps
354         * @closure->marshal and modifies the way it is called in some
355         * fashion. The most common use of this facility is for C callbacks.
356         * The same marshallers (generated by [glib-genmarshal][glib-genmarshal]),
357         * are used everywhere, but the way that we get the callback function
358         * differs. In most cases we want to use @closure->callback, but in
359         * other cases we want to use some different technique to retrieve the
360         * callback function.
361         *
362         * For example, class closures for signals (see
363         * g_signal_type_cclosure_new()) retrieve the callback function from a
364         * fixed offset in the class structure.  The meta marshaller retrieves
365         * the right callback and passes it to the marshaller as the
366         * @marshal_data argument.
367         *
368         * Params:
369         *     marshalData = context-dependent data to pass to @meta_marshal
370         *     metaMarshal = a #GClosureMarshal function
371         */
372        public void setMetaMarshal(void* marshalData, GClosureMarshal metaMarshal)
373        {
374                g_closure_set_meta_marshal(gClosure, marshalData, metaMarshal);
375        }
376
377        /**
378         * Takes over the initial ownership of a closure.  Each closure is
379         * initially created in a "floating" state, which means that the initial
380         * reference count is not owned by any caller. g_closure_sink() checks
381         * to see if the object is still floating, and if so, unsets the
382         * floating state and decreases the reference count. If the closure
383         * is not floating, g_closure_sink() does nothing. The reason for the
384         * existence of the floating state is to prevent cumbersome code
385         * sequences like:
386         * |[<!-- language="C" -->
387         * closure = g_cclosure_new (cb_func, cb_data);
388         * g_source_set_closure (source, closure);
389         * g_closure_unref (closure); // GObject doesn't really need this
390         * ]|
391         * Because g_source_set_closure() (and similar functions) take ownership of the
392         * initial reference count, if it is unowned, we instead can write:
393         * |[<!-- language="C" -->
394         * g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
395         * ]|
396         *
397         * Generally, this function is used together with g_closure_ref(). Ane example
398         * of storing a closure for later notification looks like:
399         * |[<!-- language="C" -->
400         * static GClosure *notify_closure = NULL;
401         * void
402         * foo_notify_set_closure (GClosure *closure)
403         * {
404         * if (notify_closure)
405         * g_closure_unref (notify_closure);
406         * notify_closure = closure;
407         * if (notify_closure)
408         * {
409         * g_closure_ref (notify_closure);
410         * g_closure_sink (notify_closure);
411         * }
412         * }
413         * ]|
414         *
415         * Because g_closure_sink() may decrement the reference count of a closure
416         * (if it hasn't been called on @closure yet) just like g_closure_unref(),
417         * g_closure_ref() should be called prior to this function.
418         */
419        public void sink()
420        {
421                g_closure_sink(gClosure);
422        }
423
424        /**
425         * Decrements the reference count of a closure after it was previously
426         * incremented by the same caller. If no other callers are using the
427         * closure, then the closure will be destroyed and freed.
428         */
429        public void unref()
430        {
431                g_closure_unref(gClosure);
432        }
433
434        /**
435         * Set the callback for a source as a #GClosure.
436         *
437         * If the source is not one of the standard GLib types, the @closure_callback
438         * and @closure_marshal fields of the #GSourceFuncs structure must have been
439         * filled in with pointers to appropriate functions.
440         *
441         * Params:
442         *     source = the source
443         *     closure = a #GClosure
444         */
445        public static void sourceSetClosure(Source source, Closure closure)
446        {
447                g_source_set_closure((source is null) ? null : source.getSourceStruct(), (closure is null) ? null : closure.getClosureStruct());
448        }
449
450        /**
451         * Sets a dummy callback for @source. The callback will do nothing, and
452         * if the source expects a #gboolean return value, it will return %TRUE.
453         * (If the source expects any other type of return value, it will return
454         * a 0/%NULL value; whatever g_value_init() initializes a #GValue to for
455         * that type.)
456         *
457         * If the source is not one of the standard GLib types, the
458         * @closure_callback and @closure_marshal fields of the #GSourceFuncs
459         * structure must have been filled in with pointers to appropriate
460         * functions.
461         *
462         * Params:
463         *     source = the source
464         */
465        public static void sourceSetDummyCallback(Source source)
466        {
467                g_source_set_dummy_callback((source is null) ? null : source.getSourceStruct());
468        }
469}
Note: See TracBrowser for help on using the repository browser.