Closures

G-Golf GObject Closures low level API.

Closures - Functions as first-class objects

Procedures

g-closure-size
g-closure-ref-count
g-closure-ref
g-closure-sink
g-closure-unref
g-closure-free
g-closure-invoke
g-closure-add-invalidate-notifier
g-closure-new-simple
g-closure-set-marshal
g-source-set-closure

Object Hierarchy

GBoxed
  +— GClosure

Description

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.

Please read the Closures section from the GObject reference manual for a complete description.

Procedures

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

Procedure: g-closure-size

Returns an integer.

Obtains and returns the size (the number of bytes) that a GClosure occupies in memory.

Procedure: g-closure-ref-count closure

Returns an integer.

Obtains and returns the reference count of closure.

Procedure: g-closure-ref closure

Returns a pointer.

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

Procedure: g-closure-sink closure

Returns nothing.

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

Because g-closure-sink may decrement the reference count of 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.

Procedure: g-closure-unref closure

Returns nothing.

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

Procedure: g-closure-free closure

Returns nothing.

Decrements the reference count of closure to 0 (so closure will be destroyed and freed).

Procedure: g-closure-invoke closure return-value n-param param-vals invocation-hit

Returns nothing.

Invokes the closure, i.e. executes the callback represented by the closure.

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

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 g-closure-invalidate. Invalidation notifiers are invoked before finalization notifiers, in an unspecified order.

The data argumet is (must be) a pointer to the notifier data (or #f).

Procedure: g-closure-new-simple size data

Returns a pointer.

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

The returned value is a floating reference (a pointer) to a new GClosure.

Procedure: g-closure-set-marshal closure marshal

Returns nothing.

Sets the closure marshaller to marshal.

Procedure: g-source-set-closure source closure

Returns nothing.

Set the source callback to closure.

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.