ltt/branches/poly/lttv/modules/gui/lttvwindow/lttvwindow/lttvwindowtraces.h

   1 /* This file is part of the Linux Trace Toolkit Graphic User Interface
   2  * Copyright (C) 2003-2004 Mathieu Desnoyers
   3  *
   4  * This program is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License Version 2 as
   6  * published by the Free Software Foundation;
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License
  14  * along with this program; if not, write to the Free Software
  15  * Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  16  * MA 02111-1307, USA.
  17  */
  18
  19 /* This file is the API used to launch any background computation on a trace */
  20
  21 #ifndef LTTVWINDOWTRACES_H
  22 #define LTTVWINDOWTRACES_H
  23
  24 #include <ltt/time.h>
  25 #include <glib.h>
  26
  27 typedef GQuark LttvTraceInfo;
  28
  29 extern LttvTraceInfo LTTV_TRACES,
  30               LTTV_COMPUTATION,
  31               LTTV_REQUESTS_QUEUE,
  32               LTTV_REQUESTS_CURRENT,
  33               LTTV_NOTIFY_QUEUE,
  34               LTTV_NOTIFY_CURRENT,
  35               LTTV_COMPUTATION_TRACESET,
  36               LTTV_COMPUTATION_TRACESET_CONTEXT,
  37               LTTV_BEFORE_CHUNK_TRACESET,
  38               LTTV_BEFORE_CHUNK_TRACE,
  39               LTTV_BEFORE_CHUNK_TRACEFILE,
  40               LTTV_AFTER_CHUNK_TRACESET,
  41               LTTV_AFTER_CHUNK_TRACE,
  42               LTTV_AFTER_CHUNK_TRACEFILE,
  43               LTTV_BEFORE_REQUEST,
  44               LTTV_AFTER_REQUEST,
  45               LTTV_EVENT_HOOK,
  46               LTTV_EVENT_HOOK_BY_ID,
  47               LTTV_HOOK_ADDER,
  48               LTTV_HOOK_REMOVER,
  49               LTTV_IN_PROGRESS,
  50               LTTV_READY,
  51               LTTV_LOCK;
  52
  53
  54
  55 /* Get a trace by its path name.
  56  *
  57  * @param path path of the trace on the virtual file system.
  58  * @return Pointer to trace if found
  59  *        NULL is returned if the trace is not present
  60  */
  61
  62 LttvTrace *lttvwindowtraces_get_trace_by_name(gchar *path);
  63
  64 /* Get a trace by its number identifier */
  65
  66 LttvTrace *lttvwindowtraces_get_trace(guint num);
  67
  68 /* Total number of traces */
  69
  70 guint lttvwindowtraces_get_number();
  71
  72 /* Add a trace to the global attributes */
  73
  74 void lttvwindowtraces_add_trace(LttvTrace *trace);
  75
  76 /* Remove a trace from the global attributes */
  77
  78 void lttvwindowtraces_remove_trace(LttvTrace *trace);
  79
  80
  81 /**
  82  * Function to request data from a specific trace
  83  *
  84  * The memory allocated for the request will be managed by the API.
  85  *
  86  * @param trace the trace to compute
  87  * @param module_name the name of the module which registered global computation
  88  *                    hooks.
  89  */
  90
  91 void lttvwindowtraces_background_request_queue
  92                      (LttvTrace *trace, gchar *module_name);
  93
  94 /**
  95  * Remove a background request from a trace.
  96  *
  97  * This should ONLY be used by the modules which registered the global hooks
  98  * (module_name). If this is called by the viewers, it may lead to incomplete
  99  * and incoherent background processing information.
 100  *
 101  * Even if the module which deals with the hooks removes the background
 102  * requests, it may cause a problem if the module gets loaded again in the
 103  * session : the data will be partially calculated. The calculation function
 104  * must deal with this case correctly.
 105  *
 106  * @param trace the trace to compute
 107  * @param module_name the name of the module which registered global computation
 108  *                    hooks.
 109  */
 110
 111 void lttvwindowtraces_background_request_remove
 112                      (LttvTrace *trace, gchar *module_name);
 113
 114 /**
 115  * Register a callback to be called when requested data is passed in the next
 116  * queued background processing.
 117  *
 118  * @param owner owner of the background notification
 119  * @param trace the trace computed
 120  * @param notify_time time when notification hooks must be called
 121  * @param notify_position position when notification hooks must be called
 122  * @param notify  Hook to call when the notify position is passed
 123  */
 124
 125 void lttvwindowtraces_background_notify_queue
 126  (gpointer                     owner,
 127   LttvTrace                   *trace,
 128   LttTime                      notify_time,
 129   const LttvTracesetContextPosition *notify_position,
 130   const LttvHooks                   *notify);
 131
 132 /**
 133  * Register a callback to be called when requested data is passed in the current
 134  * background processing.
 135  *
 136  * @param owner owner of the background notification
 137  * @param trace the trace computed
 138  * @param notify_time time when notification hooks must be called
 139  * @param notify_position position when notification hooks must be called
 140  * @param notify  Hook to call when the notify position is passed
 141  */
 142
 143 void lttvwindowtraces_background_notify_current
 144  (gpointer                     owner,
 145   LttvTrace                   *trace,
 146   LttTime                      notify_time,
 147   const LttvTracesetContextPosition *notify_position,
 148   const LttvHooks                   *notify);
 149
 150 /**
 151  * Removes all the notifications requests from a specific viewer.
 152  *
 153  * @param owner owner of the background notification
 154  */
 155
 156 void lttvwindowtraces_background_notify_remove(gpointer owner);
 157
 158
 159 /**
 160  * Tells if the information computed by a module for a trace is ready.
 161  *
 162  * Must be checked before a background processing request.
 163  *
 164  * @param module_name A GQuark : the name of the module which computes the
 165  *                    information.
 166  * @param trace The trace for which the information is verified.
 167  */
 168
 169 gboolean lttvwindowtraces_get_ready(LttvAttributeName module_name,
 170                                     LttvTrace *trace);
 171
 172 /**
 173  * Tells if the information computed by a module for a trace is being processed.
 174  *
 175  * Must be checked before a background processing request.
 176  *
 177  * If it is effectively processed, the typical thing to do is to call
 178  * lttvwindowtraces_background_notify_current to be notified when the current
 179  * processing will be over.
 180  *
 181  * @param module_name A GQuark : the name of the module which computes the
 182  *                    information.
 183  * @param trace The trace for which the information is verified.
 184  */
 185
 186 gboolean lttvwindowtraces_get_in_progress(LttvAttributeName module_name,
 187                                     LttvTrace *trace);
 188
 189 /**
 190  * Register the background computation hooks for a specific module. It adds the
 191  * computation hooks to the global attrubutes, under "computation/module name"
 192  *
 193  * @param module_name A GQuark : the name of the module which computes the
 194  *                    information.
 195  */
 196 void lttvwindowtraces_register_computation_hooks(LttvAttributeName module_name,
 197                                           LttvHooks *before_chunk_traceset,
 198                                           LttvHooks *before_chunk_trace,
 199                                           LttvHooks *before_chunk_tracefile,
 200                                           LttvHooks *after_chunk_traceset,
 201                                           LttvHooks *after_chunk_trace,
 202                                           LttvHooks *after_chunk_tracefile,
 203                                           LttvHooks *before_request,
 204                                           LttvHooks *after_request,
 205                                           LttvHooks *event_hook,
 206                                           LttvHooksById *event_hook_by_id,
 207                                           LttvHooks *hook_adder,
 208                                           LttvHooks *hook_remover);
 209 /**
 210  * Unregister the background computation hooks for a specific module.
 211  *
 212  * It also removes all the requests than can be currently processed by the
 213  * background computation algorithm for all the traces (list_in and list_out).
 214  *
 215  * @param module_name A GQuark : the name of the module which computes the
 216  *                    information.
 217  */
 218
 219 void lttvwindowtraces_unregister_computation_hooks
 220                                      (LttvAttributeName module_name);
 221
 222
 223 /**
 224  * It removes all the requests than can be currently processed by the
 225  * background computation algorithm for all the traces (list_in and list_out).
 226  *
 227  * Leaves the flag to in_progress or none.. depending if current or queue
 228  *
 229  * @param module_name A GQuark : the name of the module which computes the
 230  *                    information.
 231  */
 232 void lttvwindowtraces_unregister_requests(LttvAttributeName module_name);
 233
 234
 235 /**
 236  * Lock a trace so no other instance can use it.
 237  *
 238  * @param trace The trace to lock.
 239  * @return 0 on success, -1 if cannot get lock.
 240  */
 241 gint lttvwindowtraces_lock(LttvTrace *trace);
 242
 243
 244 /**
 245  * Unlock a trace.
 246  *
 247  * @param trace The trace to unlock.
 248  * @return 0 on success, -1 if cannot unlock (not locked ?).
 249  */
 250 gint lttvwindowtraces_unlock(LttvTrace *trace);
 251
 252 /**
 253  * Verify if a trace is locked.
 254  *
 255  * @param trace The trace to verify.
 256  * @return TRUE if locked, FALSE is unlocked.
 257  */
 258 gint lttvwindowtraces_get_lock_state(LttvTrace *trace);
 259
 260
 261 #endif //LTTVWINDOWTRACES_H