ltt/branches/poly/doc/developer/process_traceset_strict_boundaries.txt

   1 Linux Trace Toolkit
   2
   3 Mathieu Desnoyers 17-05-2004
   4
   5
   6 1. Read Requests Cases Study
   7
   8 The goal of this document is to describe the typical behavior of viewers when
   9 they request data to a process traceset. After the implementation of three
  10 viewers, with different needs, the idea of their need for a trace processing API
  11 is getting clearer. We then describe a new API for process traceset that would
  12 better suits the needs of those viewers.
  13
  14 They are splitted in two different categories : the first one is the one where
  15 the viewers select the events they need by specifying a time interval in the
  16 traceset and the second one is where the viewers specify a start event by its
  17 position in the traceset and a certain amount of events it needs.
  18
  19 This is a simplified case study : we look at the direct interaction between
  20 graphical viewers and process traceset, without the main window as a negociator.
  21
  22 Control Flow Viewer
  23
  24 This viewer, consisting in a two dimensions graph, shows the different processes
  25 as its y axis and the time as x axis. It's clear that it needs to get the events
  26 by specifying a start time and an end time, constituing a time interval.
  27
  28
  29 Detailed Events List
  30
  31 This list has nothing to do with time : it shows the events one by one. It cares
  32 about the quantity of events, not their time.
  33
  34 It would be simple to get the events one by one if we were reading only one
  35 tracefile (one cpu), but the way events are read through each trace
  36 (monothically increasing time) makes it a little bit more difficult to specify
  37 how to increment event position. We will determine how it could be done simply.
  38
  39 Let's define an event position. It's a pointer to a position into each
  40 tracefile. It's only meaningful when associated with a context. Comparisons
  41 between positions are done by looking comparing saved positions for each
  42 tracefile, until a difference is found.
  43
  44 A viewer could use a start time as a start event. It would specify a number of
  45 events it needs. As a first call, it could ask for the start time of the
  46 traceset. Afterward, it can save the position of the context after the last
  47 event has been delivered in its after traceset function.
  48
  49 Now, let's see how process traceset could handle it. It would seek in the
  50 traceset, searching the position number.
  51 (need a new lttv_process_traceset_seek_position)
  52
  53 Then, the viewer could simply call a process traceset middle function
  54 specifying a number of events to get.
  55
  56 The whole concept of numbering events would be hidden in the order in which the
  57 process traceset gets the events in a monothically increasing time.
  58
  59
  60
  61 2. Architecture
  62
  63 API to seek/read traceset will be extended to fully support both start time,
  64 start position, end time, end position and number of events as possible
  65 boundaries for reading.
  66
  67 lttv_process_traceset_seek_time
  68 lttv_process_traceset_seek_position
  69
  70 lttv_process_traceset_middle
  71
  72 It must be modified to end when it encounters the first criterion : number of
  73 events to read reached, end time reached, end position reached.
  74
  75 lttv_traceset_context_position_save
  76
  77 The position_save saves a position that can be used later to seek back to this
  78 exact same position, with event granularity. This implies that the
  79 process_traceset must deliver events with the same timestamp in a deterministic
  80 manner. This is actually done by using tracefile and trace numbers in the
  81 context in the comparison function.
  82
  83
  84
  85 Description of new context API useage
  86
  87 1. seek
  88 2. begin  -> add middle hooks
  89           -> call begin hooks by id
  90 3. middle -> call middle hooks by id
  91 4. end    -> call end hooks by id
  92           -> remove middle hooks
  93
  94 3. Impact on State
  95
  96 From now on, the state computation will be done in the middle hook call, with a
  97 priority higher than default. We will define this priority as PRIO_STATE,
  98 defined to 25.
  99
 100 If state has to be computed, lttv_process_traceset_begin has to be  called in
 101 a first time. It adds the state hooks to the context. Then, the state
 102 seek_closest will have to be used to restore the nearest state, plus a
 103 process_traceset with no hooks present other than the state hooks will have to
 104 be called to go from the closest state to the real time seeked.
 105
 106 The lttv_process_traceset_end will only need to be called if no further state
 107 computation is needed.
 108
 109
 110 4. Implementation in tracecontext.c
 111
 112
 113 - Type LttvTracesetContextPosition
 114
 115 struct _LttvTraceContextPosition {
 116   LttEventPosition *tf_pos;          /* Position in each trace           */
 117   guint nb_tracefile;                /* Number of tracefiles (check)     */
 118 }
 119
 120 struct _LttvTracesetContextPosition {
 121   LttTraceContextPosition *t_pos;    /* Position in each trace           */
 122   guint nb_trace;                    /* Number of traces (check)         */
 123 }
 124
 125 with interfaces :
 126
 127 lttv_traceset_context_position_save
 128 (const LttvTracesetContext *context,
 129  LttvTracesetContextPosition *pos);
 130
 131
 132 Dependencies :
 133
 134 - lttv_process_traceset_seek_position(LttvTracesetContext *self,
 135                                 const LttvTracesetContextPosition *position);
 136     - ltt_tracefile_seek_position : already implemented
 137
 138 lttv_process_traceset_seek_position will seek each tracefile to the right
 139 position. We keep information about number of tracefiles for extra integrity
 140 checking when reloading the position in the context. It also loads the pqueue.
 141
 142
 143
 144 - lttv_process_traceset_middle
 145 We modify lttv_process_traceset_middle so that it takes as arguments :
 146 (LttvTracesetContext *self,
 147 LttTime end,
 148 unsigned nb_events,
 149 const LttvTracesetContextPosition *end_position)
 150
 151 This new version of process traceset middle will call the event hooks for
 152 events until the first criterion is fulfilled : either the end time is reached,
 153 the number of events requested is passed, the end position is reached or the
 154 last event hook list called returned TRUE. When this function ends, the end
 155 position can be extracted from the context, the end event is set as described
 156 below and the number of events read is returned.
 157
 158 The end event is a pointer to the last event the hooks has been called for.
 159
 160 - lttv_process_traceset_seek_time : already implemented
 161   - now loads the pqueue.
 162
 163 - lttv_process_traceset_begin(LttvTracesetContext *self,
 164                               LttvHooks       *before_traceset,
 165                               LttvHooks       *before_trace,
 166                               LttvHooks       *before_tracefile,
 167                               LttvHooks       *event,
 168                               LttvHooksById   *event_by_id)
 169
 170
 171 - lttv_process_traceset_end(LttvTracesetContext *self,
 172                             LttvHooks           *after_traceset,
 173                             LttvHooks           *after_trace,
 174                             LttvHooks           *after_tracefile,
 175                             LttvHooks           *event,
 176                             LttvHooksById       *event_by_id)
 177
 178 - lttv_traceset_context_add_hooks and lttv_traceset_context_remove_hooks
 179
 180 These functions now become internal to tracecontext.c
 181
 182
 183
 184