docs/reference/glib/tmpl/hooks.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Hook Functions
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 support for manipulating lists of hook functions.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GHookList, #GHook and their related functions provide support for
  10 lists of hook functions. Functions can be added and removed from the lists,
  11 and the list of hook functions can be invoked.
  12
  13 </para>
  14
  15 <!-- ##### SECTION See_Also ##### -->
  16 <para>
  17
  18 </para>
  19
  20 <!-- ##### STRUCT GHookList ##### -->
  21 <para>
  22
  23 <informaltable pgwide=1 frame="none" role="struct">
  24 <tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
  25 <tbody>
  26
  27 <row>
  28 <entry>#guint seq_id;</entry>
  29 <entry>the next free #GHook id.</entry>
  30 </row>
  31
  32 <row>
  33 <entry>#guint hook_size;</entry>
  34 <entry>the size of the #GHookList elements, in bytes.</entry>
  35 </row>
  36
  37 <row>
  38 <entry>#guint is_setup : 1;</entry>
  39 <entry>1 if the #GHookList has been initialized.</entry>
  40 </row>
  41
  42 <row>
  43 <entry>#GHook *hooks;</entry>
  44 <entry>the first #GHook element in the list.</entry>
  45 </row>
  46
  47 <row>
  48 <entry>#GMemChunk *hook_memchunk;</entry>
  49 <entry>the #GMemChunk used for allocating the #GHook elements.</entry>
  50 </row>
  51
  52 <row>
  53 <entry>#GHookFinalizeFunc finalize_hook;</entry>
  54 <entry>the function to call to finalize a #GHook element.
  55 The default behaviour is to call the hooks <function>destroy</function>
  56 function.</entry>
  57 </row>
  58
  59 </tbody></tgroup></informaltable>
  60
  61 </para>
  62
  63 @seq_id:
  64 @hook_size:
  65 @is_setup:
  66 @hooks:
  67 @hook_memchunk:
  68 @finalize_hook:
  69
  70
  71 <!-- ##### USER_FUNCTION GHookFinalizeFunc ##### -->
  72 <para>
  73 Defines the type of function to be called when a hook in a
  74 list of hooks gets finalized.
  75 </para>
  76
  77 @hook_list: a #GHookList.
  78 @hook: the hook in @hook_list that gets finalized.
  79
  80
  81 <!-- ##### STRUCT GHook ##### -->
  82 <para>
  83
  84 <informaltable pgwide=1 frame="none" role="struct">
  85 <tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
  86 <tbody>
  87
  88 <row>
  89 <entry>#gpointer data;</entry>
  90 <entry>data which is passed to func when this hook is invoked.</entry>
  91 </row>
  92
  93 <row>
  94 <entry>#GHook *next;</entry>
  95 <entry>pointer to the next hook in the list.</entry>
  96 </row>
  97
  98 <row>
  99 <entry>#GHook *prev;</entry>
 100 <entry>pointer to the previous hook in the list.</entry>
 101 </row>
 102
 103 <row>
 104 <entry>#guint ref_count;</entry>
 105 <entry>the reference count of this hook.</entry>
 106 </row>
 107
 108 <row>
 109 <entry>#guint hook_id;</entry>
 110 <entry>the id of this hook, which is unique within its list.</entry>
 111 </row>
 112
 113 <row>
 114 <entry>#guint flags;</entry>
 115 <entry>flags which are set for this hook. See #GHookFlagMask for
 116 predefined flags.</entry>
 117 </row>
 118
 119 <row>
 120 <entry>#gpointer func;</entry>
 121 <entry>the function to call when this hook is invoked. The possible
 122 signatures for this function are #GHookFunc and #GHookCheckFunc.</entry>
 123 </row>
 124
 125 <row>
 126 <entry>#GDestroyNotify destroy;</entry>
 127 <entry>the default <function>finalize_hook</function> function of a
 128 #GHookList calls this member of the hook that is being finalized.</entry>
 129 </row>
 130
 131 </tbody></tgroup></informaltable>
 132 </para>
 133
 134 @data:
 135 @next:
 136 @prev:
 137 @ref_count:
 138 @hook_id:
 139 @flags:
 140 @func:
 141 @destroy:
 142
 143 <!-- ##### USER_FUNCTION GHookFunc ##### -->
 144 <para>
 145 Defines the type of a hook function that can be invoked
 146 by g_hook_list_invoke().
 147 </para>
 148
 149 @data: the data field of the #GHook is passed to the hook function here.
 150
 151
 152 <!-- ##### USER_FUNCTION GHookCheckFunc ##### -->
 153 <para>
 154 Defines the type of a hook function that can be invoked
 155 by g_hook_list_invoke_check().
 156 </para>
 157
 158 @data: the data field of the #GHook is passed to the hook function here.
 159 @Returns: %FALSE if the #GHook should be destroyed.
 160
 161
 162 <!-- ##### FUNCTION g_hook_list_init ##### -->
 163 <para>
 164 Initializes a #GHookList.
 165 This must be called before the #GHookList is used.
 166 </para>
 167
 168 @hook_list: a #GHookList.
 169 @hook_size: the size of each element in the #GHookList, typically
 170 <literal>sizeof (GHook)</literal>.
 171
 172
 173 <!-- ##### FUNCTION g_hook_list_invoke ##### -->
 174 <para>
 175 Calls all of the #GHook functions in a #GHookList.
 176 </para>
 177
 178 @hook_list: a #GHookList.
 179 @may_recurse: %TRUE if functions which are already running (e.g. in another
 180 thread) can be called. If set to %FALSE, these are skipped.
 181
 182
 183 <!-- ##### FUNCTION g_hook_list_invoke_check ##### -->
 184 <para>
 185 Calls all of the #GHook functions in a #GHookList.
 186 Any function which returns %TRUE is removed from the #GHookList.
 187 </para>
 188
 189 @hook_list: a #GHookList.
 190 @may_recurse: %TRUE if functions which are already running (e.g. in another
 191 thread) can be called. If set to %FALSE, these are skipped.
 192
 193
 194 <!-- ##### FUNCTION g_hook_list_marshal ##### -->
 195 <para>
 196 Calls a function on each valid #GHook.
 197 </para>
 198
 199 @hook_list: a #GHookList.
 200 @may_recurse: %TRUE if hooks which are currently running (e.g. in another
 201 thread) are considered valid. If set to %FALSE, these are skipped.
 202 @marshaller: the function to call for each #GHook.
 203 @marshal_data: data to pass to @marshaller.
 204
 205
 206 <!-- ##### USER_FUNCTION GHookMarshaller ##### -->
 207 <para>
 208 Defines the type of function used by g_hook_list_marshal().
 209 </para>
 210
 211 @hook: a #GHook.
 212 @marshal_data: user data.
 213
 214
 215 <!-- ##### FUNCTION g_hook_list_marshal_check ##### -->
 216 <para>
 217 Calls a function on each valid #GHook and destroys it if the
 218 function returns %FALSE.
 219 </para>
 220
 221 @hook_list: a #GHookList.
 222 @may_recurse: %TRUE if hooks which are currently running (e.g. in another
 223 thread) are considered valid. If set to %FALSE, these are skipped.
 224 @marshaller: the function to call for each #GHook.
 225 @marshal_data: data to pass to @marshaller.
 226
 227
 228 <!-- ##### USER_FUNCTION GHookCheckMarshaller ##### -->
 229 <para>
 230 Defines the type of function used by g_hook_list_marshal_check().
 231 </para>
 232
 233 @hook: a #GHook.
 234 @marshal_data: user data.
 235 @Returns: %FALSE if @hook should be destroyed.
 236
 237
 238 <!-- ##### FUNCTION g_hook_list_clear ##### -->
 239 <para>
 240 Removes all the #GHook elements from a #GHookList.
 241 </para>
 242
 243 @hook_list: a #GHookList.
 244
 245
 246 <!-- ##### FUNCTION g_hook_alloc ##### -->
 247 <para>
 248 Allocates space for a #GHook and initializes it.
 249 </para>
 250
 251 @hook_list: a #GHookList.
 252 @Returns: a new #GHook.
 253
 254
 255 <!-- ##### MACRO g_hook_append ##### -->
 256 <para>
 257 Appends a #GHook onto the end of a #GHookList.
 258 </para>
 259
 260 @hook_list: a #GHookList.
 261 @hook: the #GHook to add to the end of @hook_list.
 262
 263
 264 <!-- ##### FUNCTION g_hook_prepend ##### -->
 265 <para>
 266 Prepends a #GHook on the start of a #GHookList.
 267 </para>
 268
 269 @hook_list: a #GHookList.
 270 @hook: the #GHook to add to the start of @hook_list.
 271
 272
 273 <!-- ##### FUNCTION g_hook_insert_before ##### -->
 274 <para>
 275 Inserts a #GHook into a #GHookList, before a given #GHook.
 276 </para>
 277
 278 @hook_list: a #GHookList.
 279 @sibling: the #GHook to insert the new #GHook before.
 280 @hook: the #GHook to insert.
 281
 282
 283 <!-- ##### FUNCTION g_hook_insert_sorted ##### -->
 284 <para>
 285 Inserts a #GHook into a #GHookList, sorted by the given function.
 286 </para>
 287
 288 @hook_list: a #GHookList.
 289 @hook: the #GHook to insert.
 290 @func: the comparison function used to sort the #GHook elements.
 291
 292
 293 <!-- ##### USER_FUNCTION GHookCompareFunc ##### -->
 294 <para>
 295 Defines the type of function used to compare #GHook elements in
 296 g_hook_insert_sorted().
 297 </para>
 298
 299 @new_hook: the #GHook being inserted.
 300 @sibling: the #GHook to compare with @new_hook.
 301 @Returns: a value <= 0 if @new_hook should be before @sibling.
 302
 303
 304 <!-- ##### FUNCTION g_hook_compare_ids ##### -->
 305 <para>
 306 Compares the ids of two #GHook elements, returning a negative value
 307 if the second id is greater than the first.
 308 </para>
 309
 310 @new_hook: a #GHook.
 311 @sibling: a #GHook to compare with @new_hook.
 312 @Returns: a value <= 0 if the id of @sibling is >= the id of @new_hook.
 313
 314
 315 <!-- ##### FUNCTION g_hook_get ##### -->
 316 <para>
 317 Returns the #GHook with the given id, or %NULL if it is not found.
 318 </para>
 319
 320 @hook_list: a #GHookList.
 321 @hook_id: a hook id.
 322 @Returns: the #GHook with the given id, or %NULL if it is not found.
 323
 324
 325 <!-- ##### FUNCTION g_hook_find ##### -->
 326 <para>
 327 Finds a #GHook in a #GHookList using the given function to test for a match.
 328 </para>
 329
 330 @hook_list: a #GHookList.
 331 @need_valids: %TRUE if #GHook elements which have been destroyed should be
 332 skipped.
 333 @func: the function to call for each #GHook, which should return %TRUE when
 334 the #GHook has been found.
 335 @data: the data to pass to @func.
 336 @Returns: the found #GHook or %NULL if no matching #GHook is found.
 337
 338
 339 <!-- ##### USER_FUNCTION GHookFindFunc ##### -->
 340 <para>
 341 Defines the type of the function passed to g_hook_find().
 342 </para>
 343
 344 @hook: a #GHook.
 345 @data: user data passed to g_hook_find_func().
 346 @Returns: %TRUE if the required #GHook has been found.
 347
 348
 349 <!-- ##### FUNCTION g_hook_find_data ##### -->
 350 <para>
 351 Finds a #GHook in a #GHookList with the given data.
 352 </para>
 353
 354 @hook_list: a #GHookList.
 355 @need_valids: %TRUE if #GHook elements which have been destroyed should be
 356 skipped.
 357 @data: the data to find.
 358 @Returns: the #GHook with the given @data or %NULL if no matching
 359 #GHook is found.
 360
 361
 362 <!-- ##### FUNCTION g_hook_find_func ##### -->
 363 <para>
 364 Finds a #GHook in a #GHookList with the given function.
 365 </para>
 366
 367 @hook_list: a #GHookList.
 368 @need_valids: %TRUE if #GHook elements which have been destroyed should be
 369 skipped.
 370 @func: the function to find.
 371 @Returns: the #GHook with the given @func or %NULL if no matching
 372 #GHook is found.
 373
 374
 375 <!-- ##### FUNCTION g_hook_find_func_data ##### -->
 376 <para>
 377 Finds a #GHook in a #GHookList with the given function and data.
 378 </para>
 379
 380 @hook_list: a #GHookList.
 381 @need_valids: %TRUE if #GHook elements which have been destroyed should be
 382 skipped.
 383 @func: the function to find.
 384 @data: the data to find.
 385 @Returns: the #GHook with the given @func and @data or %NULL if no matching
 386 #GHook is found.
 387
 388
 389 <!-- ##### FUNCTION g_hook_first_valid ##### -->
 390 <para>
 391 Returns the first #GHook in a #GHookList which has not been destroyed.
 392 The reference count for the #GHook is incremented, so you must call
 393 g_hook_unref() to restore it when no longer needed. (Or call
 394 g_hook_next_valid() if you are stepping through the #GHookList.)
 395 </para>
 396
 397 @hook_list: a #GHookList.
 398 @may_be_in_call: %TRUE if hooks which are currently running (e.g. in another
 399 thread) are considered valid. If set to %FALSE, these are skipped.
 400 @Returns: the first valid #GHook, or %NULL if none are valid.
 401
 402
 403 <!-- ##### FUNCTION g_hook_next_valid ##### -->
 404 <para>
 405 Returns the next #GHook in a #GHookList which has not been destroyed.
 406 The reference count for the #GHook is incremented, so you must call
 407 g_hook_unref() to restore it when no longer needed. (Or continue to call
 408 g_hook_next_valid() until %NULL is returned.)
 409
 410 </para>
 411
 412 @hook_list: a #GHookList.
 413 @hook: the current #GHook.
 414 @may_be_in_call: %TRUE if hooks which are currently running (e.g. in another
 415 thread) are considered valid. If set to %FALSE, these are skipped.
 416 @Returns: the next valid #GHook, or %NULL if none are valid.
 417
 418
 419 <!-- ##### ENUM GHookFlagMask ##### -->
 420 <para>
 421 Flags used internally in the #GHook implementation.
 422 </para>
 423
 424 @G_HOOK_FLAG_ACTIVE: set if the hook has not been destroyed.
 425 @G_HOOK_FLAG_IN_CALL: set if the hook is currently being run.
 426 @G_HOOK_FLAG_MASK:
 427
 428 <!-- ##### MACRO G_HOOK_FLAGS ##### -->
 429 <para>
 430 Returns the flags of a hook.
 431 </para>
 432
 433 @hook: a #GHook.
 434
 435
 436 <!-- ##### MACRO G_HOOK_FLAG_USER_SHIFT ##### -->
 437 <para>
 438
 439 </para>
 440
 441
 442
 443 <!-- ##### MACRO G_HOOK ##### -->
 444 <para>
 445 Casts a pointer to a <literal>GHook*</literal>.
 446 </para>
 447
 448 @hook: a pointer.
 449
 450
 451 <!-- ##### MACRO G_HOOK_IS_VALID ##### -->
 452 <para>
 453 Returns %TRUE if the #GHook is valid, i.e. it is in a #GHookList, it is active
 454 and it has not been destroyed.
 455 </para>
 456
 457 @hook: a #GHook.
 458 @Returns: %TRUE if the #GHook is valid.
 459
 460
 461 <!-- ##### MACRO G_HOOK_ACTIVE ##### -->
 462 <para>
 463 Returns %TRUE if the #GHook is active, which is normally %TRUE until the #GHook
 464 is destroyed.
 465 </para>
 466
 467 @hook: a #GHook.
 468 @Returns: %TRUE if the #GHook is active.
 469
 470
 471 <!-- ##### MACRO G_HOOK_IN_CALL ##### -->
 472 <para>
 473 Returns %TRUE if the #GHook function is currently executing.
 474 </para>
 475
 476 @hook: a #GHook.
 477 @Returns: %TRUE if the #GHook function is currently executing.
 478
 479
 480 <!-- ##### MACRO G_HOOK_IS_UNLINKED ##### -->
 481 <para>
 482 Returns %TRUE if the #GHook is not in a #GHookList.
 483
 484 </para>
 485
 486 @hook: a #GHook.
 487 @Returns: %TRUE if the #GHook is not in a #GHookList.
 488
 489
 490 <!-- ##### FUNCTION g_hook_ref ##### -->
 491 <para>
 492 Increments the reference count for a #GHook.
 493 </para>
 494
 495 @hook_list: a #GHookList.
 496 @hook: the #GHook to increment the reference count of.
 497
 498
 499 <!-- ##### FUNCTION g_hook_unref ##### -->
 500 <para>
 501 Decrements the reference count of a #GHook.
 502 If the reference count falls to 0, the #GHook is removed from the #GHookList
 503 and g_hook_free() is called to free it.
 504 </para>
 505
 506 @hook_list: a #GHookList.
 507 @hook: the #GHook to unref.
 508
 509
 510 <!-- ##### FUNCTION g_hook_free ##### -->
 511 <para>
 512 Calls the #GHookList @hook_free function if it exists, and frees the memory
 513 allocated for the #GHook.
 514 </para>
 515
 516 @hook_list: a #GHookList.
 517 @hook: the #GHook to free.
 518
 519
 520 <!-- ##### FUNCTION g_hook_destroy ##### -->
 521 <para>
 522 Destroys a #GHook, given its ID.
 523 </para>
 524
 525 @hook_list: a #GHookList.
 526 @hook_id: a hook ID.
 527 @Returns: %TRUE if the #GHook was found in the #GHookList and destroyed.
 528
 529
 530 <!-- ##### FUNCTION g_hook_destroy_link ##### -->
 531 <para>
 532 Removes one #GHook from a #GHookList, marking it inactive and calling
 533 g_hook_unref() on it.
 534 </para>
 535
 536 @hook_list: a #GHookList.
 537 @hook: the #GHook to remove.
 538
 539