1<!-- ##### SECTION Title ##### --> 2Hook Functions 3 4<!-- ##### SECTION Short_Description ##### --> 5support for manipulating lists of hook functions 6 7<!-- ##### SECTION Long_Description ##### --> 8<para> 9The #GHookList, #GHook and their related functions provide support for 10lists of hook functions. Functions can be added and removed from the lists, 11and 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> 25The <structname>GHookList</structname> struct represents a 26list 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 35default behaviour is to call the hooks <function>destroy</function> function 36@dummy: unused 37 38<!-- ##### USER_FUNCTION GHookFinalizeFunc ##### --> 39<para> 40Defines the type of function to be called when a hook in a 41list 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> 50The <structname>GHook</structname> struct represents a single hook 51function 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 62signatures 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> 68Defines the type of a hook function that can be invoked 69by 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> 77Defines the type of a hook function that can be invoked 78by 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> 87Initializes a #GHookList. 88This 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> 98Calls 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> 108Calls all of the #GHook functions in a #GHookList. 109Any 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 114thread) can be called. If set to %FALSE, these are skipped 115 116 117<!-- ##### FUNCTION g_hook_list_marshal ##### --> 118<para> 119Calls 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> 131Defines 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> 140Calls a function on each valid #GHook and destroys it if the 141function 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> 153Defines 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> 163Removes all the #GHook elements from a #GHookList. 164</para> 165 166@hook_list: a #GHookList 167 168 169<!-- ##### FUNCTION g_hook_alloc ##### --> 170<para> 171Allocates 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> 180Appends 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> 189Prepends 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> 198Inserts 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> 208Inserts 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> 218Defines the type of function used to compare #GHook elements in 219g_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 <= 0 if @new_hook should be before @sibling 225 226 227<!-- ##### FUNCTION g_hook_compare_ids ##### --> 228<para> 229Compares the ids of two #GHook elements, returning a negative value 230if 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 <= 0 if the id of @sibling is >= the id of @new_hook 236 237 238<!-- ##### FUNCTION g_hook_get ##### --> 239<para> 240Returns 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> 250Finds 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> 264Defines 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> 274Finds 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> 287Finds 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> 300Finds 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> 314Returns the first #GHook in a #GHookList which has not been destroyed. 315The reference count for the #GHook is incremented, so you must call 316g_hook_unref() to restore it when no longer needed. (Or call 317g_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> 328Returns the next #GHook in a #GHookList which has not been destroyed. 329The reference count for the #GHook is incremented, so you must call 330g_hook_unref() to restore it when no longer needed. (Or continue to call 331g_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> 344Flags 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> 354Returns the flags of a hook. 355</para> 356 357@hook: a #GHook 358 359 360<!-- ##### MACRO G_HOOK_FLAG_USER_SHIFT ##### --> 361<para> 362The position of the first bit which is not reserved for internal 363use be the #GHook implementation, i.e. 364<literal>1 << G_HOOK_FLAG_USER_SHIFT</literal> is the first bit 365which can be used for application-defined flags. 366</para> 367 368 369 370<!-- ##### MACRO G_HOOK ##### --> 371<para> 372Casts a pointer to a <literal>GHook*</literal>. 373</para> 374 375@hook: a pointer 376 377 378<!-- ##### MACRO G_HOOK_IS_VALID ##### --> 379<para> 380Returns %TRUE if the #GHook is valid, i.e. it is in a #GHookList, it is active 381and 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> 390Returns %TRUE if the #GHook is active, which is normally %TRUE until the #GHook 391is 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> 400Returns %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> 409Returns %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> 419Increments 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> 429Decrements the reference count of a #GHook. 430If the reference count falls to 0, the #GHook is removed from the #GHookList 431and 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> 440Calls the #GHookList @finalize_hook function if it exists, and frees the memory 441allocated 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> 450Destroys 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> 460Removes one #GHook from a #GHookList, marking it inactive and calling 461g_hook_unref() on it. 462</para> 463 464@hook_list: a #GHookList 465@hook: the #GHook to remove 466 467 468