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: unused
  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: unused
  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 %FALSE 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 @finalize_hook 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