:right-sidebar: True Closure =================================================================== .. currentmodule:: gi.repository.GObject .. class:: Closure(*args, **kwargs) :no-contents-entry: :Constructors: :: Closure() new_object(sizeof_closure:int, object:GObject.Object) -> GObject.Closure new_simple(sizeof_closure:int, data=None) -> GObject.Closure Constructors ------------ .. rst-class:: interim-class .. class:: Closure :no-index: .. classmethod:: new_object(sizeof_closure: int, object: ~gi.repository.GObject.Object) -> ~typing.Callable[[...], ~typing.Any] A variant of :func:`~gi.repository.GObject.Closure.new_simple` which stores ``object`` in the ``data`` field of the closure and calls :func:`~gi.repository.GObject.Object.watch_closure` on ``object`` and the created closure. This function is mainly useful when implementing new types of closures. :param sizeof_closure: the size of the structure to allocate, must be at least `sizeof (GClosure)` :param object: a :obj:`~gi.repository.GObject.Object` pointer to store in the ``data`` field of the newly allocated :obj:`~gi.repository.GObject.Closure` .. classmethod:: new_simple(sizeof_closure: int, data: None) -> ~typing.Callable[[...], ~typing.Any] Allocates a struct of the given size and initializes the initial part as a :obj:`~gi.repository.GObject.Closure`. This function is mainly useful when implementing new types of closures: .. code-block:: C :dedent: 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; } :param sizeof_closure: the size of the structure to allocate, must be at least `sizeof (GClosure)` :param data: data to store in the ``data`` field of the newly allocated :obj:`~gi.repository.GObject.Closure` Methods ------- .. rst-class:: interim-class .. class:: Closure :no-index: .. method:: invalidate() -> None Sets a flag on the closure to indicate that its calling environment has become invalid, and thus causes any future invocations of :func:`~gi.repository.GObject.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 :func:`~gi.repository.GObject.Closure.invalidate`, make sure that you've previously called :func:`~gi.repository.GObject.Closure.ref`. Note that :func:`~gi.repository.GObject.Closure.invalidate` will also be called when the reference count of a closure drops to zero (unless it has already been invalidated before). .. method:: invoke(param_values: ~typing.Sequence[~typing.Any], invocation_hint: None) -> ~typing.Any Invokes the closure, i.e. executes the callback represented by the ``closure``. :param param_values: an array of :obj:`~gi.repository.GObject.Value` holding the arguments on which to invoke the callback of ``closure`` :param invocation_hint: a context-dependent invocation hint .. method:: sink() -> None 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, :func:`~gi.repository.GObject.Closure.sink` does nothing. The reason for the existence of the floating state is to prevent cumbersome code sequences like: .. code-block:: C :dedent: 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 :func:`~gi.repository.GObject.source_set_closure` (and similar functions) take ownership of the initial reference count, if it is unowned, we instead can write: .. code-block:: C :dedent: g_source_set_closure (source, g_cclosure_new (cb_func, cb_data)); Generally, this function is used together with :func:`~gi.repository.GObject.Closure.ref`. An example of storing a closure for later notification looks like: .. code-block:: C :dedent: 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 :func:`~gi.repository.GObject.Closure.sink` may decrement the reference count of a closure (if it hasn't been called on ``closure`` yet) just like :func:`~gi.repository.GObject.Closure.unref`, :func:`~gi.repository.GObject.Closure.ref` should be called prior to this function. Fields ------ .. rst-class:: interim-class .. class:: Closure :no-index: .. attribute:: data .. attribute:: derivative_flag .. attribute:: floating .. attribute:: in_inotify .. attribute:: in_marshal Indicates whether the closure is currently being invoked with :func:`~gi.repository.GObject.Closure.invoke` .. attribute:: is_invalid Indicates whether the closure has been invalidated by :func:`~gi.repository.GObject.Closure.invalidate` .. attribute:: marshal .. attribute:: meta_marshal_nouse .. attribute:: n_fnotifiers .. attribute:: n_guards .. attribute:: n_inotifiers .. attribute:: notifiers .. attribute:: ref_count