Closure

open class Closure : ClosureProtocol

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 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.

The Closure type acts as a reference-counted owner of an underlying GClosure instance. It provides the methods that can operate on this data type through ClosureProtocol conformance. Use Closure as a strong reference or owner of a GClosure instance.

  • ptr
    Untyped pointer to the underlying `GClosure` instance.
    

    For type-safe access, use the generated, typed pointer closure_ptr property instead.

    Declaration

    Swift

    public let ptr: UnsafeMutableRawPointer!
  • Designated initialiser from the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the Closure instance.

    Declaration

    Swift

    @inlinable
    public init(_ op: UnsafeMutablePointer<GClosure>)

    Parameters

    op

    pointer to the underlying object

  • Designated initialiser from a constant pointer to the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the Closure instance.

    Declaration

    Swift

    @inlinable
    public init(_ op: UnsafePointer<GClosure>)

    Parameters

    op

    pointer to the underlying object

  • Optional initialiser from a non-mutating gpointer to the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the Closure instance.

    Declaration

    Swift

    @inlinable
    public init!(gpointer op: gpointer?)

    Parameters

    op

    gpointer to the underlying object

  • Optional initialiser from a non-mutating gconstpointer to the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the Closure instance.

    Declaration

    Swift

    @inlinable
    public init!(gconstpointer op: gconstpointer?)

    Parameters

    op

    pointer to the underlying object

  • Optional initialiser from a constant pointer to the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the Closure instance.

    Declaration

    Swift

    @inlinable
    public init!(_ op: UnsafePointer<GClosure>?)

    Parameters

    op

    pointer to the underlying object

  • Optional initialiser from the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the Closure instance.

    Declaration

    Swift

    @inlinable
    public init!(_ op: UnsafeMutablePointer<GClosure>?)

    Parameters

    op

    pointer to the underlying object

  • Designated initialiser from the underlying C data type. Will retain GClosure. i.e., ownership is transferred to the Closure instance.

    Declaration

    Swift

    @inlinable
    public init(retaining op: UnsafeMutablePointer<GClosure>)

    Parameters

    op

    pointer to the underlying object

  • Reference intialiser for a related type that implements ClosureProtocol Will retain GClosure.

    Declaration

    Swift

    @inlinable
    public init<T>(_ other: T) where T : ClosureProtocol

    Parameters

    other

    an instance of a related type that implements ClosureProtocol

  • Unsafe typed initialiser. Do not use unless you know the underlying data type the pointer points to conforms to ClosureProtocol.

    Declaration

    Swift

    @inlinable
    public init<T>(cPointer p: UnsafeMutablePointer<T>)

    Parameters

    cPointer

    pointer to the underlying object

  • Unsafe typed, retaining initialiser. Do not use unless you know the underlying data type the pointer points to conforms to ClosureProtocol.

    Declaration

    Swift

    @inlinable
    public init<T>(retainingCPointer cPointer: UnsafeMutablePointer<T>)

    Parameters

    cPointer

    pointer to the underlying object

  • Unsafe untyped initialiser. Do not use unless you know the underlying data type the pointer points to conforms to ClosureProtocol.

    Declaration

    Swift

    @inlinable
    public init(raw p: UnsafeRawPointer)

    Parameters

    p

    raw pointer to the underlying object

  • Unsafe untyped, retaining initialiser. Do not use unless you know the underlying data type the pointer points to conforms to ClosureProtocol.

    Declaration

    Swift

    @inlinable
    public init(retainingRaw raw: UnsafeRawPointer)
  • Unsafe untyped initialiser. Do not use unless you know the underlying data type the pointer points to conforms to ClosureProtocol.

    Declaration

    Swift

    @inlinable
    public required init(raw p: UnsafeMutableRawPointer)

    Parameters

    p

    mutable raw pointer to the underlying object

  • Unsafe untyped, retaining initialiser. Do not use unless you know the underlying data type the pointer points to conforms to ClosureProtocol.

    Declaration

    Swift

    @inlinable
    public init(retainingRaw raw: UnsafeMutableRawPointer)

    Parameters

    raw

    mutable raw pointer to the underlying object

  • Unsafe untyped initialiser. Do not use unless you know the underlying data type the pointer points to conforms to ClosureProtocol.

    Declaration

    Swift

    @inlinable
    public init(opaquePointer p: OpaquePointer)

    Parameters

    p

    opaque pointer to the underlying object

  • Unsafe untyped, retaining initialiser. Do not use unless you know the underlying data type the pointer points to conforms to ClosureProtocol.

    Declaration

    Swift

    @inlinable
    public init(retainingOpaquePointer p: OpaquePointer)

    Parameters

    p

    opaque pointer to the underlying 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.

    Declaration

    Swift

    @inlinable
    public init<ObjectT>(object sizeofClosure: Int, object: ObjectT) where ObjectT : ObjectProtocol
  • Allocates a struct of the given size and initializes the initial part as a GClosure.

    This function is mainly useful when implementing new types of closures:

    (C Language Example):

    typedef struct _MyClosure MyClosure;
    struct _MyClosure
    {
      GClosure closure;
      // extra data goes here
    };
    
    static void
    my_closure_finalize (gpointer  notify_data,
                         GClosure *closure)
    {
      MyClosure *my_closure = (MyClosure *)closure;
    
      // free extra data here
    }
    
    MyClosure *my_closure_new (gpointer data)
    {
      GClosure *closure;
      MyClosure *my_closure;
    
      closure = g_closure_new_simple (sizeof (MyClosure), data);
      my_closure = (MyClosure *) closure;
    
      // initialize extra data here
    
      g_closure_add_finalize_notifier (closure, notify_data,
                                       my_closure_finalize);
      return my_closure;
    }
    

    Declaration

    Swift

    @inlinable
    public init(simple sizeofClosure: Int, data: gpointer? = nil)
  • 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.

    Declaration

    Swift

    @inlinable
    public static func new<ObjectT>(object sizeofClosure: Int, object: ObjectT) -> GLibObject.Closure! where ObjectT : ObjectProtocol
  • Allocates a struct of the given size and initializes the initial part as a GClosure.

    This function is mainly useful when implementing new types of closures:

    (C Language Example):

    typedef struct _MyClosure MyClosure;
    struct _MyClosure
    {
      GClosure closure;
      // extra data goes here
    };
    
    static void
    my_closure_finalize (gpointer  notify_data,
                         GClosure *closure)
    {
      MyClosure *my_closure = (MyClosure *)closure;
    
      // free extra data here
    }
    
    MyClosure *my_closure_new (gpointer data)
    {
      GClosure *closure;
      MyClosure *my_closure;
    
      closure = g_closure_new_simple (sizeof (MyClosure), data);
      my_closure = (MyClosure *) closure;
    
      // initialize extra data here
    
      g_closure_add_finalize_notifier (closure, notify_data,
                                       my_closure_finalize);
      return my_closure;
    }
    

    Declaration

    Swift

    @inlinable
    public static func new(simple sizeofClosure: Int, data: gpointer? = nil) -> GLibObject.Closure!