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`

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

`is_invalid`

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

`marshal`

  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.