docs/reference/gobject/tmpl/gclosure.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Closures
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Functions as first-class objects
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 A #GClosure represents a callback supplied by the programmer. It will generally
  10 comprise a function of some kind and a marshaller used to call it. It is the
  11 reponsibility of the marshaller to convert the arguments for the invocation
  12 from #GValue<!-- -->s into a suitable form, perform the callback on the
  13 converted arguments, and transform the return value back into a #GValue.
  14 </para>
  15 <para>
  16 In the case of C programs, a closure usually just holds a pointer to a function
  17 and maybe a data argument, and the marshaller converts between #GValue<!-- -->
  18 and native C types. The GObject library provides the #GCClosure type for this
  19 purpose. Bindings for other languages need marshallers which
  20 convert between #GValue<!-- -->s and suitable representations in the runtime
  21 of the language in order to use functions written in that languages as
  22 callbacks.
  23 </para>
  24 <para>
  25 Within GObject, closures play an important role in the implementation of
  26 signals. When a signal is registered, the @c_marshaller argument to
  27 g_signal_new() specifies the default C marshaller for any closure which is
  28 connected to this signal. GObject provides a number of C marshallers
  29 for this purpose, see the g_cclosure_marshal_*() functions. Additional
  30 C marshallers can be generated with the <link linkend="glib-genmarshal"
  31 >glib-genmarshal</link> utility.
  32 Closures can be explicitly connected to signals with
  33 g_signal_connect_closure(), but it usually more convenient to let GObject
  34 create a closure automatically by using one of the g_signal_connect_*()
  35 functions which take a callback function/user data pair.
  36 </para>
  37 <para>
  38 Using closures has a number of important advantages over a simple
  39 callback function/data pointer combination:
  40 <itemizedlist>
  41 <listitem><para>
  42 Closures allow the callee to get the types of the callback parameters,
  43 which means that language bindings don't have to write individual glue
  44 for each callback type.
  45 </para></listitem>
  46 <listitem><para>
  47 The reference counting of #GClosure makes it easy to handle reentrancy
  48 right; if a callback is removed while it is being invoked, the closure
  49 and it's parameters won't be freed until the invocation finishes.
  50 </para></listitem>
  51 <listitem><para>
  52 g_closure_invalidate() and invalidation notifiers allow callbacks to be
  53 automatically removed when the objects they point to go away.
  54 </para></listitem>
  55 </itemizedlist>
  56 </para>
  57
  58 <!-- ##### SECTION See_Also ##### -->
  59 <para>
  60
  61 </para>
  62
  63 <!-- ##### SECTION Stability_Level ##### -->
  64
  65
  66 <!-- ##### MACRO G_CLOSURE_NEEDS_MARSHAL ##### -->
  67 <para>
  68 Returns %TRUE if a #GClosureMarshal marshaller has not yet been set on
  69 @closure. See g_closure_set_marshal().
  70 </para>
  71
  72 @closure: a #GClosure
  73
  74
  75 <!-- ##### MACRO G_CLOSURE_N_NOTIFIERS ##### -->
  76 <para>
  77 Returns the total number of notifiers connected with the closure @cl.
  78 The count includes the meta marshaller, the finalize and invalidate notifiers
  79 and the marshal guards. Note that each guard counts as two notifiers.
  80 See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(),
  81 g_closure_add_invalidate_notifier() and g_closure_add_marshal_guards().
  82 </para>
  83
  84 @cl: a #GClosure
  85
  86
  87 <!-- ##### MACRO G_CCLOSURE_SWAP_DATA ##### -->
  88 <para>
  89 Returns whether the user data of the #GCClosure should be passed as the
  90 first parameter to the callback. See g_cclosure_new_swap().
  91 </para>
  92
  93 @cclosure: a #GCClosure
  94
  95
  96 <!-- ##### MACRO G_CALLBACK ##### -->
  97 <para>
  98 Cast a function pointer to a #GCallback.
  99 </para>
 100
 101 @f: a function pointer.
 102
 103
 104 <!-- ##### USER_FUNCTION GCallback ##### -->
 105 <para>
 106 The type used for callback functions in structure definitions and function
 107 signatures. This doesn't mean that all callback functions must take no
 108 parameters and return void. The required signature of a callback function
 109 is determined by the context in which is used (e.g. the signal to which it
 110 is connected). Use G_CALLBACK() to cast the callback function to a #GCallback.
 111 </para>
 112
 113
 114
 115 <!-- ##### STRUCT GClosure ##### -->
 116 <para>
 117 A #GClosure represents a callback supplied by the programmer.
 118 </para>
 119
 120 @in_marshal: Indicates whether the closure is currently being invoked with
 121   g_closure_invoke()
 122 @is_invalid: Indicates whether the closure has been invalidated by
 123   g_closure_invalidate()
 124
 125 <!-- ##### MACRO G_TYPE_CLOSURE ##### -->
 126 <para>
 127 The #GType for #GClosure.
 128 </para>
 129
 130
 131
 132 <!-- ##### STRUCT GCClosure ##### -->
 133 <para>
 134 A #GCClosure is a specialization of #GClosure for C function callbacks.
 135 </para>
 136
 137 @closure: the #GClosure
 138 @callback: the callback function
 139
 140 <!-- ##### USER_FUNCTION GClosureMarshal ##### -->
 141 <para>
 142 The type used for marshaller functions.
 143 </para>
 144
 145 @closure: the #GClosure to which the marshaller belongs
 146 @return_value: a #GValue to store the return value. May be %NULL if the
 147   callback of @closure doesn't return a value.
 148 @n_param_values: the length of the @param_values array
 149 @param_values: an array of #GValue<!-- -->s holding the arguments on
 150   which to invoke the callback of @closure
 151 @invocation_hint: the invocation hint given as the the last argument
 152   to g_closure_invoke()
 153 @marshal_data: additional data specified when registering the marshaller,
 154   see g_closure_set_marshal() and g_closure_set_meta_marshal()
 155
 156
 157 <!-- ##### USER_FUNCTION GClosureNotify ##### -->
 158 <para>
 159 The type used for the various notification callbacks which can be registered
 160 on closures.
 161 </para>
 162
 163 @data: data specified when registering the notification callback
 164 @closure: the #GClosure on which the notification is emitted
 165
 166
 167 <!-- ##### FUNCTION g_cclosure_new ##### -->
 168 <para>
 169 Creates a new closure which invokes @callback_func with @user_data as
 170 the last parameter.
 171 </para>
 172
 173 @callback_func: the function to invoke
 174 @user_data: user data to pass to @callback_func
 175 @destroy_data: destroy notify to be called when @user_data is no longer used
 176 @Returns: a new #GCClosure
 177
 178
 179 <!-- ##### FUNCTION g_cclosure_new_swap ##### -->
 180 <para>
 181 Creates a new closure which invokes @callback_func with @user_data as
 182 the first parameter.
 183 </para>
 184
 185 @callback_func: the function to invoke
 186 @user_data: user data to pass to @callback_func
 187 @destroy_data: destroy notify to be called when @user_data is no longer used
 188 @Returns: a new #GCClosure
 189
 190
 191 <!-- ##### FUNCTION g_cclosure_new_object ##### -->
 192 <para>
 193 A variant of g_cclosure_new() which uses @object as @user_data and calls
 194 g_object_watch_closure() on @object and the created closure. This function
 195 is useful when you have a callback closely associated with a #GObject,
 196 and want the callback to no longer run after the object is is freed.
 197 </para>
 198
 199 @callback_func: the function to invoke
 200 @object: a #GObject pointer to pass to @callback_func
 201 @Returns: a new #GCClosure
 202
 203
 204 <!-- ##### FUNCTION g_cclosure_new_object_swap ##### -->
 205 <para>
 206 A variant of g_cclosure_new_swap() which uses @object as @user_data and calls
 207 g_object_watch_closure() on @object and the created closure. This function
 208 is useful when you have a callback closely associated with a #GObject,
 209 and want the callback to no longer run after the object is is freed.
 210 </para>
 211
 212 @callback_func: the function to invoke
 213 @object: a #GObject pointer to pass to @callback_func
 214 @Returns: a new #GCClosure
 215
 216
 217 <!-- ##### FUNCTION g_closure_new_object ##### -->
 218 <para>
 219 A variant of g_closure_new_simple() which stores @object in the @data
 220 field of the closure and calls g_object_watch_closure() on @object and the
 221 created closure. This function is mainly useful when implementing new types
 222 of closures.
 223 </para>
 224
 225 @sizeof_closure: the size of the structure to allocate, must be at least
 226 <literal>sizeof (GClosure)</literal>
 227 @object: a #GObject pointer to store in the @data field of the newly
 228   allocated #GClosure
 229 @Returns: a newly allocated #GClosure
 230
 231
 232 <!-- ##### FUNCTION g_closure_ref ##### -->
 233 <para>
 234 Increments the reference count on a closure to force it staying
 235 alive while the caller holds a pointer to it.
 236 </para>
 237
 238 @closure: #GClosure to increment the reference count on
 239 @Returns: The @closure passed in, for convenience
 240
 241
 242 <!-- ##### FUNCTION g_closure_sink ##### -->
 243 <para>
 244 Takes over the initial ownership of a closure.
 245 Each closure is initially created in a<firstterm>floating</firstterm> state,
 246 which means that the initial reference count is not owned by any caller.
 247 g_closure_sink() checks to see if the object is still floating, and if so,
 248 unsets the floating state and decreases the reference count. If the closure
 249 is not floating, g_closure_sink() does nothing. The reason for the existance
 250 of the floating state is to prevent cumbersome code sequences like:
 251 <programlisting>
 252 closure = g_cclosure_new (cb_func, cb_data);
 253 g_source_set_closure (source, closure);
 254 g_closure_unref (closure); /* XXX GObject doesn't really need this */
 255 </programlisting>
 256 Because g_source_set_closure() (and similar functions) take ownership of the
 257 initial reference count, if it is unowned, we instead can write:
 258 <programlisting>
 259 g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
 260 </programlisting>
 261 </para>
 262 <para>
 263 Generally, this function is used together with g_closure_ref(). Ane example
 264 of storing a closure for later notification looks like:
 265 <informalexample><programlisting>
 266 static GClosure *notify_closure = NULL;
 267 void
 268 foo_notify_set_closure (GClosure *closure)
 269 {
 270   if (notify_closure)
 271     g_closure_unref (notify_closure);
 272   notify_closure = closure;
 273   if (notify_closure)
 274     {
 275       g_closure_ref (notify_closure);
 276       g_closure_sink (notify_closure);
 277     }
 278 }
 279 </programlisting></informalexample>
 280 </para>
 281 <para>
 282 Because g_closure_sink() may decrement the reference count of a closure
 283 (if it hasn't been called on @closure yet) just like g_closure_unref(),
 284 g_closure_ref() should be called prior to this function.
 285 </para>
 286
 287 @closure: #GClosure to decrement the initial reference count on, if it's
 288           still being held
 289
 290
 291 <!-- ##### FUNCTION g_closure_unref ##### -->
 292 <para>
 293 Decrements the reference count of a closure after it was previously
 294 incremented by the same caller. If no other callers are using the closure,
 295 then the closure will be destroyed and freed.
 296 </para>
 297
 298 @closure: #GClosure to decrement the reference count on
 299
 300
 301 <!-- ##### FUNCTION g_closure_invoke ##### -->
 302 <para>
 303 Invokes the closure, i.e. executes the callback represented by the @closure.
 304 </para>
 305
 306 @closure: a #GClosure
 307 @return_value: a #GValue to store the return value. May be %NULL if the
 308   callback of @closure doesn't return a value.
 309 @n_param_values: the length of the @param_values array
 310 @param_values: an array of #GValue<!-- -->s holding the arguments on
 311   which to invoke the callback of @closure
 312 @invocation_hint: a context-dependent invocation hint
 313
 314
 315 <!-- ##### FUNCTION g_closure_invalidate ##### -->
 316 <para>
 317 Sets a flag on the closure to indicate that it's calling environment has
 318 become invalid, and thus causes any future invocations of g_closure_invoke()
 319 on this @closure to be ignored. Also, invalidation notifiers installed on
 320 the closure will be called at this point. Note that unless you are holding
 321 a reference to the closure yourself, the invalidation notifiers may unref
 322 the closure and cause it to be destroyed, so if you need to access the
 323 closure after calling g_closure_invalidate(), make sure that you've
 324 previously called g_closure_ref().
 325 </para>
 326 <para>
 327 Note that g_closure_invalidate() will also be called when the reference count
 328 of a closure drops to zero (unless it has already been invalidated before).
 329 </para>
 330
 331 @closure: GClosure to invalidate
 332
 333
 334 <!-- ##### FUNCTION g_closure_add_finalize_notifier ##### -->
 335 <para>
 336 Registers a finalization notifier which will be called when the reference
 337 count of @closure goes down to 0. Multiple finalization notifiers on a
 338 single closure are invoked in unspecified order. If a single call to
 339 g_closure_unref() results in the closure being both invalidated and
 340 finalized, then the invalidate notifiers will be run before the finalize
 341 notifiers.
 342 </para>
 343
 344 @closure: a #GClosure
 345 @notify_data: data to pass to @notify_func
 346 @notify_func: the callback function to register
 347
 348
 349 <!-- ##### FUNCTION g_closure_add_invalidate_notifier ##### -->
 350 <para>
 351 Registers an invalidation notifier which will be called when the @closure
 352 is invalidated with g_closure_invalidate(). Invalidation notifiers are
 353 invoked before finalization notifiers, in an unspecified order.
 354 </para>
 355
 356 @closure: a #GClosure
 357 @notify_data: data to pass to @notify_func
 358 @notify_func: the callback function to register
 359
 360
 361 <!-- ##### FUNCTION g_closure_remove_finalize_notifier ##### -->
 362 <para>
 363 Removes a finalization notifier. Notifiers are automatically removed after
 364 they are run.
 365 </para>
 366
 367 @closure: a #GClosure
 368 @notify_data: data which was passed to g_closure_add_finalize_notifier()
 369  when registering @notify_func
 370 @notify_func: the callback function to remove
 371
 372
 373 <!-- ##### FUNCTION g_closure_remove_invalidate_notifier ##### -->
 374 <para>
 375 Removes a invalidation notifier. Notifiers are automatically removed after
 376 they are run.
 377 </para>
 378
 379 @closure: a #GClosure
 380 @notify_data: data which was passed to g_closure_add_invalidate_notifier()
 381  when registering @notify_func
 382 @notify_func: the callback function to remove
 383
 384
 385 <!-- ##### FUNCTION g_closure_new_simple ##### -->
 386 <para>
 387 Allocates a struct of the given size and initializes the initial part
 388 as a #GClosure. This function is mainly useful when implementing new types
 389 of closures.
 390 </para>
 391 <informalexample>
 392 <programlisting>
 393 typedef struct _MyClosure MyClosure;
 394 struct _MyClosure
 395 {
 396   GClosure closure;
 397   /* extra data goes here */
 398 };
 399
 400
 401 static void
 402 my_closure_finalize (gpointer  notify_data,
 403                      GClosure *closure)
 404 {
 405   MyClosure *my_closure = (MyClosure *)closure;
 406
 407   /* free extra data here */
 408 }
 409
 410 MyClosure *my_closure_new (gpointer data)
 411 {
 412   GClosure *closure;
 413   MyClosure *my_closure;
 414
 415   closure = g_closure_new_simple (sizeof (MyClosure), data);
 416   my_closure = (MyClosure *) closure;
 417
 418   / initialize extra data here */
 419
 420   g_closure_add_finalize_notifier (closure, notify_data,
 421                                    my_closure_finalize);
 422   return my_closure;
 423 }
 424 </programlisting>
 425 </informalexample>
 426
 427 @sizeof_closure: the size of the structure to allocate, must be at least
 428 <literal>sizeof (GClosure)</literal>
 429 @data: data to store in the @data field of the newly allocated #GClosure
 430 @Returns: a newly allocated #GClosure
 431
 432
 433 <!-- ##### FUNCTION g_closure_set_marshal ##### -->
 434 <para>
 435 Sets the marshaller of @closure. The @marshal_data provides a way for a
 436 meta marshaller to provide additional information to the marshaller.
 437 (See g_closure_set_meta_marshal().) For GObject's C predefined marshallers
 438 (the g_cclosure_marshal_*() functions), what it provides is a callback
 439 function to use instead of @closure->callback.
 440 </para>
 441
 442 @closure: a #GClosure
 443 @marshal: a #GClosureMarshal function
 444
 445
 446 <!-- ##### FUNCTION g_closure_add_marshal_guards ##### -->
 447 <para>
 448 Adds a pair of notifiers which get invoked before and after the closure
 449 callback, respectively. This is typically used to protect the extra arguments
 450 for the duration of the callback. See g_object_watch_closure() for an
 451 example of marshal guards.
 452 </para>
 453
 454 @closure: a #GClosure
 455 @pre_marshal_data: data to pass to @pre_marshal_notify
 456 @pre_marshal_notify: a function to call before the closure callback
 457 @post_marshal_data: data to pass to @post_marshal_notify
 458 @post_marshal_notify: a function to call after the closure callback
 459
 460
 461 <!-- ##### FUNCTION g_closure_set_meta_marshal ##### -->
 462 <para>
 463 Sets the meta marshaller of @closure.
 464 A meta marshaller wraps @closure->marshal and modifies the way it is called
 465 in some fashion. The most common use of this facility is for C callbacks.
 466 The same marshallers (generated by
 467 <link linkend="glib-genmarshal">glib-genmarshal</link>) are used everywhere,
 468 but the way that we get the callback function differs. In most cases we want
 469 to use @closure->callback, but in other cases we want to use use some
 470 different technique to retrieve the callbakc function.
 471 </para>
 472 <para>
 473 For example, class closures for signals (see g_signal_type_cclosure_new())
 474 retrieve the callback function from a fixed offset in the class structure.
 475 The meta marshaller retrieves the right callback and passes it to the
 476 marshaller as the @marshal_data argument.
 477 </para>
 478
 479 @closure: a #GClosure
 480 @marshal_data: context-dependent data to pass to @meta_marshal
 481 @meta_marshal: a #GClosureMarshal function
 482
 483
 484 <!-- ##### FUNCTION g_source_set_closure ##### -->
 485 <para>
 486 Set the callback for a source as a #GClosure.
 487 </para>
 488 <para>
 489 If the source is not one of the standard GLib types, the @closure_callback
 490 and @closure_marshal fields of the GSourceFuncs structure must have been
 491 filled in with pointers to appropriate functions.
 492 </para>
 493
 494 @source: the source
 495 @closure: a #GClosure
 496
 497
 498 <!-- ##### MACRO G_TYPE_IO_CHANNEL ##### -->
 499 <para>
 500 The #GType for #GIOChannel.
 501 </para>
 502
 503
 504
 505 <!-- ##### MACRO G_TYPE_IO_CONDITION ##### -->
 506 <para>
 507 The #GType for #GIOCondition.
 508 </para>
 509
 510
 511
 512 <!-- ##### FUNCTION g_cclosure_marshal_VOID__VOID ##### -->
 513 <para>
 514 A marshaller for a #GCClosure with a callback of type
 515 <literal>void (*callback) (gpointer instance, gpointer user_data)</literal>.
 516 </para>
 517
 518 @closure: the #GClosure to which the marshaller belongs
 519 @return_value: ignored
 520 @n_param_values: 1
 521 @param_values: a #GValue array holding only the instance
 522 @invocation_hint: the invocation hint given as the the last argument
 523   to g_closure_invoke()
 524 @marshal_data: additional data specified when registering the marshaller
 525
 526
 527 <!-- ##### FUNCTION g_cclosure_marshal_VOID__BOOLEAN ##### -->
 528 <para>
 529 A marshaller for a #GCClosure with a callback of type
 530 <literal>void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)</literal>.
 531 </para>
 532
 533 @closure: the #GClosure to which the marshaller belongs
 534 @return_value: ignored
 535 @n_param_values: 2
 536 @param_values: a #GValue array holding the instance and the #gboolean parameter
 537 @invocation_hint: the invocation hint given as the the last argument
 538   to g_closure_invoke()
 539 @marshal_data: additional data specified when registering the marshaller
 540
 541
 542 <!-- ##### FUNCTION g_cclosure_marshal_VOID__CHAR ##### -->
 543 <para>
 544 A marshaller for a #GCClosure with a callback of type
 545 <literal>void (*callback) (gpointer instance, gchar arg1, gpointer user_data)</literal>.
 546 </para>
 547
 548 @closure: the #GClosure to which the marshaller belongs
 549 @return_value: ignored
 550 @n_param_values: 2
 551 @param_values: a #GValue array holding the instance and the #gchar parameter
 552 @invocation_hint: the invocation hint given as the the last argument
 553   to g_closure_invoke()
 554 @marshal_data: additional data specified when registering the marshaller
 555
 556
 557 <!-- ##### FUNCTION g_cclosure_marshal_VOID__UCHAR ##### -->
 558 <para>
 559 A marshaller for a #GCClosure with a callback of type
 560 <literal>void (*callback) (gpointer instance, guchar arg1, gpointer user_data)</literal>.
 561 </para>
 562
 563 @closure: the #GClosure to which the marshaller belongs
 564 @return_value: ignored
 565 @n_param_values: 2
 566 @param_values: a #GValue array holding the instance and the #guchar parameter
 567 @invocation_hint: the invocation hint given as the the last argument
 568   to g_closure_invoke()
 569 @marshal_data: additional data specified when registering the marshaller
 570
 571
 572 <!-- ##### FUNCTION g_cclosure_marshal_VOID__INT ##### -->
 573 <para>
 574 A marshaller for a #GCClosure with a callback of type
 575 <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal>.
 576 </para>
 577
 578 @closure: the #GClosure to which the marshaller belongs
 579 @return_value: ignored
 580 @n_param_values: 2
 581 @param_values: a #GValue array holding the instance and the #gint parameter
 582 @invocation_hint: the invocation hint given as the the last argument
 583   to g_closure_invoke()
 584 @marshal_data: additional data specified when registering the marshaller
 585
 586
 587 <!-- ##### FUNCTION g_cclosure_marshal_VOID__UINT ##### -->
 588 <para>
 589 A marshaller for a #GCClosure with a callback of type
 590 <literal>void (*callback) (gpointer instance, guint arg1, gpointer user_data)</literal>.
 591 </para>
 592
 593 @closure: the #GClosure to which the marshaller belongs
 594 @return_value: ignored
 595 @n_param_values: 2
 596 @param_values: a #GValue array holding the instance and the #guint parameter
 597 @invocation_hint: the invocation hint given as the the last argument
 598   to g_closure_invoke()
 599 @marshal_data: additional data specified when registering the marshaller
 600
 601
 602 <!-- ##### FUNCTION g_cclosure_marshal_VOID__LONG ##### -->
 603 <para>
 604 A marshaller for a #GCClosure with a callback of type
 605 <literal>void (*callback) (gpointer instance, glong arg1, gpointer user_data)</literal>.
 606 </para>
 607
 608 @closure: the #GClosure to which the marshaller belongs
 609 @return_value: ignored
 610 @n_param_values: 2
 611 @param_values: a #GValue array holding the instance and the #glong parameter
 612 @invocation_hint: the invocation hint given as the the last argument
 613   to g_closure_invoke()
 614 @marshal_data: additional data specified when registering the marshaller
 615
 616
 617 <!-- ##### FUNCTION g_cclosure_marshal_VOID__ULONG ##### -->
 618 <para>
 619 A marshaller for a #GCClosure with a callback of type
 620 <literal>void (*callback) (gpointer instance, gulong arg1, gpointer user_data)</literal>.
 621 </para>
 622
 623 @closure: the #GClosure to which the marshaller belongs
 624 @return_value: ignored
 625 @n_param_values: 2
 626 @param_values: a #GValue array holding the instance and the #gulong parameter
 627 @invocation_hint: the invocation hint given as the the last argument
 628   to g_closure_invoke()
 629 @marshal_data: additional data specified when registering the marshaller
 630
 631
 632 <!-- ##### FUNCTION g_cclosure_marshal_VOID__ENUM ##### -->
 633 <para>
 634 A marshaller for a #GCClosure with a callback of type
 635 <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes an enumeration type..
 636 </para>
 637
 638 @closure: the #GClosure to which the marshaller belongs
 639 @return_value: ignored
 640 @n_param_values: 2
 641 @param_values: a #GValue array holding the instance and the enumeration parameter
 642 @invocation_hint: the invocation hint given as the the last argument
 643   to g_closure_invoke()
 644 @marshal_data: additional data specified when registering the marshaller
 645
 646
 647 <!-- ##### FUNCTION g_cclosure_marshal_VOID__FLAGS ##### -->
 648 <para>
 649 A marshaller for a #GCClosure with a callback of type
 650 <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes a flags type
 651 denotes a flags type.
 652 </para>
 653
 654 @closure: the #GClosure to which the marshaller belongs
 655 @return_value: ignored
 656 @n_param_values: 2
 657 @param_values: a #GValue array holding the instance and the flags parameter
 658 @invocation_hint: the invocation hint given as the the last argument
 659   to g_closure_invoke()
 660 @marshal_data: additional data specified when registering the marshaller
 661
 662
 663 <!-- ##### FUNCTION g_cclosure_marshal_VOID__FLOAT ##### -->
 664 <para>
 665 A marshaller for a #GCClosure with a callback of type
 666 <literal>void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)</literal>.
 667 </para>
 668
 669 @closure: the #GClosure to which the marshaller belongs
 670 @return_value: ignored
 671 @n_param_values: 2
 672 @param_values: a #GValue array holding the instance and the #gfloat parameter
 673 @invocation_hint: the invocation hint given as the the last argument
 674   to g_closure_invoke()
 675 @marshal_data: additional data specified when registering the marshaller
 676
 677
 678 <!-- ##### FUNCTION g_cclosure_marshal_VOID__DOUBLE ##### -->
 679 <para>
 680 A marshaller for a #GCClosure with a callback of type
 681 <literal>void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)</literal>.
 682 </para>
 683
 684 @closure: the #GClosure to which the marshaller belongs
 685 @return_value: ignored
 686 @n_param_values: 2
 687 @param_values: a #GValue array holding the instance and the #gdouble parameter
 688 @invocation_hint: the invocation hint given as the the last argument
 689   to g_closure_invoke()
 690 @marshal_data: additional data specified when registering the marshaller
 691
 692
 693 <!-- ##### FUNCTION g_cclosure_marshal_VOID__STRING ##### -->
 694 <para>
 695 A marshaller for a #GCClosure with a callback of type
 696 <literal>void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)</literal>.
 697 </para>
 698
 699 @closure: the #GClosure to which the marshaller belongs
 700 @return_value: ignored
 701 @n_param_values: 2
 702 @param_values: a #GValue array holding the instance and the #gchar* parameter
 703 @invocation_hint: the invocation hint given as the the last argument
 704   to g_closure_invoke()
 705 @marshal_data: additional data specified when registering the marshaller
 706
 707
 708 <!-- ##### FUNCTION g_cclosure_marshal_VOID__PARAM ##### -->
 709 <para>
 710 A marshaller for a #GCClosure with a callback of type
 711 <literal>void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)</literal>.
 712 </para>
 713
 714 @closure: the #GClosure to which the marshaller belongs
 715 @return_value: ignored
 716 @n_param_values: 2
 717 @param_values: a #GValue array holding the instance and the #GParamSpec* parameter
 718 @invocation_hint: the invocation hint given as the the last argument
 719   to g_closure_invoke()
 720 @marshal_data: additional data specified when registering the marshaller
 721
 722
 723 <!-- ##### FUNCTION g_cclosure_marshal_VOID__BOXED ##### -->
 724 <para>
 725 A marshaller for a #GCClosure with a callback of type
 726 <literal>void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)</literal>.
 727 </para>
 728
 729 @closure: the #GClosure to which the marshaller belongs
 730 @return_value: ignored
 731 @n_param_values: 2
 732 @param_values: a #GValue array holding the instance and the #GBoxed* parameter
 733 @invocation_hint: the invocation hint given as the the last argument
 734   to g_closure_invoke()
 735 @marshal_data: additional data specified when registering the marshaller
 736
 737
 738 <!-- ##### FUNCTION g_cclosure_marshal_VOID__POINTER ##### -->
 739 <para>
 740 A marshaller for a #GCClosure with a callback of type
 741 <literal>void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)</literal>.
 742 </para>
 743
 744 @closure: the #GClosure to which the marshaller belongs
 745 @return_value: ignored
 746 @n_param_values: 2
 747 @param_values: a #GValue array holding the instance and the #gpointer parameter
 748 @invocation_hint: the invocation hint given as the the last argument
 749   to g_closure_invoke()
 750 @marshal_data: additional data specified when registering the marshaller
 751
 752
 753 <!-- ##### FUNCTION g_cclosure_marshal_VOID__OBJECT ##### -->
 754 <para>
 755 A marshaller for a #GCClosure with a callback of type
 756 <literal>void (*callback) (gpointer instance, GOBject *arg1, gpointer user_data)</literal>.
 757 </para>
 758
 759 @closure: the #GClosure to which the marshaller belongs
 760 @return_value: ignored
 761 @n_param_values: 2
 762 @param_values: a #GValue array holding the instance and the #GObject* parameter
 763 @invocation_hint: the invocation hint given as the the last argument
 764   to g_closure_invoke()
 765 @marshal_data: additional data specified when registering the marshaller
 766
 767
 768 <!-- ##### FUNCTION g_cclosure_marshal_STRING__OBJECT_POINTER ##### -->
 769 <para>
 770 A marshaller for a #GCClosure with a callback of type
 771 <literal>void (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)</literal>.
 772 </para>
 773
 774 @closure: the #GClosure to which the marshaller belongs
 775 @return_value: ignored
 776 @n_param_values: 3
 777 @param_values: a #GValue array holding instance, arg1 and arg2
 778 @invocation_hint: the invocation hint given as the the last argument
 779   to g_closure_invoke()
 780 @marshal_data: additional data specified when registering the marshaller
 781
 782
 783 <!-- ##### FUNCTION g_cclosure_marshal_VOID__UINT_POINTER ##### -->
 784 <para>
 785 A marshaller for a #GCClosure with a callback of type
 786 <literal>void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)</literal>.
 787 </para>
 788
 789 @closure: the #GClosure to which the marshaller belongs
 790 @return_value: ignored
 791 @n_param_values: 3
 792 @param_values: a #GValue array holding instance, arg1 and arg2
 793 @invocation_hint: the invocation hint given as the the last argument
 794   to g_closure_invoke()
 795 @marshal_data: additional data specified when registering the marshaller
 796
 797
 798 <!-- ##### FUNCTION g_cclosure_marshal_BOOLEAN__FLAGS ##### -->
 799 <para>
 800 A marshaller for a #GCClosure with a callback of type
 801 <literal>gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter
 802 denotes a flags type.
 803 </para>
 804
 805 @closure: the #GClosure to which the marshaller belongs
 806 @return_value: a #GValue which can store the returned #gboolean
 807 @n_param_values: 2
 808 @param_values: a #GValue array holding instance and arg1
 809 @invocation_hint: the invocation hint given as the the last argument
 810   to g_closure_invoke()
 811 @marshal_data: additional data specified when registering the marshaller
 812
 813
 814 <!-- ##### MACRO g_cclosure_marshal_BOOL__FLAGS ##### -->
 815 <para>
 816 Another name for g_cclosure_marshal_BOOLEAN__FLAGS().
 817 </para>
 818
 819
 820