Sets our main struct and passes it to the parent class.
A variant of Closure.newSimple which stores object in the data field of the closure and calls g_object_watch_closure() on object and the created closure. This function is mainly useful when implementing new types of closures.
Allocates a struct of the given size and initializes the initial part as a gobject.Closure This function is mainly useful when implementing new types of closures.
A destructor is present on this object, but not explicitly documented in the source.
Registers a finalization notifier which will be called when the reference count of closure goes down to 0. Multiple finalization notifiers on a single closure are invoked in unspecified order. If a single call to Closure.unref results in the closure being both invalidated and finalized, then the invalidate notifiers will be run before the finalize notifiers.
Registers an invalidation notifier which will be called when the closure is invalidated with Closure.invalidate. Invalidation notifiers are invoked before finalization notifiers, in an unspecified order.
Adds a pair of notifiers which get invoked before and after the closure callback, respectively. This is typically used to protect the extra arguments for the duration of the callback. See g_object_watch_closure() for an example of marshal guards.
Get the main Gtk struct
the main Gtk struct as a void*
Sets a flag on the closure to indicate that its calling environment has become invalid, and thus causes any future invocations of Closure.invoke on this closure to be ignored. Also, invalidation notifiers installed on the closure will be called at this point. Note that unless you are holding a reference to the closure yourself, the invalidation notifiers may unref the closure and cause it to be destroyed, so if you need to access the closure after calling Closure.invalidate, make sure that you've previously called Closure.ref.
Invokes the closure, i.e. executes the callback represented by the closure.
Increments the reference count on a closure to force it staying alive while the caller holds a pointer to it.
Removes a finalization notifier.
Removes an invalidation notifier.
Sets the marshaller of closure. The marshal_data of marshal provides a way for a meta marshaller to provide additional information to the marshaller. (See Closure.setMetaMarshal.) For GObject's C predefined marshallers (the g_cclosure_marshal_*() functions), what it provides is a callback function to use instead of closure->callback.
Sets the meta marshaller of closure. A meta marshaller wraps closure->marshal and modifies the way it is called in some fashion. The most common use of this facility is for C callbacks. The same marshallers (generated by [glib-genmarshal][glib-genmarshal]), are used everywhere, but the way that we get the callback function differs. In most cases we want to use closure->callback, but in other cases we want to use some different technique to retrieve the callback function.
Takes over the initial ownership of a closure. Each closure is initially created in a "floating" state, which means that the initial reference count is not owned by any caller. Closure.sink checks to see if the object is still floating, and if so, unsets the floating state and decreases the reference count. If the closure is not floating, Closure.sink does nothing. The reason for the existence of the floating state is to prevent cumbersome code sequences like:
Decrements the reference count of a closure after it was previously incremented by the same caller. If no other callers are using the closure, then the closure will be destroyed and freed.
Set the callback for a source as a gobject.Closure
Sets a dummy callback for source. The callback will do nothing, and if the source expects a gboolean return value, it will return TRUE. (If the source expects any other type of return value, it will return a 0/NULL value; whatever Value.init initializes a gobject.Value to for that type.)
the main Gtk struct
A gobject.Closure represents a callback supplied by the programmer. It will generally comprise a function of some kind and a marshaller used to call it. It is the responsibility of the marshaller to convert the arguments for the invocation from gobject.Values into a suitable form, perform the callback on the converted arguments, and transform the return value back into a gobject.Value
In the case of C programs, a closure usually just holds a pointer to a function and maybe a data argument, and the marshaller converts between gobject.Value and native C types. The GObject library provides the gobject.CClosure type for this purpose. Bindings for other languages need marshallers which convert between gobject.Values and suitable representations in the runtime of the language in order to use functions written in that language as callbacks. Use Closure.setMarshal to set the marshaller on such a custom closure implementation.
Within GObject, closures play an important role in the implementation of signals. When a signal is registered, the c_marshaller argument to g_signal_new() specifies the default C marshaller for any closure which is connected to this signal. GObject provides a number of C marshallers for this purpose, see the g_cclosure_marshal_*() functions. Additional C marshallers can be generated with the [glib-genmarshal][glib-genmarshal] utility. Closures can be explicitly connected to signals with g_signal_connect_closure(), but it usually more convenient to let GObject create a closure automatically by using one of the g_signal_connect_*() functions which take a callback function/user data pair.
Using closures has a number of important advantages over a simple callback function/data pointer combination:
- Closures allow the callee to get the types of the callback parameters, which means that language bindings don't have to write individual glue for each callback type.
- The reference counting of gobject.Closure makes it easy to handle reentrancy right; if a callback is removed while it is being invoked, the closure and its parameters won't be freed until the invocation finishes.
- Closure.invalidate and invalidation notifiers allow callbacks to be automatically removed when the objects they point to go away.