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 -10.
  99
 100 If state has to be computed, lttv_process_traceset_begin is called to add state
 101 hooks to the context. Then, the state seek_closest will have to be used to
 102 restore the nearest state, plus a process_traceset with no hooks present other
 103 than the state hooks will have to be called to go from the closest state to the
 104 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 _LttvTracesetContextPosition {
 116   LttEventPosition *tracefile_position;  /* Position in each trace/tracefile */
 117   guint num_tracefiles;                   /* Number of tracefiles (check)     */
 118 }
 119
 120 with interfaces :
 121
 122 lttv_traceset_context_position_save
 123 (const LttvTracesetContext *context,
 124  LttvTracesetContextPosition *pos);
 125
 126
 127 Dependencies :
 128
 129 - lttv_process_traceset_seek_position(LttvTracesetContext *self,
 130                                 const LttvTracesetContextPosition *position);
 131     - ltt_tracefile_seek_position : already implemented
 132
 133 lttv_process_traceset_seek_position will seek each tracefile to the right
 134 position. We keep information about number of tracefiles for extra integrity
 135 checking when reloading the position in the context.
 136
 137
 138
 139 - lttv_process_traceset_middle
 140 We modify lttv_process_traceset_middle so that it takes as arguments :
 141 (LttvTracesetContext *self,
 142 LttTime end,
 143 unsigned num_events,
 144 const LttvTracesetContextPosition *end_position)
 145
 146 This new version of process traceset middle will call the middle hooks for
 147 events until the first criterion is fulfilled : either the end time is passed,
 148 the number of events requested is passed or the end position is reached. When
 149 this function ends, the end position can be extracted from the context, the end
 150 event is set as described below and the number of events read is returned.
 151
 152 The end event is a pointer to the last event the hooks has been called for.
 153
 154 - lttv_process_traceset_seek_time : already implemented
 155
 156 - lttv_process_traceset_begin(LttvTracesetContext *self,
 157                               LttvHooksById *begin_hooks,
 158                               LttvHooksById *middle_hooks)
 159
 160
 161 - lttv_process_traceset_end(LttvTracesetContext *self,
 162                               LttvHooksById *end_hooks,
 163                               LttvHooksById *middle_hooks)
 164
 165 - lttv_traceset_context_add_hooks and lttv_traceset_context_remove_hooks
 166
 167 These functions now become internal to tracecontext.c
 168
 169
 170
 171