git.lttng.org Git - lttv.git/blob

   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 /* lttvwindowtraces
  22  *
  23  * This API consists in two main parts. The first one is for the background
  24  * computation provider and the second is for the viewer which needs this
  25  * information.
  26  *
  27  * A computation provider, i.e. a statistics computation module or a state
  28  * computation module, have two things in common : they append data to a trace
  29  * in an extensible container (LttvAttributes). This extended information, once
  30  * computed, can be kept all along with the trace and does not need to be
  31  * recomputed : a computation done on a trace must result in a identical result
  32  * each time it is done.
  33  *
  34  * This API provides functions for computation provider to register their
  35  * computation functions (or computation functions insertion and removal
  36  * functions). Once the computation provider is registered with its module name,
  37  * extended computation for a trace can be requested by any viewer by specifying
  38  * the module name, as we will describe in a moment.
  39  *
  40  * A viewer which needs extended information about a trace must ask for it to be
  41  * computed by doing a background computation request. It may also ask to be
  42  * notified of the completion of its request by doing a notify request.
  43  *
  44  * Before asking for the computation, it must check for its readiness. If it is
  45  * ready, the information has already been computed, so it is ready to use. If
  46  * the information is not ready, in must check whether or not the processing of
  47  * this task is in progress. If it is, it must not do any background computation
  48  * request. It must only do a background notification request of the current
  49  * processing to be informed of its completion. If the information is not ready
  50  * and not being processed, then the viewer may do a background computation
  51  * request and add a notify request to the notify queue.
  52  *
  53  * When a context takes control of a trace, it must lock the trace. This is a
  54  * way of ensuring that not conflict will occur between two traceset contexts
  55  * and shared traces. It will generate an error if a context try to get a lock
  56  * on a trace what is not unlocked. Upon every trace locking,
  57  * lttv_process_traceset_synchronize_tracefiles should be used to resynchronize
  58  * the traces with the trace context information.
  59  *
  60  * The usefulness of the lock in this framework can be questionable in a
  61  * single threaded environment, but can be great in the eventuality of
  62  * multiple threads.
  63  *
  64  */
  65
  66
  67
  68 #ifndef LTTVWINDOWTRACES_H
  69 #define LTTVWINDOWTRACES_H
  70
  71 #include <ltt/time.h>
  72 #include <glib.h>
  73 #include <gtk/gtk.h>
  74
  75 typedef GQuark LttvTraceInfo;
  76
  77 extern LttvTraceInfo LTTV_TRACES,
  78               LTTV_COMPUTATION,
  79               LTTV_REQUESTS_QUEUE,
  80               LTTV_REQUESTS_CURRENT,
  81               LTTV_NOTIFY_QUEUE,
  82               LTTV_NOTIFY_CURRENT,
  83               LTTV_COMPUTATION_TRACESET,
  84               LTTV_COMPUTATION_TRACESET_CONTEXT,
  85               LTTV_COMPUTATION_SYNC_POSITION,
  86               LTTV_BEFORE_CHUNK_TRACESET,
  87               LTTV_BEFORE_CHUNK_TRACE,
  88               LTTV_BEFORE_CHUNK_TRACEFILE,
  89               LTTV_AFTER_CHUNK_TRACESET,
  90               LTTV_AFTER_CHUNK_TRACE,
  91               LTTV_AFTER_CHUNK_TRACEFILE,
  92               LTTV_BEFORE_REQUEST,
  93               LTTV_AFTER_REQUEST,
  94               LTTV_EVENT_HOOK,
  95               LTTV_EVENT_HOOK_BY_ID,
  96               LTTV_HOOK_ADDER,
  97               LTTV_HOOK_REMOVER,
  98               LTTV_IN_PROGRESS,
  99               LTTV_READY,
 100               LTTV_LOCK;
 101
 102
 103
 104 /* Get a trace by its path name.
 105  *
 106  * @param path path of the trace on the virtual file system.
 107  * @return Pointer to trace if found
 108  *        NULL is returned if the trace is not present
 109  */
 110
 111 LttvTrace *lttvwindowtraces_get_trace_by_name(gchar *path);
 112
 113 /* Get a trace by its number identifier */
 114
 115 LttvTrace *lttvwindowtraces_get_trace(guint num);
 116
 117 /* Total number of traces */
 118
 119 guint lttvwindowtraces_get_number();
 120
 121 /* Add a trace to the global attributes */
 122
 123 void lttvwindowtraces_add_trace(LttvTrace *trace);
 124
 125 /* Remove a trace from the global attributes */
 126
 127 void lttvwindowtraces_remove_trace(LttvTrace *trace);
 128
 129
 130 /**
 131  * Function to request data from a specific trace
 132  *
 133  * The memory allocated for the request will be managed by the API.
 134  *
 135  * @param tab parent Window
 136  * @param trace the trace to compute
 137  * @param module_name the name of the module which registered global computation
 138  *                    hooks.
 139  */
 140
 141 void lttvwindowtraces_background_request_queue
 142                      (GtkWidget *widget, LttvTrace *trace, gchar *module_name);
 143
 144 /**
 145  * Remove a background request from a trace.
 146  *
 147  * This should ONLY be used by the modules which registered the global hooks
 148  * (module_name). If this is called by the viewers, it may lead to incomplete
 149  * and incoherent background processing information.
 150  *
 151  * Even if the module which deals with the hooks removes the background
 152  * requests, it may cause a problem if the module gets loaded again in the
 153  * session : the data will be partially calculated. The calculation function
 154  * must deal with this case correctly.
 155  *
 156  * @param trace the trace to compute
 157  * @param module_name the name of the module which registered global computation
 158  *                    hooks.
 159  */
 160
 161 void lttvwindowtraces_background_request_remove
 162                      (LttvTrace *trace, gchar *module_name);
 163
 164
 165
 166 /**
 167  * Find a background request in a trace
 168  *
 169  */
 170
 171 gboolean lttvwindowtraces_background_request_find
 172                      (LttvTrace *trace, gchar *module_name);
 173
 174 /**
 175  * Register a callback to be called when requested data is passed in the next
 176  * queued background processing.
 177  *
 178  * @param owner owner of the background notification
 179  * @param trace the trace computed
 180  * @param notify_time time when notification hooks must be called
 181  * @param notify_position position when notification hooks must be called
 182  * @param notify  Hook to call when the notify position is passed
 183  */
 184
 185 void lttvwindowtraces_background_notify_queue
 186  (gpointer                     owner,
 187   LttvTrace                   *trace,
 188   LttTime                      notify_time,
 189   const LttvTracesetContextPosition *notify_position,
 190   const LttvHooks                   *notify);
 191
 192 /**
 193  * Register a callback to be called when requested data is passed in the current
 194  * background processing.
 195  *
 196  * @param owner owner of the background notification
 197  * @param trace the trace computed
 198  * @param notify_time time when notification hooks must be called
 199  * @param notify_position position when notification hooks must be called
 200  * @param notify  Hook to call when the notify position is passed
 201  */
 202
 203 void lttvwindowtraces_background_notify_current
 204  (gpointer                     owner,
 205   LttvTrace                   *trace,
 206   LttTime                      notify_time,
 207   const LttvTracesetContextPosition *notify_position,
 208   const LttvHooks                   *notify);
 209
 210 /**
 211  * Removes all the notifications requests from a specific viewer.
 212  *
 213  * @param owner owner of the background notification
 214  */
 215
 216 void lttvwindowtraces_background_notify_remove(gpointer owner);
 217
 218
 219 /**
 220  * Tells if the information computed by a module for a trace is ready.
 221  *
 222  * Must be checked before a background processing request.
 223  *
 224  * @param module_name A GQuark : the name of the module which computes the
 225  *                    information.
 226  * @param trace The trace for which the information is verified.
 227  */
 228
 229 gboolean lttvwindowtraces_get_ready(LttvAttributeName module_name,
 230                                     LttvTrace *trace);
 231
 232 /**
 233  * Tells if the information computed by a module for a trace is being processed.
 234  *
 235  * Must be checked before a background processing request.
 236  *
 237  * If it is effectively processed, the typical thing to do is to call
 238  * lttvwindowtraces_background_notify_current to be notified when the current
 239  * processing will be over.
 240  *
 241  * @param module_name A GQuark : the name of the module which computes the
 242  *                    information.
 243  * @param trace The trace for which the information is verified.
 244  */
 245
 246 gboolean lttvwindowtraces_get_in_progress(LttvAttributeName module_name,
 247                                     LttvTrace *trace);
 248
 249 /**
 250  * Register the background computation hooks for a specific module. It adds the
 251  * computation hooks to the global attrubutes, under "computation/module name"
 252  *
 253  * @param module_name A GQuark : the name of the module which computes the
 254  *                    information.
 255  */
 256 void lttvwindowtraces_register_computation_hooks(LttvAttributeName module_name,
 257                                           LttvHooks *before_chunk_traceset,
 258                                           LttvHooks *before_chunk_trace,
 259                                           LttvHooks *before_chunk_tracefile,
 260                                           LttvHooks *after_chunk_traceset,
 261                                           LttvHooks *after_chunk_trace,
 262                                           LttvHooks *after_chunk_tracefile,
 263                                           LttvHooks *before_request,
 264                                           LttvHooks *after_request,
 265                                           LttvHooks *event_hook,
 266                                           LttvHooksById *event_hook_by_id,
 267                                           LttvHooks *hook_adder,
 268                                           LttvHooks *hook_remover);
 269 /**
 270  * Unregister the background computation hooks for a specific module.
 271  *
 272  * It also removes all the requests than can be currently processed by the
 273  * background computation algorithm for all the traces (list_in and list_out).
 274  *
 275  * @param module_name A GQuark : the name of the module which computes the
 276  *                    information.
 277  */
 278
 279 void lttvwindowtraces_unregister_computation_hooks
 280                                      (LttvAttributeName module_name);
 281
 282
 283 /**
 284  * It removes all the requests than can be currently processed by the
 285  * background computation algorithm for all the traces (list_in and list_out).
 286  *
 287  * Leaves the flag to in_progress or none.. depending if current or queue
 288  *
 289  * @param module_name A GQuark : the name of the module which computes the
 290  *                    information.
 291  */
 292 void lttvwindowtraces_unregister_requests(LttvAttributeName module_name);
 293
 294
 295 /**
 296  * Lock a trace so no other instance can use it.
 297  *
 298  * @param trace The trace to lock.
 299  * @return 0 on success, -1 if cannot get lock.
 300  */
 301 gint lttvwindowtraces_lock(LttvTrace *trace);
 302
 303
 304 /**
 305  * Unlock a trace.
 306  *
 307  * @param trace The trace to unlock.
 308  * @return 0 on success, -1 if cannot unlock (not locked ?).
 309  */
 310 gint lttvwindowtraces_unlock(LttvTrace *trace);
 311
 312 /**
 313  * Verify if a trace is locked.
 314  *
 315  * @param trace The trace to verify.
 316  * @return TRUE if locked, FALSE is unlocked.
 317  */
 318 gint lttvwindowtraces_get_lock_state(LttvTrace *trace);
 319
 320
 321 #endif //LTTVWINDOWTRACES_H