ltt/branches/poly/lttv/lttv/hook.h

   1 /* This file is part of the Linux Trace Toolkit viewer
   2  * Copyright (C) 2003-2004 Michel Dagenais
   3  *
   4  * 25/05/2004 Mathieu Desnoyers : Hook priorities
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License Version 2 as
   8  * published by the Free Software Foundation;
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program; if not, write to the Free Software
  17  * Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  18  * MA 02111-1307, USA.
  19  */
  20
  21 #ifndef HOOK_H
  22 #define HOOK_H
  23
  24 #include <glib.h>
  25
  26 /* A hook is a function to call with the supplied hook data, and with
  27    call site specific data (e.g., hooks for events are called with a
  28    pointer to the current event). */
  29
  30 typedef gboolean (*LttvHook)(void *hook_data, void *call_data);
  31
  32
  33 /* A list of hooks allows registering hooks to be called later. */
  34
  35 typedef GArray LttvHooks;
  36
  37 /* A priority associated with each hook, from -19 (high prio) to 20 (low prio)
  38  * 0 being the default priority.
  39  *
  40  * Priority ordering is done in the lttv_hooks_add and lttv_hooks_add_list
  41  * functions. Hook removal does not change list order.
  42  */
  43
  44 #define LTTV_PRIO_DEFAULT 50
  45 #define LTTV_PRIO_HIGH 0
  46 #define LTTV_PRIO_LOW 99
  47
  48 typedef gint LttvHookPrio;
  49
  50 /* Create and destroy a list of hooks */
  51
  52 LttvHooks *lttv_hooks_new();
  53
  54 void lttv_hooks_destroy(LttvHooks *h);
  55
  56
  57 /* Add a hook and its hook data to the list */
  58
  59 void lttv_hooks_add(LttvHooks *h, LttvHook f, void *hook_data, LttvHookPrio p);
  60
  61
  62 /* Add a list of hooks to the list h */
  63
  64 void lttv_hooks_add_list(LttvHooks *h, const LttvHooks *list);
  65
  66
  67 /* Remove a hook from the list. Return the hook data. */
  68
  69 void *lttv_hooks_remove(LttvHooks *h, LttvHook f);
  70
  71
  72 /* Remove a hook from the list checking that the hook data match. */
  73
  74 void lttv_hooks_remove_data(LttvHooks *h, LttvHook f, void *hook_data);
  75
  76
  77 /* Remove a list of hooks from the hooks list in h. */
  78
  79 void lttv_hooks_remove_list(LttvHooks *h, LttvHooks *list);
  80
  81
  82 /* Return the number of hooks in the list */
  83
  84 unsigned lttv_hooks_number(LttvHooks *h);
  85
  86
  87 /* Return the hook at the specified position in the list.
  88  * *f and *hook_data are NULL if no hook exists at that position. */
  89
  90 void lttv_hooks_get(LttvHooks *h, unsigned i, LttvHook *f, void **hook_data,
  91                                               LttvHookPrio *p);
  92
  93
  94 /* Remove the specified hook. The position of the following hooks may change */
  95 /* The hook is removed from the list event if its ref_count is higher than 1 */
  96
  97 void lttv_hooks_remove_by_position(LttvHooks *h, unsigned i);
  98
  99
 100 /* Call all the hooks in the list, each with its hook data,
 101    with the specified call data, in priority order. Return TRUE if one hook
 102    returned TRUE. */
 103
 104 gboolean lttv_hooks_call(LttvHooks *h, void *call_data);
 105
 106
 107 /* Call the hooks in the list in priority order until one returns true,
 108  * in which case TRUE is returned. */
 109
 110 gboolean lttv_hooks_call_check(LttvHooks *h, void *call_data);
 111
 112
 113 /* Call hooks from two lists in priority order. If priority is the same,
 114  * hooks from h1 are called first. */
 115
 116 gboolean lttv_hooks_call_merge(LttvHooks *h1, void *call_data1,
 117                                LttvHooks *h2, void *call_data2);
 118
 119 gboolean lttv_hooks_call_check_merge(LttvHooks *h1, void *call_data1,
 120                                      LttvHooks *h2, void *call_data2);
 121
 122 /* Sometimes different hooks need to be called based on the case. The
 123    case is represented by an unsigned integer id */
 124
 125 typedef GPtrArray LttvHooksById;
 126
 127
 128 /* Create and destroy a hooks by id list */
 129
 130 LttvHooksById *lttv_hooks_by_id_new();
 131
 132 void lttv_hooks_by_id_destroy(LttvHooksById *h);
 133
 134
 135 /* Obtain the hooks for a given id, creating a list if needed */
 136
 137 LttvHooks *lttv_hooks_by_id_find(LttvHooksById *h, unsigned id);
 138
 139
 140 /* Return an id larger than any for which a list exists. */
 141
 142 unsigned lttv_hooks_by_id_max_id(LttvHooksById *h);
 143
 144
 145 /* Get the list of hooks for an id, NULL if none exists */
 146
 147 static inline LttvHooks *lttv_hooks_by_id_get(LttvHooksById *h, unsigned id)
 148 {
 149   LttvHooks *ret;
 150   if(id < h->len) ret = h->pdata[id];
 151   else ret = NULL;
 152
 153   return ret;
 154 }
 155
 156
 157 /* Remove the list of hooks associated with an id */
 158
 159 void lttv_hooks_by_id_remove(LttvHooksById *h, unsigned id);
 160
 161 #endif // HOOK_H