/src/wrappers/glib/library/utilities/glib_hook_functions.e
Specman e | 685 lines | 2 code | 218 blank | 465 comment | 0 complexity | 759d3dbdd49b0a6650ee87eeddac5102 MD5 | raw file
1deferred class GLIB_HOOK_FUNCTIONS 2-- Hook Functions 3 4-- Hook Functions -- support for manipulating lists of hook functions. 5 6-- Synopsis 7 8 9-- #include <glib.h> 10 11 12-- GHookList; 13-- void (*GHookFinalizeFunc) (GHookList *hook_list, 14-- GHook *hook); 15-- GHook; 16-- void (*GHookFunc) (gpointer data); 17-- gboolean (*GHookCheckFunc) (gpointer data); 18 19-- void g_hook_list_init (GHookList *hook_list, 20-- guint hook_size); 21-- void g_hook_list_invoke (GHookList *hook_list, 22-- gboolean may_recurse); 23-- void g_hook_list_invoke_check (GHookList *hook_list, 24-- gboolean may_recurse); 25-- void g_hook_list_marshal (GHookList *hook_list, 26-- gboolean may_recurse, 27-- GHookMarshaller marshaller, 28-- gpointer marshal_data); 29-- void (*GHookMarshaller) (GHook *hook, 30-- gpointer marshal_data); 31-- void g_hook_list_marshal_check (GHookList *hook_list, 32-- gboolean may_recurse, 33-- GHookCheckMarshaller marshaller, 34-- gpointer marshal_data); 35-- gboolean (*GHookCheckMarshaller) (GHook *hook, 36-- gpointer marshal_data); 37-- void g_hook_list_clear (GHookList *hook_list); 38 39-- GHook* g_hook_alloc (GHookList *hook_list); 40-- #define g_hook_append ( hook_list, hook ) 41-- void g_hook_prepend (GHookList *hook_list, 42-- GHook *hook); 43-- void g_hook_insert_before (GHookList *hook_list, 44-- GHook *sibling, 45-- GHook *hook); 46-- void g_hook_insert_sorted (GHookList *hook_list, 47-- GHook *hook, 48-- GHookCompareFunc func); 49-- gint (*GHookCompareFunc) (GHook *new_hook, 50-- GHook *sibling); 51-- gint g_hook_compare_ids (GHook *new_hook, 52-- GHook *sibling); 53 54-- GHook* g_hook_get (GHookList *hook_list, 55-- gulong hook_id); 56-- GHook* g_hook_find (GHookList *hook_list, 57-- gboolean need_valids, 58-- GHookFindFunc func, 59-- gpointer data); 60-- gboolean (*GHookFindFunc) (GHook *hook, 61-- gpointer data); 62-- GHook* g_hook_find_data (GHookList *hook_list, 63-- gboolean need_valids, 64-- gpointer data); 65-- GHook* g_hook_find_func (GHookList *hook_list, 66-- gboolean need_valids, 67-- gpointer func); 68-- GHook* g_hook_find_func_data (GHookList *hook_list, 69-- gboolean need_valids, 70-- gpointer func, 71-- gpointer data); 72 73-- GHook* g_hook_first_valid (GHookList *hook_list, 74-- gboolean may_be_in_call); 75-- GHook* g_hook_next_valid (GHookList *hook_list, 76-- GHook *hook, 77-- gboolean may_be_in_call); 78-- enum GHookFlagMask; 79-- #define G_HOOK_FLAGS (hook) 80-- #define G_HOOK_FLAG_USER_SHIFT 81 82-- #define G_HOOK (hook) 83-- #define G_HOOK_IS_VALID (hook) 84-- #define G_HOOK_ACTIVE (hook) 85-- #define G_HOOK_IN_CALL (hook) 86-- #define G_HOOK_IS_UNLINKED (hook) 87 88-- GHook* g_hook_ref (GHookList *hook_list, 89-- GHook *hook); 90-- void g_hook_unref (GHookList *hook_list, 91-- GHook *hook); 92-- void g_hook_free (GHookList *hook_list, 93-- GHook *hook); 94-- gboolean g_hook_destroy (GHookList *hook_list, 95-- gulong hook_id); 96-- void g_hook_destroy_link (GHookList *hook_list, 97-- GHook *hook); 98 99-- Description 100 101-- The GHookList, GHook and their related functions provide support for lists of 102-- hook functions. Functions can be added and removed from the lists, and the list 103-- of hook functions can be invoked. 104 105-- Details 106 107-- GHookList 108 109-- typedef struct { 110-- gulong seq_id; 111-- guint hook_size : 16; 112-- guint is_setup : 1; 113-- GHook *hooks; 114-- gpointer dummy3; 115-- GHookFinalizeFunc finalize_hook; 116-- gpointer dummy[2]; 117-- } GHookList; 118 119-- The GHookList struct represents a list of hook functions. 120 121-- gulong seq_id; the next free GHook id. 122-- guint hook_size : 16; the size of the GHookList elements, in bytes. 123-- guint is_setup : 1; 1 if the GHookList has been initialized. 124-- GHook *hooks; the first GHook element in the list. 125-- gpointer dummy3; 126-- GHookFinalizeFunc finalize_hook; the function to call to finalize a GHook 127-- element. The default behaviour is to call the 128-- hooks destroy function. 129-- gpointer dummy[2]; 130 131-- --------------------------------------------------------------------------------- 132 133-- GHookFinalizeFunc () 134 135-- void (*GHookFinalizeFunc) (GHookList *hook_list, 136-- GHook *hook); 137 138-- Defines the type of function to be called when a hook in a list of hooks gets 139-- finalized. 140 141-- hook_list : a GHookList. 142-- hook : the hook in hook_list that gets finalized. 143 144-- --------------------------------------------------------------------------------- 145 146-- GHook 147 148-- typedef struct { 149-- gpointer data; 150-- GHook *next; 151-- GHook *prev; 152-- guint ref_count; 153-- gulong hook_id; 154-- guint flags; 155-- gpointer func; 156-- GDestroyNotify destroy; 157-- } GHook; 158 159-- The GHook struct represents a single hook function in a GHookList. 160 161-- gpointer data; data which is passed to func when this hook is invoked. 162-- GHook *next; pointer to the next hook in the list. 163-- GHook *prev; pointer to the previous hook in the list. 164-- guint ref_count; the reference count of this hook. 165-- gulong hook_id; the id of this hook, which is unique within its list. 166-- guint flags; flags which are set for this hook. See GHookFlagMask for 167-- predefined flags. 168-- gpointer func; the function to call when this hook is invoked. The 169-- possible signatures for this function are GHookFunc and 170-- GHookCheckFunc. 171-- GDestroyNotify destroy; the default finalize_hook function of a GHookList calls 172-- this member of the hook that is being finalized. 173 174-- --------------------------------------------------------------------------------- 175 176-- GHookFunc () 177 178-- void (*GHookFunc) (gpointer data); 179 180-- Defines the type of a hook function that can be invoked by g_hook_list_invoke(). 181 182-- data : the data field of the GHook is passed to the hook function here. 183 184-- --------------------------------------------------------------------------------- 185 186-- GHookCheckFunc () 187 188-- gboolean (*GHookCheckFunc) (gpointer data); 189 190-- Defines the type of a hook function that can be invoked by 191-- g_hook_list_invoke_check(). 192 193-- data : the data field of the GHook is passed to the hook function here. 194-- Returns : FALSE if the GHook should be destroyed. 195 196-- --------------------------------------------------------------------------------- 197 198-- g_hook_list_init () 199 200-- void g_hook_list_init (GHookList *hook_list, 201-- guint hook_size); 202 203-- Initializes a GHookList. This must be called before the GHookList is used. 204 205-- hook_list : a GHookList. 206-- hook_size : the size of each element in the GHookList, typically sizeof (GHook). 207 208-- --------------------------------------------------------------------------------- 209 210-- g_hook_list_invoke () 211 212-- void g_hook_list_invoke (GHookList *hook_list, 213-- gboolean may_recurse); 214 215-- Calls all of the GHook functions in a GHookList. 216 217-- hook_list : a GHookList. 218-- may_recurse : TRUE if functions which are already running (e.g. in another 219-- thread) can be called. If set to FALSE, these are skipped. 220 221-- --------------------------------------------------------------------------------- 222 223-- g_hook_list_invoke_check () 224 225-- void g_hook_list_invoke_check (GHookList *hook_list, 226-- gboolean may_recurse); 227 228-- Calls all of the GHook functions in a GHookList. Any function which returns TRUE 229-- is removed from the GHookList. 230 231-- hook_list : a GHookList. 232-- may_recurse : TRUE if functions which are already running (e.g. in another 233-- thread) can be called. If set to FALSE, these are skipped. 234 235-- --------------------------------------------------------------------------------- 236 237-- g_hook_list_marshal () 238 239-- void g_hook_list_marshal (GHookList *hook_list, 240-- gboolean may_recurse, 241-- GHookMarshaller marshaller, 242-- gpointer marshal_data); 243 244-- Calls a function on each valid GHook. 245 246-- hook_list : a GHookList. 247-- may_recurse : TRUE if hooks which are currently running (e.g. in another thread) 248-- are considered valid. If set to FALSE, these are skipped. 249-- marshaller : the function to call for each GHook. 250-- marshal_data : data to pass to marshaller. 251 252-- --------------------------------------------------------------------------------- 253 254-- GHookMarshaller () 255 256-- void (*GHookMarshaller) (GHook *hook, 257-- gpointer marshal_data); 258 259-- Defines the type of function used by g_hook_list_marshal(). 260 261-- hook : a GHook. 262-- marshal_data : user data. 263 264-- --------------------------------------------------------------------------------- 265 266-- g_hook_list_marshal_check () 267 268-- void g_hook_list_marshal_check (GHookList *hook_list, 269-- gboolean may_recurse, 270-- GHookCheckMarshaller marshaller, 271-- gpointer marshal_data); 272 273-- Calls a function on each valid GHook and destroys it if the function returns 274-- FALSE. 275 276-- hook_list : a GHookList. 277-- may_recurse : TRUE if hooks which are currently running (e.g. in another thread) 278-- are considered valid. If set to FALSE, these are skipped. 279-- marshaller : the function to call for each GHook. 280-- marshal_data : data to pass to marshaller. 281 282-- --------------------------------------------------------------------------------- 283 284-- GHookCheckMarshaller () 285 286-- gboolean (*GHookCheckMarshaller) (GHook *hook, 287-- gpointer marshal_data); 288 289-- Defines the type of function used by g_hook_list_marshal_check(). 290 291-- hook : a GHook. 292-- marshal_data : user data. 293-- Returns : FALSE if hook should be destroyed. 294 295-- --------------------------------------------------------------------------------- 296 297-- g_hook_list_clear () 298 299-- void g_hook_list_clear (GHookList *hook_list); 300 301-- Removes all the GHook elements from a GHookList. 302 303-- hook_list : a GHookList. 304 305-- --------------------------------------------------------------------------------- 306 307-- g_hook_alloc () 308 309-- GHook* g_hook_alloc (GHookList *hook_list); 310 311-- Allocates space for a GHook and initializes it. 312 313-- hook_list : a GHookList. 314-- Returns : a new GHook. 315 316-- --------------------------------------------------------------------------------- 317 318-- g_hook_append() 319 320-- #define g_hook_append( hook_list, hook ) 321 322-- Appends a GHook onto the end of a GHookList. 323 324-- hook_list : a GHookList. 325-- hook : the GHook to add to the end of hook_list. 326 327-- --------------------------------------------------------------------------------- 328 329-- g_hook_prepend () 330 331-- void g_hook_prepend (GHookList *hook_list, 332-- GHook *hook); 333 334-- Prepends a GHook on the start of a GHookList. 335 336-- hook_list : a GHookList. 337-- hook : the GHook to add to the start of hook_list. 338 339-- --------------------------------------------------------------------------------- 340 341-- g_hook_insert_before () 342 343-- void g_hook_insert_before (GHookList *hook_list, 344-- GHook *sibling, 345-- GHook *hook); 346 347-- Inserts a GHook into a GHookList, before a given GHook. 348 349-- hook_list : a GHookList. 350-- sibling : the GHook to insert the new GHook before. 351-- hook : the GHook to insert. 352 353-- --------------------------------------------------------------------------------- 354 355-- g_hook_insert_sorted () 356 357-- void g_hook_insert_sorted (GHookList *hook_list, 358-- GHook *hook, 359-- GHookCompareFunc func); 360 361-- Inserts a GHook into a GHookList, sorted by the given function. 362 363-- hook_list : a GHookList. 364-- hook : the GHook to insert. 365-- func : the comparison function used to sort the GHook elements. 366 367-- --------------------------------------------------------------------------------- 368 369-- GHookCompareFunc () 370 371-- gint (*GHookCompareFunc) (GHook *new_hook, 372-- GHook *sibling); 373 374-- Defines the type of function used to compare GHook elements in 375-- g_hook_insert_sorted(). 376 377-- new_hook : the GHook being inserted. 378-- sibling : the GHook to compare with new_hook. 379-- Returns : a value <= 0 if new_hook should be before sibling. 380 381-- --------------------------------------------------------------------------------- 382 383-- g_hook_compare_ids () 384 385-- gint g_hook_compare_ids (GHook *new_hook, 386-- GHook *sibling); 387 388-- Compares the ids of two GHook elements, returning a negative value if the second 389-- id is greater than the first. 390 391-- new_hook : a GHook. 392-- sibling : a GHook to compare with new_hook. 393-- Returns : a value <= 0 if the id of sibling is >= the id of new_hook. 394 395-- --------------------------------------------------------------------------------- 396 397-- g_hook_get () 398 399-- GHook* g_hook_get (GHookList *hook_list, 400-- gulong hook_id); 401 402-- Returns the GHook with the given id, or NULL if it is not found. 403 404-- hook_list : a GHookList. 405-- hook_id : a hook id. 406-- Returns : the GHook with the given id, or NULL if it is not found. 407 408-- --------------------------------------------------------------------------------- 409 410-- g_hook_find () 411 412-- GHook* g_hook_find (GHookList *hook_list, 413-- gboolean need_valids, 414-- GHookFindFunc func, 415-- gpointer data); 416 417-- Finds a GHook in a GHookList using the given function to test for a match. 418 419-- hook_list : a GHookList. 420-- need_valids : TRUE if GHook elements which have been destroyed should be skipped. 421-- func : the function to call for each GHook, which should return TRUE when 422-- the GHook has been found. 423-- data : the data to pass to func. 424-- Returns : the found GHook or NULL if no matching GHook is found. 425 426-- --------------------------------------------------------------------------------- 427 428-- GHookFindFunc () 429 430-- gboolean (*GHookFindFunc) (GHook *hook, 431-- gpointer data); 432 433-- Defines the type of the function passed to g_hook_find(). 434 435-- hook : a GHook. 436-- data : user data passed to g_hook_find_func(). 437-- Returns : TRUE if the required GHook has been found. 438 439-- --------------------------------------------------------------------------------- 440 441-- g_hook_find_data () 442 443-- GHook* g_hook_find_data (GHookList *hook_list, 444-- gboolean need_valids, 445-- gpointer data); 446 447-- Finds a GHook in a GHookList with the given data. 448 449-- hook_list : a GHookList. 450-- need_valids : TRUE if GHook elements which have been destroyed should be skipped. 451-- data : the data to find. 452-- Returns : the GHook with the given data or NULL if no matching GHook is 453-- found. 454 455-- --------------------------------------------------------------------------------- 456 457-- g_hook_find_func () 458 459-- GHook* g_hook_find_func (GHookList *hook_list, 460-- gboolean need_valids, 461-- gpointer func); 462 463-- Finds a GHook in a GHookList with the given function. 464 465-- hook_list : a GHookList. 466-- need_valids : TRUE if GHook elements which have been destroyed should be skipped. 467-- func : the function to find. 468-- Returns : the GHook with the given func or NULL if no matching GHook is 469-- found. 470 471-- --------------------------------------------------------------------------------- 472 473-- g_hook_find_func_data () 474 475-- GHook* g_hook_find_func_data (GHookList *hook_list, 476-- gboolean need_valids, 477-- gpointer func, 478-- gpointer data); 479 480-- Finds a GHook in a GHookList with the given function and data. 481 482-- hook_list : a GHookList. 483-- need_valids : TRUE if GHook elements which have been destroyed should be skipped. 484-- func : the function to find. 485-- data : the data to find. 486-- Returns : the GHook with the given func and data or NULL if no matching GHook 487-- is found. 488 489-- --------------------------------------------------------------------------------- 490 491-- g_hook_first_valid () 492 493-- GHook* g_hook_first_valid (GHookList *hook_list, 494-- gboolean may_be_in_call); 495 496-- Returns the first GHook in a GHookList which has not been destroyed. The 497-- reference count for the GHook is incremented, so you must call g_hook_unref() to 498-- restore it when no longer needed. (Or call g_hook_next_valid() if you are 499-- stepping through the GHookList.) 500 501-- hook_list : a GHookList. 502-- may_be_in_call : TRUE if hooks which are currently running (e.g. in another 503-- thread) are considered valid. If set to FALSE, these are 504-- skipped. 505-- Returns : the first valid GHook, or NULL if none are valid. 506 507-- --------------------------------------------------------------------------------- 508 509-- g_hook_next_valid () 510 511-- GHook* g_hook_next_valid (GHookList *hook_list, 512-- GHook *hook, 513-- gboolean may_be_in_call); 514 515-- Returns the next GHook in a GHookList which has not been destroyed. The reference 516-- count for the GHook is incremented, so you must call g_hook_unref() to restore it 517-- when no longer needed. (Or continue to call g_hook_next_valid() until NULL is 518-- returned.) 519 520-- hook_list : a GHookList. 521-- hook : the current GHook. 522-- may_be_in_call : TRUE if hooks which are currently running (e.g. in another 523-- thread) are considered valid. If set to FALSE, these are 524-- skipped. 525-- Returns : the next valid GHook, or NULL if none are valid. 526 527-- --------------------------------------------------------------------------------- 528 529-- enum GHookFlagMask 530 531-- typedef enum 532-- { 533-- G_HOOK_FLAG_ACTIVE = 1 << 0, 534-- G_HOOK_FLAG_IN_CALL = 1 << 1, 535-- G_HOOK_FLAG_MASK = 0x0f 536-- } GHookFlagMask; 537 538-- Flags used internally in the GHook implementation. 539 540-- G_HOOK_FLAG_ACTIVE set if the hook has not been destroyed. 541-- G_HOOK_FLAG_IN_CALL set if the hook is currently being run. 542-- G_HOOK_FLAG_MASK A mask covering all bits reserved for hook flags; see 543-- G_HOOK_FLAGS_USER_SHIFT 544 545-- --------------------------------------------------------------------------------- 546 547-- G_HOOK_FLAGS() 548 549-- #define G_HOOK_FLAGS(hook) (G_HOOK (hook)->flags) 550 551-- Returns the flags of a hook. 552 553-- hook : a GHook. 554 555-- --------------------------------------------------------------------------------- 556 557-- G_HOOK_FLAG_USER_SHIFT 558 559-- #define G_HOOK_FLAG_USER_SHIFT (4) 560 561-- The position of the first bit which is not reserved for internal use be the GHook 562-- implementation, i.e. 1 << G_HOOK_FLAG_USER_SHIFT is the first bit which can be 563-- used for application-defined flags. 564 565-- --------------------------------------------------------------------------------- 566 567-- G_HOOK() 568 569-- #define G_HOOK(hook) ((GHook*) (hook)) 570 571-- Casts a pointer to a GHook*. 572 573-- hook : a pointer. 574 575-- --------------------------------------------------------------------------------- 576 577-- G_HOOK_IS_VALID() 578 579-- #define G_HOOK_IS_VALID(hook) 580 581-- Returns TRUE if the GHook is valid, i.e. it is in a GHookList, it is active and 582-- it has not been destroyed. 583 584-- hook : a GHook. 585-- Returns : TRUE if the GHook is valid. 586 587-- --------------------------------------------------------------------------------- 588 589-- G_HOOK_ACTIVE() 590 591-- #define G_HOOK_ACTIVE(hook) 592 593-- Returns TRUE if the GHook is active, which is normally TRUE until the GHook is 594-- destroyed. 595 596-- hook : a GHook. 597-- Returns : TRUE if the GHook is active. 598 599-- --------------------------------------------------------------------------------- 600 601-- G_HOOK_IN_CALL() 602 603-- #define G_HOOK_IN_CALL(hook) 604 605-- Returns TRUE if the GHook function is currently executing. 606 607-- hook : a GHook. 608-- Returns : TRUE if the GHook function is currently executing. 609 610-- --------------------------------------------------------------------------------- 611 612-- G_HOOK_IS_UNLINKED() 613 614-- #define G_HOOK_IS_UNLINKED(hook) 615 616-- Returns TRUE if the GHook is not in a GHookList. 617 618-- hook : a GHook. 619-- Returns : TRUE if the GHook is not in a GHookList. 620 621-- --------------------------------------------------------------------------------- 622 623-- g_hook_ref () 624 625-- GHook* g_hook_ref (GHookList *hook_list, 626-- GHook *hook); 627 628-- Increments the reference count for a GHook. 629 630-- hook_list : a GHookList. 631-- hook : the GHook to increment the reference count of. 632-- Returns : the hook that was passed in (since 2.6) 633 634-- --------------------------------------------------------------------------------- 635 636-- g_hook_unref () 637 638-- void g_hook_unref (GHookList *hook_list, 639-- GHook *hook); 640 641-- Decrements the reference count of a GHook. If the reference count falls to 0, the 642-- GHook is removed from the GHookList and g_hook_free() is called to free it. 643 644-- hook_list : a GHookList. 645-- hook : the GHook to unref. 646 647-- --------------------------------------------------------------------------------- 648 649-- g_hook_free () 650 651-- void g_hook_free (GHookList *hook_list, 652-- GHook *hook); 653 654-- Calls the GHookList hook_free function if it exists, and frees the memory 655-- allocated for the GHook. 656 657-- hook_list : a GHookList. 658-- hook : the GHook to free. 659 660-- --------------------------------------------------------------------------------- 661 662-- g_hook_destroy () 663 664-- gboolean g_hook_destroy (GHookList *hook_list, 665-- gulong hook_id); 666 667-- Destroys a GHook, given its ID. 668 669-- hook_list : a GHookList. 670-- hook_id : a hook ID. 671-- Returns : TRUE if the GHook was found in the GHookList and destroyed. 672 673-- --------------------------------------------------------------------------------- 674 675-- g_hook_destroy_link () 676 677-- void g_hook_destroy_link (GHookList *hook_list, 678-- GHook *hook); 679 680-- Removes one GHook from a GHookList, marking it inactive and calling 681-- g_hook_unref() on it. 682 683-- hook_list : a GHookList. 684-- hook : the GHook to remove. 685end -- class GLIB_HOOK_FUNCTIONS