ClosureProtocol

public protocol 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 ClosureProtocol protocol exposes the methods and properties of an underlying GClosure instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Closure. Alternatively, use ClosureRef as a lighweight, unowned reference if you already have an instance you just want to use.

  • ptr

    Untyped pointer to the underlying GClosure instance.

    Declaration

    Swift

    var ptr: UnsafeMutableRawPointer! { get }
  • closure_ptr Default implementation

    Typed pointer to the underlying GClosure instance.

    Default Implementation

    Return the stored, untyped pointer as a typed pointer to the GClosure instance.

    Declaration

    Swift

    var closure_ptr: UnsafeMutablePointer<GClosure>! { get }
  • Required Initialiser for types conforming to ClosureProtocol

    Declaration

    Swift

    init(raw: UnsafeMutableRawPointer)

Closure Record: ClosureProtocol extension (methods and fields)

  • 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 g_closure_unref() results in the closure being both invalidated and finalized, then the invalidate notifiers will be run before the finalize notifiers.

    Declaration

    Swift

    @inlinable
    func addFinalizeNotifier(notifyData: gpointer? = nil, notifyFunc: GClosureNotify? = nil)
  • Registers an invalidation notifier which will be called when the closure is invalidated with g_closure_invalidate().

    Invalidation notifiers are invoked before finalization notifiers, in an unspecified order.

    Declaration

    Swift

    @inlinable
    func addInvalidateNotifier(notifyData: gpointer? = nil, notifyFunc: GClosureNotify? = nil)
  • 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.

    Declaration

    Swift

    @inlinable
    func addMarshalGuards(preMarshalData: gpointer? = nil, preMarshalNotify: GClosureNotify? = nil, postMarshalData: gpointer? = nil, postMarshalNotify: GClosureNotify? = nil)
  • invalidate() Extension method

    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.

    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 g_closure_invalidate(), make sure that you’ve previously called g_closure_ref().

    Note that g_closure_invalidate() will also be called when the reference count of a closure drops to zero (unless it has already been invalidated before).

    Declaration

    Swift

    @inlinable
    func invalidate()
  • Invokes the closure, i.e. executes the callback represented by the closure.

    Declaration

    Swift

    @inlinable
    func invoke(returnValue: ValueRef? = nil, nParamValues: Int, paramValues: UnsafePointer<GValue>!, invocationHint: gpointer? = nil)
  • Invokes the closure, i.e. executes the callback represented by the closure.

    Declaration

    Swift

    @inlinable
    func invoke<ValueT>(returnValue: ValueT?, nParamValues: Int, paramValues: UnsafePointer<GValue>!, invocationHint: gpointer? = nil) where ValueT : ValueProtocol
  • ref() Extension method

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

    Declaration

    Swift

    @discardableResult
    @inlinable
    func ref() -> GLibObject.ClosureRef!
  • Removes a finalization notifier.

    Notice that notifiers are automatically removed after they are run.

    Declaration

    Swift

    @inlinable
    func removeFinalizeNotifier(notifyData: gpointer? = nil, notifyFunc: GClosureNotify?)
  • Removes an invalidation notifier.

    Notice that notifiers are automatically removed after they are run.

    Declaration

    Swift

    @inlinable
    func removeInvalidateNotifier(notifyData: gpointer? = nil, notifyFunc: GClosureNotify?)
  • set(marshal:) Extension method

    Sets the marshaller of closure.

    The marshal_data of marshal provides a way for a meta marshaller to provide additional information to the marshaller.

    For GObject’s C predefined marshallers (the g_cclosure_marshal_*() functions), what it provides is a callback function to use instead of closure->callback.

    See also: g_closure_set_meta_marshal()

    Declaration

    Swift

    @inlinable
    func set(marshal: @escaping GClosureMarshal)
  • Sets the meta marshaller of closure.

    A meta marshaller wraps the closure‘s 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), are used everywhere, but the way that we get the callback function differs. In most cases we want to use the closure’s callback, but in other cases we want to use some different technique to retrieve the callback function.

    For example, class closures for signals (see g_signal_type_cclosure_new()) retrieve the callback function from a fixed offset in the class structure. The meta marshaller retrieves the right callback and passes it to the marshaller as the marshal_data argument.

    Declaration

    Swift

    @inlinable
    func setMetaMarshal(marshalData: gpointer? = nil, metaMarshal: GClosureMarshal! = nil)
  • sink() Extension method

    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.

    This function 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, g_closure_sink() does nothing.

    The reason for the existence of the floating state is to prevent cumbersome code sequences like:

    (C Language Example):

    closure = g_cclosure_new (cb_func, cb_data);
    g_source_set_closure (source, closure);
    g_closure_unref (closure); // GObject doesn't really need this
    

    Because g_source_set_closure() (and similar functions) take ownership of the initial reference count, if it is unowned, we instead can write:

    (C Language Example):

    g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
    

    Generally, this function is used together with g_closure_ref(). An example of storing a closure for later notification looks like:

    (C Language Example):

    static GClosure *notify_closure = NULL;
    void
    foo_notify_set_closure (GClosure *closure)
    {
      if (notify_closure)
        g_closure_unref (notify_closure);
      notify_closure = closure;
      if (notify_closure)
        {
          g_closure_ref (notify_closure);
          g_closure_sink (notify_closure);
        }
    }
    

    Because g_closure_sink() may decrement the reference count of a closure (if it hasn’t been called on closure yet) just like g_closure_unref(), g_closure_ref() should be called prior to this function.

    Declaration

    Swift

    @inlinable
    func sink()
  • unref() Extension method

    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.

    Declaration

    Swift

    @inlinable
    func unref()
  • A GClosureMarshal function for use with signals with handlers that take two boxed pointers as arguments and return a boolean. If you have such a signal, you will probably also need to use an accumulator, such as g_signal_accumulator_true_handled().

    Declaration

    Swift

    @inlinable
    func cclosureMarshalBOOLEANBOXEDBOXED<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data) where the gint parameter denotes a flags type.

    Declaration

    Swift

    @inlinable
    func cclosureMarshalBOOLEANFLAGS<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data).

    Declaration

    Swift

    @inlinable
    func cclosureMarshalSTRINGOBJECTPOINTER<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type void (*callback) (gpointer instance, gboolean arg1, gpointer user_data).

    Declaration

    Swift

    @inlinable
    func cclosureMarshalVOIDBOOLEAN<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data).

    Declaration

    Swift

    @inlinable
    func cclosureMarshalVOIDBOXED<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type void (*callback) (gpointer instance, gchar arg1, gpointer user_data).

    Declaration

    Swift

    @inlinable
    func cclosureMarshalVOIDCHAR<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type void (*callback) (gpointer instance, gdouble arg1, gpointer user_data).

    Declaration

    Swift

    @inlinable
    func cclosureMarshalVOIDDOUBLE<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type void (*callback) (gpointer instance, gint arg1, gpointer user_data) where the gint parameter denotes an enumeration type..

    Declaration

    Swift

    @inlinable
    func cclosureMarshalVOIDENUM<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type void (*callback) (gpointer instance, gint arg1, gpointer user_data) where the gint parameter denotes a flags type.

    Declaration

    Swift

    @inlinable
    func cclosureMarshalVOIDFLAGS<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type void (*callback) (gpointer instance, gfloat arg1, gpointer user_data).

    Declaration

    Swift

    @inlinable
    func cclosureMarshalVOIDFLOAT<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type void (*callback) (gpointer instance, gint arg1, gpointer user_data).

    Declaration

    Swift

    @inlinable
    func cclosureMarshalVOIDINT<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type void (*callback) (gpointer instance, glong arg1, gpointer user_data).

    Declaration

    Swift

    @inlinable
    func cclosureMarshalVOIDLONG<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type void (*callback) (gpointer instance, GObject *arg1, gpointer user_data).

    Declaration

    Swift

    @inlinable
    func cclosureMarshalVOIDOBJECT<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data).

    Declaration

    Swift

    @inlinable
    func cclosureMarshalVOIDPARAM<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type void (*callback) (gpointer instance, gpointer arg1, gpointer user_data).

    Declaration

    Swift

    @inlinable
    func cclosureMarshalVOIDPOINTER<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data).

    Declaration

    Swift

    @inlinable
    func cclosureMarshalVOIDSTRING<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type void (*callback) (gpointer instance, guchar arg1, gpointer user_data).

    Declaration

    Swift

    @inlinable
    func cclosureMarshalVOIDUCHAR<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type void (*callback) (gpointer instance, guint arg1, gpointer user_data).

    Declaration

    Swift

    @inlinable
    func cclosureMarshalVOIDUINT<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data).

    Declaration

    Swift

    @inlinable
    func cclosureMarshalVOIDUINTPOINTER<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type void (*callback) (gpointer instance, gulong arg1, gpointer user_data).

    Declaration

    Swift

    @inlinable
    func cclosureMarshalVOIDULONG<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data).

    Declaration

    Swift

    @inlinable
    func cclosureMarshalVOIDVARIANT<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A marshaller for a GCClosure with a callback of type void (*callback) (gpointer instance, gpointer user_data).

    Declaration

    Swift

    @inlinable
    func cclosureMarshalVOIDVOID<ValueT>(returnValue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • A generic marshaller function implemented via libffi.

    Normally this function is not passed explicitly to g_signal_new(), but used automatically by GLib when specifying a nil marshaller.

    Declaration

    Swift

    @inlinable
    func cclosureMarshalGeneric<ValueT>(returnGvalue: ValueT, nParamValues: Int, paramValues: ValueT, invocationHint: gpointer? = nil, marshalData: gpointer? = nil) where ValueT : ValueProtocol
  • Connects a closure to a signal for a particular object.

    Declaration

    Swift

    @inlinable
    func signalConnectClosure<ObjectT>(instance: ObjectT, detailedSignal: UnsafePointer<gchar>!, after: Bool) -> Int where ObjectT : ObjectProtocol
  • Connects a closure to a signal for a particular object.

    Declaration

    Swift

    @inlinable
    func signalConnectClosureByID<ObjectT>(instance: ObjectT, signalID: Int, detail: GQuark, after: Bool) -> Int where ObjectT : ObjectProtocol
  • Finds the first signal handler that matches certain selection criteria. The criteria mask is passed as an OR-ed combination of GSignalMatchType flags, and the criteria values are passed as arguments. The match mask has to be non-0 for successful matches. If no handler was found, 0 is returned.

    Declaration

    Swift

    @inlinable
    func signalHandlerFind<ObjectT>(instance: ObjectT, mask: SignalMatchType, signalID: Int, detail: GQuark, func: gpointer? = nil, data: gpointer? = nil) -> Int where ObjectT : ObjectProtocol
  • Blocks all handlers on an instance that match a certain selection criteria. The criteria mask is passed as an OR-ed combination of GSignalMatchType flags, and the criteria values are passed as arguments. Passing at least one of the G_SIGNAL_MATCH_CLOSURE, G_SIGNAL_MATCH_FUNC or G_SIGNAL_MATCH_DATA match flags is required for successful matches. If no handlers were found, 0 is returned, the number of blocked handlers otherwise.

    Declaration

    Swift

    @inlinable
    func signalHandlersBlockMatched<ObjectT>(instance: ObjectT, mask: SignalMatchType, signalID: Int, detail: GQuark, func: gpointer? = nil, data: gpointer? = nil) -> Int where ObjectT : ObjectProtocol
  • Disconnects all handlers on an instance that match a certain selection criteria. The criteria mask is passed as an OR-ed combination of GSignalMatchType flags, and the criteria values are passed as arguments. Passing at least one of the G_SIGNAL_MATCH_CLOSURE, G_SIGNAL_MATCH_FUNC or G_SIGNAL_MATCH_DATA match flags is required for successful matches. If no handlers were found, 0 is returned, the number of disconnected handlers otherwise.

    Declaration

    Swift

    @inlinable
    func signalHandlersDisconnectMatched<ObjectT>(instance: ObjectT, mask: SignalMatchType, signalID: Int, detail: GQuark, func: gpointer? = nil, data: gpointer? = nil) -> Int where ObjectT : ObjectProtocol
  • Unblocks all handlers on an instance that match a certain selection criteria. The criteria mask is passed as an OR-ed combination of GSignalMatchType flags, and the criteria values are passed as arguments. Passing at least one of the G_SIGNAL_MATCH_CLOSURE, G_SIGNAL_MATCH_FUNC or G_SIGNAL_MATCH_DATA match flags is required for successful matches. If no handlers were found, 0 is returned, the number of unblocked handlers otherwise. The match criteria should not apply to any handlers that are not currently blocked.

    Declaration

    Swift

    @inlinable
    func signalHandlersUnblockMatched<ObjectT>(instance: ObjectT, mask: SignalMatchType, signalID: Int, detail: GQuark, func: gpointer? = nil, data: gpointer? = nil) -> Int where ObjectT : ObjectProtocol
  • Creates a new signal. (This is usually done in the class initializer.)

    See g_signal_new() for details on allowed signal names.

    If c_marshaller is nil, g_cclosure_marshal_generic() will be used as the marshaller for this signal.

    Declaration

    Swift

    @inlinable
    func signalNewValist(signalName: UnsafePointer<gchar>!, itype: GType, signalFlags: SignalFlags, accumulator: GSignalAccumulator! = nil, accuData: gpointer? = nil, cMarshaller: GSignalCMarshaller! = nil, returnType: GType, nParams: Int, args: CVaListPointer) -> Int
  • Creates a new signal. (This is usually done in the class initializer.)

    See g_signal_new() for details on allowed signal names.

    If c_marshaller is nil, g_cclosure_marshal_generic() will be used as the marshaller for this signal.

    Declaration

    Swift

    @inlinable
    func signalNewv(signalName: UnsafePointer<gchar>!, itype: GType, signalFlags: SignalFlags, accumulator: GSignalAccumulator! = nil, accuData: gpointer? = nil, cMarshaller: GSignalCMarshaller! = nil, returnType: GType, nParams: Int, paramTypes: UnsafeMutablePointer<GType>! = nil) -> Int
  • Overrides the class closure (i.e. the default handler) for the given signal for emissions on instances of instance_type. instance_type must be derived from the type to which the signal belongs.

    See g_signal_chain_from_overridden() and g_signal_chain_from_overridden_handler() for how to chain up to the parent class closure from inside the overridden one.

    Declaration

    Swift

    @inlinable
    func signalOverrideClassClosure(signalID: Int, instanceType: GType)
  • sourceSetClosure(source:) Extension method

    Set the callback for a source as a GClosure.

    If the source is not one of the standard GLib types, the closure_callback and closure_marshal fields of the GSourceFuncs structure must have been filled in with pointers to appropriate functions.

    Declaration

    Swift

    @inlinable
    func sourceSetClosure<GLibSourceT>(source: GLibSourceT) where GLibSourceT : SourceProtocol
  • inMarshal Extension method

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

    Declaration

    Swift

    @inlinable
    var inMarshal: guint { get set }
  • isInvalid Extension method

    Indicates whether the closure has been invalidated by g_closure_invalidate()

    Declaration

    Swift

    @inlinable
    var isInvalid: guint { get set }