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