PageRenderTime 56ms CodeModel.GetById 41ms app.highlight 7ms RepoModel.GetById 1ms app.codeStats 0ms

/src/wrappers/glib/library/utilities/glib_hook_functions.e

http://github.com/tybor/Liberty
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