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.
  12
  13 They are splitted in two different categories : the first one is the one where
  14 the viewers select the events they need by specifying a time interval in the
  15 traceset and the second one is where the viewers specify a start event by it's
  16 position in the traceset and a certain amount of events it needs.
  17
  18
  19
  20 Control Flow Viewer
  21
  22 This viewer, consisting in a two dimensions graph, shows the different processes
  23 as its y axis and the time as x axis. It's clear that it needs to get the events
  24 by specifying a start time and an end time, constituing a time interval.
  25
  26
  27 Detailed Events List
  28
  29 This list has nothing to do with time : it shows the events one by one. It cares
  30 about the quantity of events, not their time.
  31
  32 It would be simple to get the events one by one if we were reading only one
  33 tracefile (one cpu), but the way events are read through each trace
  34 (monothically increasing time) makes it a little bit more difficult to specify
  35 how to increment event position. We will determine how it could be done simply.
  36
  37 Let's define an event position. It's composed of a tracefile number, a bloc
  38 number and an index in the bloc.
  39
  40 A viewer could ask for a specific event position as a start event. It would
  41 specify a number of events it needs. As a first call, it could ask for tracefile
  42 0, bloc 0, event 0. Afterward, it can reuse information from events delivered to
  43 keep track of the next events it needs.
  44
  45 Now, let's see how process traceset could handle it. It would seek in the
  46 traceset, searching the position number.
  47 (need a new lttv_process_traceset_seek_position)
  48
  49 Then, the viewer could simply call a process traceset function specifying a
  50 number of events to get.
  51
  52 The whole concept of numbering events would be hidden in the order in which the
  53 process traceset gets the events in a monothically increasing time.
  54
  55 We sould specify that a request from such a viewer should be of one more event
  56 than needed : it would use the last event position to seek in the traceset for
  57 the next read. So, for example, a request for 50 events would ask for 51,
  58 keeping the event position of event 51.
  59
  60
  61
  62 2. Architecture
  63
  64 Two different sets of API functions offered to read tracesets :
  65
  66 lttv_process_traceset_seek_time
  67 lttv_process_traceset_middle_time
  68
  69 lttv_process_traceset_seek_position
  70 lttv_process_traceset_middle_position
  71 lttv_traceset_context_position_save
  72
  73
  74 Of course, the typical use will be to call the seek_time with the middle_time,
  75 and similarly for position functions, but the architecture does permit viewers
  76 to mix calls to _time and _position functions.
  77
  78 The position_save saves a position that can be used later to seek back to this
  79 exact same position, with event granularity. This implies that the
  80 process_traceset must deliver events with the same timestamp in a deterministic
  81 manner.
  82
  83
  84 3. Implementation in tracecontext.c
  85
  86
  87 - Type LttvTracesetContextPosition
  88
  89 struct _LttvTracesetContextPosition {
  90   LttEventPosition **tracefile_position;  /* Position in each trace/tracefile */
  91   guint num_traces;                       /* Number of traces (for check)     */
  92   guint num_tracefiles;                   /* Number of tracefiles (check)     */
  93   GTree *pqueue;                          /* Copy of context pqueue           */
  94 }
  95
  96 with interfaces :
  97
  98 lttv_traceset_context_position_save
  99 (const LttvTracesetContext *context,
 100  LttvTracesetContextPosition *pos);
 101
 102
 103 Dependencies :
 104
 105 - lttv_process_traceset_seek_position
 106   - lttv_process_trace_seek_position
 107     - ltt_tracefile_seek_position : already implemented
 108
 109 lttv_process_traceset_seek_position will seek each trace to the right position.
 110 Each trace will seek all of its tracesets to the right position. We keep
 111 information about number of traces and tracefiles for extra integrity checking
 112 when reloading the context.
 113
 114 lttv_process_traceset_seek_position(LttvTracesetContext *self,
 115                                 const LttvTracesetContextPosition *position);
 116
 117
 118 - lttv_process_traceset_middle_position
 119 We modify lttv_process_traceset_middle so that it takes as arguments :
 120 (LttvTracesetContext *self,
 121 const LttvTracesetContextPosition *end_position,
 122 unsigned max_num_events)
 123
 124 It's a simplification of the original function that will just read events until
 125 the first criterion is fulfilled : the end_position is reached (we do not
 126 deliver the event at the end_position) or the maximum number of events specified
 127 is reached (we deliver the last event, corresponding to the maximum number of
 128 events). The first event in the LttvTracesetContextPosition's pqueue will be
 129 used as end_event.
 130
 131 - lttv_process_traceset_seek_time : already implemented
 132
 133 - lttv_process_traceset_middle_time
 134 It's basically the same function as lttv_process_traceset_middle. We keep the
 135 nb_events as a limit of events to read. We also keep the fact that, when the
 136 maximum number of events is triggered, we also read the events that has the same
 137 timestamp. This is useful for not losing events. The fact is that a viewer that
 138 rely on time to select events it needs cannot have the granularity it needs to
 139 select specific events from a bunch of events with the same time stamp.
 140
 141
 142