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 #include <ltt/compiler.h>
  26
  27 /* A hook is a function to call with the supplied hook data, and with
  28    call site specific data (e.g., hooks for events are called with a
  29    pointer to the current event). */
  30
  31 typedef gboolean (*LttvHook)(void *hook_data, void *call_data);
  32
  33
  34 /* A list of hooks allows registering hooks to be called later. */
  35
  36 typedef GArray LttvHooks;
  37
  38 /* A priority associated with each hook, from -19 (high prio) to 20 (low prio)
  39  * 0 being the default priority.
  40  *
  41  * Priority ordering is done in the lttv_hooks_add and lttv_hooks_add_list
  42  * functions. Hook removal does not change list order.
  43  */
  44
  45 #define LTTV_PRIO_DEFAULT 50
  46 #define LTTV_PRIO_HIGH 0
  47 #define LTTV_PRIO_LOW 99
  48
  49 typedef gint LttvHookPrio;
  50
  51 /* Create and destroy a list of hooks */
  52
  53 LttvHooks *lttv_hooks_new();
  54
  55 void lttv_hooks_destroy(LttvHooks *h);
  56
  57
  58 /* Add a hook and its hook data to the list */
  59
  60 void lttv_hooks_add(LttvHooks *h, LttvHook f, void *hook_data, LttvHookPrio p);
  61
  62
  63 /* Add a list of hooks to the list h */
  64
  65 void lttv_hooks_add_list(LttvHooks *h, const LttvHooks *list);
  66
  67
  68 /* Remove a hook from the list. Return the hook data. */
  69
  70 void *lttv_hooks_remove(LttvHooks *h, LttvHook f);
  71
  72
  73 /* Remove a hook from the list checking that the hook data match. */
  74
  75 void lttv_hooks_remove_data(LttvHooks *h, LttvHook f, void *hook_data);
  76
  77
  78 /* Remove a list of hooks from the hooks list in h. */
  79
  80 void lttv_hooks_remove_list(LttvHooks *h, LttvHooks *list);
  81
  82
  83 /* Return the number of hooks in the list */
  84
  85 unsigned lttv_hooks_number(LttvHooks *h);
  86
  87
  88 /* Return the hook at the specified position in the list.
  89  * *f and *hook_data are NULL if no hook exists at that position. */
  90
  91 void lttv_hooks_get(LttvHooks *h, unsigned i, LttvHook *f, void **hook_data,
  92                 LttvHookPrio *p);
  93
  94
  95 /* Remove the specified hook. The position of the following hooks may change */
  96 /* The hook is removed from the list event if its ref_count is higher than 1 */
  97
  98 void lttv_hooks_remove_by_position(LttvHooks *h, unsigned i);
  99
 100
 101 /* Call all the hooks in the list, each with its hook data,
 102    with the specified call data, in priority order. Return TRUE if one hook
 103    returned TRUE. */
 104
 105 gboolean lttv_hooks_call(LttvHooks *h, void *call_data);
 106
 107
 108 /* Call the hooks in the list in priority order until one returns true,
 109  * in which case TRUE is returned. */
 110
 111 gboolean lttv_hooks_call_check(LttvHooks *h, void *call_data);
 112
 113
 114 /* Call hooks from two lists in priority order. If priority is the same,
 115  * hooks from h1 are called first. */
 116
 117 gboolean lttv_hooks_call_merge(LttvHooks *h1, void *call_data1,
 118                 LttvHooks *h2, void *call_data2);
 119
 120 gboolean lttv_hooks_call_check_merge(LttvHooks *h1, void *call_data1,
 121                 LttvHooks *h2, void *call_data2);
 122
 123 /* Sometimes different hooks need to be called based on the case. The
 124    case is represented by an unsigned integer id */
 125
 126 typedef struct _LttvHooksById {
 127         GPtrArray *index;
 128         GArray *array;
 129 } LttvHooksById;
 130
 131 /* Create and destroy a hooks by id list */
 132
 133 LttvHooksById *lttv_hooks_by_id_new(void);
 134
 135 void lttv_hooks_by_id_destroy(LttvHooksById *h);
 136
 137
 138 /* Obtain the hooks for a given id, creating a list if needed */
 139
 140 LttvHooks *lttv_hooks_by_id_find(LttvHooksById *h, unsigned id);
 141
 142
 143 /* Return an id larger than any for which a list exists. */
 144
 145 unsigned lttv_hooks_by_id_max_id(LttvHooksById *h);
 146
 147
 148 /* Get the list of hooks for an id, NULL if none exists */
 149
 150 static inline LttvHooks *lttv_hooks_by_id_get(LttvHooksById *h, unsigned id)
 151 {
 152         LttvHooks *ret;
 153         if(likely(id < h->index->len)) ret = h->index->pdata[id];
 154         else ret = NULL;
 155
 156         return ret;
 157 }
 158
 159 /* Remove the list of hooks associated with an id */
 160
 161 void lttv_hooks_by_id_remove(LttvHooksById *h, unsigned id);
 162
 163 void lttv_hooks_by_id_copy(LttvHooksById *dest, LttvHooksById *src);
 164
 165 /*
 166  * Hooks per channel per id. Useful for GUI to save/restore hooks
 167  * on a per trace basis (rather than per tracefile).
 168  */
 169
 170 /* Internal structure, contained in by the LttvHooksByIdChannelArray */
 171 typedef struct _LttvHooksByIdChannel {
 172         LttvHooksById *hooks_by_id;
 173         GQuark channel;
 174 } LttvHooksByIdChannel;
 175
 176 typedef struct _LttvHooksByIdChannelArray {
 177         GArray *array;  /* Array of LttvHooksByIdChannel */
 178 } LttvHooksByIdChannelArray;
 179
 180 LttvHooksByIdChannelArray *lttv_hooks_by_id_channel_new(void);
 181
 182 void lttv_hooks_by_id_channel_destroy(LttvHooksByIdChannelArray *h);
 183
 184 LttvHooks *lttv_hooks_by_id_channel_find(LttvHooksByIdChannelArray *h,
 185                 GQuark channel, guint16 id);
 186
 187 #endif // HOOK_H