Package ch.bailu.gtk.gobject

Class Closure

java.lang.Object
ch.bailu.gtk.type.Type
ch.bailu.gtk.type.Pointer
ch.bailu.gtk.type.Record
ch.bailu.gtk.gobject.Closure
All Implemented Interfaces:
PointerInterface
public class Closure extends Record
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.

https://docs.gtk.org/gobject/struct.Closure.html

  • Field Details

  • Constructor Details

  • Method Details

    • getClassHandler

      public static ClassHandler getClassHandler()

    • getFieldRefCount

      public int getFieldRefCount()

    • getFieldMetaMarshalNouse

      public int getFieldMetaMarshalNouse()

    • getFieldNGuards

      public int getFieldNGuards()

    • getFieldNFnotifiers

      public int getFieldNFnotifiers()

    • getFieldNInotifiers

      public int getFieldNInotifiers()

    • getFieldInInotify

      public int getFieldInInotify()

    • getFieldFloating

      public int getFieldFloating()

    • getFieldDerivativeFlag

      public int getFieldDerivativeFlag()

    • setFieldInMarshal

      public void setFieldInMarshal(int in_marshal)
      Indicates whether the closure is currently being invoked with
      g_closure_invoke()

    • getFieldInMarshal

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

    • setFieldIsInvalid

      public void setFieldIsInvalid(int is_invalid)
      Indicates whether the closure has been invalidated by
      g_closure_invalidate()

    • getFieldIsInvalid

      public int getFieldIsInvalid()
      Indicates whether the closure has been invalidated by
      g_closure_invalidate()

    • setFieldMarshal

      public void setFieldMarshal(Closure.OnMarshal marshal)

      See Closure.OnMarshal.onMarshal(ch.bailu.gtk.lib.handler.CallbackHandler, ch.bailu.gtk.gobject.Closure, ch.bailu.gtk.gobject.Value, int, ch.bailu.gtk.gobject.Value, ch.bailu.gtk.type.Pointer, ch.bailu.gtk.type.Pointer)

    • getFieldMarshal

      public ch.bailu.gtk.gobject.JnaClosure.OnMarshal getFieldMarshal()

      See Closure.OnMarshal.onMarshal(ch.bailu.gtk.lib.handler.CallbackHandler, ch.bailu.gtk.gobject.Closure, ch.bailu.gtk.gobject.Value, int, ch.bailu.gtk.gobject.Value, ch.bailu.gtk.type.Pointer, ch.bailu.gtk.type.Pointer)

    • getFieldData

      public Pointer getFieldData()

    • getFieldNotifiers

      public ClosureNotifyData getFieldNotifiers()

    • newObjectClosure

      public static Closure newObjectClosure(int sizeof_closure, @Nonnull Object 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.
      Parameters:
      sizeof_closure - the size of the structure to allocate, must be at least `sizeof (GClosure)`
      object - a #GObject pointer to store in the @data field of the newly allocated #GClosure
      Returns:
      a newly allocated #GClosure

    • newSimpleClosure

      public static Closure newSimpleClosure(int sizeof_closure, @Nullable Pointer data)
      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: 
      <!-- language="C" -->
 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;
 }
      Parameters:
      sizeof_closure - the size of the structure to allocate, must be at least `sizeof (GClosure)`
      data - data to store in the @data field of the newly allocated #GClosure
      Returns:
      a floating reference to a new #GClosure

    • addFinalizeNotifier

      public void addFinalizeNotifier(@Nullable Pointer notify_data, Closure.OnClosureNotify notify_func)
      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.
      Parameters:
      notify_data - data to pass to @notify_func
      notify_func - the callback function to register

    • addInvalidateNotifier

      public void addInvalidateNotifier(@Nullable Pointer notify_data, Closure.OnClosureNotify notify_func)
      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.
      Parameters:
      notify_data - data to pass to @notify_func
      notify_func - the callback function to register

    • addMarshalGuards

      public void addMarshalGuards(@Nullable Pointer pre_marshal_data, Closure.OnClosureNotify pre_marshal_notify, @Nullable Pointer post_marshal_data, Closure.OnClosureNotify post_marshal_notify)
      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.
      Parameters:
      pre_marshal_data - data to pass to @pre_marshal_notify
      pre_marshal_notify - a function to call before the closure callback
      post_marshal_data - data to pass to @post_marshal_notify
      post_marshal_notify - a function to call after the closure callback

    • invalidate

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

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

    • ref

      public Closure ref()
      Increments the reference count on a closure to force it staying
      alive while the caller holds a pointer to it.
      Returns:
      The @closure passed in, for convenience

    • removeFinalizeNotifier

      public void removeFinalizeNotifier(@Nullable Pointer notify_data, Closure.OnClosureNotify notify_func)
      Removes a finalization notifier.

      Notice that notifiers are automatically removed after they are run.
      Parameters:
      notify_data - data which was passed to g_closure_add_finalize_notifier() when registering @notify_func
      notify_func - the callback function to remove

    • removeInvalidateNotifier

      public void removeInvalidateNotifier(@Nullable Pointer notify_data, Closure.OnClosureNotify notify_func)
      Removes an invalidation notifier.

      Notice that notifiers are automatically removed after they are run.
      Parameters:
      notify_data - data which was passed to g_closure_add_invalidate_notifier() when registering @notify_func
      notify_func - the callback function to remove

    • sink

      public void sink()
      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: 
      <!-- language="C" -->
 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: 
      <!-- language="C" -->
 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: 
      <!-- language="C" -->
 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.

    • unref

      public void unref()
      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.

    • getTypeID

      public static long getTypeID()

    • getParentTypeID

      public static long getParentTypeID()

    • getTypeSize

      public static TypeSystem.TypeSize getTypeSize()

    • getParentTypeSize

      public static TypeSystem.TypeSize getParentTypeSize()

    • getInstanceSize

      public static int getInstanceSize()