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