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