* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General
- * Public License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
- * Boston, MA 02111-1307, USA.
+ * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
*/
/*
*
* 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 reponsibility of the marshaller to
- * convert the arguments for the invocation from #GValue<!-- -->s into
+ * 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
+ * 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 #GValue<!--
* -->s and suitable representations in the runtime of the language in
* 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 <link
- * linkend="glib-genmarshal">glib-genmarshal</link> utility. Closures
- * can be explicitly connected to signals with
+ * 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
*
* Using closures has a number of important advantages over a simple
* callback function/data pointer combination:
- * <itemizedlist>
- * <listitem><para>
- * 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.
- * </para></listitem>
- * <listitem><para>
- * 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.
- * </para></listitem>
- * <listitem><para>
- * g_closure_invalidate() and invalidation notifiers allow callbacks to be
- * automatically removed when the objects they point to go away.
- * </para></listitem>
- * </itemizedlist>
+ *
+ * - 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.
*/
#define CLOSURE_MAX_REF_COUNT ((1 << 15) - 1)
/**
* g_closure_new_simple:
* @sizeof_closure: the size of the structure to allocate, must be at least
- * <literal>sizeof (GClosure)</literal>
+ * `sizeof (GClosure)`
* @data: data to store in the @data field of the newly allocated #GClosure
*
* 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
* {
* Sets the meta marshaller of @closure. A meta marshaller wraps
* @closure->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 <link
- * linkend="glib-genmarshal">glib-genmarshal</link>) are used
- * everywhere, but the way that we get the callback function
+ * The same marshallers (generated by [glib-genmarshal][glib-genmarshal]),
+ * are used everywhere, but the way that we get the callback function
* differs. In most cases we want to use @closure->callback, but in
* other cases we want to use some different technique to retrieve the
* callback function.
* still being held
*
* Takes over the initial ownership of a closure. Each closure is
- * initially created in a <firstterm>floating</firstterm> 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. The reason for the existence of the floating state is to
- * prevent cumbersome code sequences like:
- * |[
+ * 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. 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); // XXX GObject doesn't really need this
+ * 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(). Ane example
* of storing a closure for later notification looks like:
- * |[
+ * |[<!-- language="C" -->
* static GClosure *notify_closure = NULL;
* void
* foo_notify_set_closure (GClosure *closure)
* doesn't return a value.
* @n_param_values: the length of the @param_values array
* @param_values: (array length=n_param_values): an array of
- * #GValue<!-- -->s holding the arguments on which to
+ * #GValues holding the arguments on which to
* invoke the callback of @closure
* @invocation_hint: (allow-none): a context-dependent invocation hint
*
* @closure: a #GClosure
* @marshal: a #GClosureMarshal function
*
- * Sets the marshaller of @closure. The <literal>marshal_data</literal>
+ * Sets the marshaller of @closure. The `marshal_data`
* of @marshal provides a way for a meta marshaller to provide additional
* information to the marshaller. (See g_closure_set_meta_marshal().) For
* GObject's C predefined marshallers (the g_cclosure_marshal_*()
* @return_gvalue: A #GValue to store the return value. May be %NULL
* if the callback of closure doesn't return a value.
* @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValue<!-- -->s holding the arguments
+ * @param_values: An array of #GValues holding the arguments
* on which to invoke the callback of closure.
* @invocation_hint: The invocation hint given as the last argument to
* g_closure_invoke().
* marshaller, see g_closure_set_marshal() and
* g_closure_set_meta_marshal()
*
- * A generic marshaller function implemented via <ulink
- * url="http://sourceware.org/libffi/">libffi</ulink>.
+ * A generic marshaller function implemented via
+ * [libffi](http://sourceware.org/libffi/).
+ *
+ * Normally this function is not passed explicitly to g_signal_new(),
+ * but used automatically by GLib when specifying a %NULL marshaller.
*
* Since: 2.30
*/
args = g_alloca (sizeof (gpointer) * n_args);
storage = g_alloca (sizeof (va_arg_storage) * n_params);
- if (tmpval_used)
- enum_tmpval = g_alloca (sizeof (gint));
-
if (G_CCLOSURE_SWAP_DATA (closure))
{
atypes[n_args-1] = &ffi_type_pointer;
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, gpointer user_data)`.
*/
/**
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`.
*/
/**
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, gchar arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`.
*/
/**
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, guchar arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`.
*/
/**
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)`.
*/
/**
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, guint arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, guint arg1, gpointer user_data)`.
*/
/**
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, glong arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, glong arg1, gpointer user_data)`.
*/
/**
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, gulong arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`.
*/
/**
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes an enumeration type..
+ * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type..
*/
/**
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes a flags type.
+ * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type.
*/
/**
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`.
*/
/**
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`.
*/
/**
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`.
*/
/**
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`.
*/
/**
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`.
*/
/**
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`.
*/
/**
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`.
*/
/**
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`.
*
* Since: 2.26
*/
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`.
*/
/**
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter
+ * `gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter
* denotes a flags type.
*/
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)</literal>.
+ * `gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`.
*/
/**
* g_cclosure_marshal_BOOLEAN__OBJECT_BOXED_BOXED:
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * <literal>gboolean (*callback) (gpointer instance, GBoxed *arg1, GBoxed *arg2, gpointer user_data)</literal>.
+ * `gboolean (*callback) (gpointer instance, GBoxed *arg1, GBoxed *arg2, gpointer user_data)`.
*
* Since: 2.26
*/
projects / platform / upstream / glib.git / blobdiff