@c -*-texinfo-*-
@c This is part of the GNU G-Golf Reference Manual.
@c Copyright (C) 2019 Free Software Foundation, Inc.
@c See the file g-golf.texi for copying conditions.


@node Closures
@subsection Closures

G-Golf GObject Closures low level API.@*

Closures - Functions as first-class objects


@subheading Procedures

@indentedblock
@table @code
@item @ref{g-closure-size}
@item @ref{g-closure-ref-count}
@item @ref{g-closure-ref}
@item @ref{g-closure-sink}
@item @ref{g-closure-unref}
@item @ref{g-closure-free}
@item @ref{g-closure-invoke}
@item @ref{g-closure-add-invalidate-notifier}
@item @ref{g-closure-new-simple}
@item @ref{g-closure-set-marshal}
@item @ref{g-source-set-closure}
@end table
@end indentedblock


@c @subheading Types and Values

@c @indentedblock
@c @table @code
@c @item @ref{%g-signal-flags}
@c @end table
@c @end indentedblock


@subheading Object Hierarchy

@indentedblock
GBoxed           	       @*
@ @ +--- GClosure
@end indentedblock


@subheading Description

A @code{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 @code{GValues} into a suitable form,
perform the callback on the converted arguments, and transform the
return value back into a @code{GValue}.

Please read the @uref{@value{UGOBJECT-Closures}, Closures} section from
the GObject reference manual for a complete description.


@subheading Procedures


Note: in this section, the @var{closure}, @var{marshal}, @var{source}
and @var{function} arguments are [must be] pointers to a
@code{GClosure}, a @code{GSource}, a @code{GClosureMarshal} and
a @code{GClosureNotify} respectively.


@anchor{g-closure-size}
@deffn Procedure g-closure-size

Returns an integer.

Obtains and returns the size (the number of bytes) that a
@code{GClosure} occupies in memory.
@end deffn


@anchor{g-closure-ref-count}
@deffn Procedure g-closure-ref-count closure

Returns an integer.

Obtains and returns the reference count of @var{closure}.
@end deffn


@anchor{g-closure-ref}
@deffn Procedure g-closure-ref closure

Returns a pointer.

Increments the reference count of @var{closure}, to force it staying
alive while the caller holds a pointer to it.
@end deffn


@anchor{g-closure-sink}
@deffn Procedure g-closure-sink closure

Returns nothing.

Takes over the initial ownership of @var{closure}. Each closure is
initially created in a @samp{floating} state, which means that the
initial reference count is not owned by any caller. @ref{g-closure-sink}
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, @ref{g-closure-sink} does nothing.

Because @ref{g-closure-sink} may decrement the reference count of
@var{closure} (if it hasn't been called on closure yet) just like
@ref{g-closure-unref}, @ref{g-closure-ref} should be called prior to
this function.
@end deffn


@anchor{g-closure-unref}
@deffn Procedure g-closure-unref closure

Returns nothing.

Decrements the reference count of @var{closure} after it was previously
incremented by the same caller. If no other callers are using
@var{closure}closure, then it will be destroyed and freed.
@end deffn


@anchor{g-closure-free}
@deffn Procedure g-closure-free closure

Returns nothing.

Decrements the reference count of @var{closure} to 0 (so @var{closure}
will be destroyed and freed).
@end deffn


@anchor{g-closure-invoke}
@deffn Procedure g-closure-invoke closure return-value @
       n-param param-vals invocation-hit

Returns nothing.

Invokes the @var{closure}, i.e. executes the callback represented by the
closure.

The arguments are @var{closure} (a pointer to a @code{GClosure}),
@var{return-value} (a pointer to a @code{GValue}), @var{n-param} (the
length of the param-vals array), @var{param-vals} (a pointer to an array
of @code{GValue}) and @var{invocation-hint} (a context dependent
invocation hint).
@end deffn


@anchor{g-closure-add-invalidate-notifier}
@deffn Procedure g-closure-add-invalidate-notifier closure data @
       function

Returns nothing.

Registers an invalidation notifier which will be called when the closure
is invalidated with @code{g-closure-invalidate}. Invalidation notifiers
are invoked before finalization notifiers, in an unspecified order.

The @var{data} argumet is (must be) a pointer to the notifier data (or
#f).
@end deffn


@anchor{g-closure-new-simple}
@deffn Procedure g-closure-new-simple size data

Returns a pointer.

Allocates a structure of the given @var{size} and initializes the
initial part as a @code{GClosure}. The @var{data} (if any) are used to
iitialize the data fields of the newly allocated @code{GClosure}.

The returned value is a floating reference (a pointer) to a new
@code{GClosure}.
@end deffn


@anchor{g-closure-set-marshal}
@deffn Procedure g-closure-set-marshal closure marshal

Returns nothing.

Sets the @var{closure} marshaller to @var{marshal}.
@end deffn


@anchor{g-source-set-closure}
@deffn Procedure g-source-set-closure source closure

Returns nothing.

Set the @var{source} callback to @var{closure}.

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


@c @subheading Types and Values
