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