GObject.Closure
Description: Reference for GObject.Closure

### Struct

# GObjectClosure

#### Description [src]

    struct GClosure {
      guint in_marshal : 1;
      guint is_invalid : 1;
      void (* marshal) (
        GClosure* closure,
        GValue* return_value,
        guint n_param_values,
        const GValue* param_values,
        gpointer invocation_hint,
        gpointer marshal_data
      );;
    }

A `GClosure` 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 GValues into a suitable form, perform the callback on the converted arguments, and transform the return value back into a `GValue`.

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 `GValue` and native C types. The GObject library provides the `GCClosure` type for this purpose. Bindings for other languages need marshallers which convert between GValues and suitable representations in the runtime of the language in order to use functions written in that language as callbacks. Use `g_closure_set_marshal()` 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 `GClosure` 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.

- `g_closure_invalidate()` and invalidation notifiers allow callbacks to be automatically removed when the objects they point to go away.

###### Structure members

`in_marshal:` `guint`

  Indicates whether the closure is currently being invoked with g_closure_invoke().

`is_invalid:` `guint`

  Indicates whether the closure has been invalidated by g_closure_invalidate().

`marshal:` `void (* marshal) ( GClosure* closure, GValue* return_value, guint n_param_values, const GValue* param_values, gpointer invocation_hint, gpointer marshal_data )`

  No description available.

#### Constructors

###### g_closure_new_object

A variant of `g_closure_new_simple()` 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.

###### g_closure_new_simple

Allocates a struct of the given size and initializes the initial part as a `GClosure`.

#### Instance methods

###### g_closure_add_finalize_notifier

Registers a finalization notifier which will be called when the reference count of `closure` goes down to 0.

###### g_closure_add_invalidate_notifier

Registers an invalidation notifier which will be called when the `closure` is invalidated with g_closure_invalidate().

###### g_closure_add_marshal_guards

Adds a pair of notifiers which get invoked before and after the closure callback, respectively.

###### g_closure_invalidate

Sets a flag on the closure to indicate that its calling environment has become invalid, and thus causes any future invocations of `g_closure_invoke()` on this `closure` to be ignored.

###### g_closure_invoke

Invokes the closure, i.e. executes the callback represented by the `closure`.

###### g_closure_ref

Increments the reference count on a closure to force it staying alive while the caller holds a pointer to it.

###### g_closure_remove_finalize_notifier

Removes a finalization notifier.

###### g_closure_remove_invalidate_notifier

Removes an invalidation notifier.

###### g_closure_set_marshal

Sets the marshaller of `closure`.

###### g_closure_set_meta_marshal

Sets the meta marshaller of `closure`.

###### g_closure_sink

Takes over the initial ownership of a closure.

###### g_closure_unref

Decrements the reference count of a closure after it was previously incremented by the same caller.