explain viewer stop_flag

[lttv.git] / ltt / branches / poly / doc / developer / lttvwindow_events_delivery.txt

diff --git a/ltt/branches/poly/doc/developer/lttvwindow_events_delivery.txt b/ltt/branches/poly/doc/developer/lttvwindow_events_delivery.txt
index fd29ab561b9395f1751e9cc8f1ac507d920d1784..f310dce9973ab29cb7ce1aa682775b83d059b890 100644 (file)
--- a/ltt/branches/poly/doc/developer/lttvwindow_events_delivery.txt
+++ b/ltt/branches/poly/doc/developer/lttvwindow_events_delivery.txt
@@ -140,20 +140,9 @@ Architecture
 Added to the lttvwindow API :
 
 
-- lttvwindow_events_request
-( MainWindow          *main_win,
-  LttTime              start_time,
-  LttvTracesetPosition start_position,
-  LttTime              end_time,
-  guint                num_events,
-  LttvTracesetPosition end_position,
-  LttvHooksById        before_traceset,
-  LttvHooksById        before_trace,
-  LttvHooksById        before_tracefile,
-  LttvHooksById        middle,
-  LttvHooksById        after_tracefile,
-  LttvHooksById        after_trace,
-  LttvHooksById        after_traceset)
+void lttvwindow_events_request
+( MainWindow                  *main_win,
+  EventsRequest               *events_request);
 
 
 Internal functions :
@@ -177,22 +166,27 @@ each viewer through process traceset.
 
 - lttvwindow_events_request
 
-It adds the EventsRequest struct to the array of time requests pending and
-registers a pending request for the next g_idle if none is registered.
+It adds the a pointer to the EventsRequest struct to the array of time requests
+pending and registers a pending request for the next g_idle if none is
+registered. The viewer has to keep a reference to this structure in its own
+instance data structure. Only the stop_flag can be changed by the viewer
+through the event hooks.
 
 typedef struct _EventsRequest {
-  LttTime              start_time,
-  LttvTracesetPosition start_position,
-  LttTime              end_time,
-  guint                num_events,
-  LttvTracesetPosition end_position,
-  LttvHooksById        before_traceset,
-  LttvHooksById        before_trace,
-  LttvHooksById        before_tracefile,
-  LttvHooksById        middle,
-  LttvHooksById        after_tracefile,
-  LttvHooksById        after_trace,
-  LttvHooksById        after_traceset)
+  LttTime                     start_time,       /* Unset : { 0, 0 }         */
+  LttvTracesetContextPosition start_position,   /* Unset : num_traces = 0   */
+  gboolean                    stop_flag,        /* Continue:TRUE Stop:FALSE */
+  LttTime                     end_time,         /* Unset : { 0, 0 }         */
+  guint                       num_events,       /* Unset : G_MAXUINT        */
+  LttvTracesetContextPosition end_position,     /* Unset : num_traces = 0   */
+  LttvHooks                  *before_traceset,  /* Unset : NULL             */
+  LttvHooks                  *before_trace,     /* Unset : NULL             */
+  LttvHooks                  *before_tracefile, /* Unset : NULL             */
+  LttvHooks                  *event,            /* Unset : NULL             */
+  LttvHooksById              *event_by_id,      /* Unset : NULL             */
+  LttvHooks                  *after_tracefile,  /* Unset : NULL             */
+  LttvHooks                  *after_trace,      /* Unset : NULL             */
+  LttvHooks                  *after_traceset    /* Unset : NULL             */
 } EventsRequest;
 
 
@@ -238,7 +232,7 @@ While list_in !empty and list_out !empty
       (1.3.2 middle hooks added)
   2. Else, list_in is not empty, we continue a read
     2.1 For each req of list_out
-    - if req.start time == current time
+    - if req.start time == current context time
       - Add to list_in, remove from list_out
       - Call begin
     - if req.start position == current position
@@ -259,27 +253,32 @@ While list_in !empty and list_out !empty
 
   4. Call process traceset middle
     4.1 Call process traceset middle (Use end criterion found in 3)
+      * note : end criterion can also be viewer's hook returning TRUE
   5. After process traceset middle
     5.1 For each req in list_in
           - req.num -= count
           - if req.num == 0
             - Call end for req
             - remove req from list_in
-          - if req.end time == current time
+          - if current context time > req.end time
             - Call end for req
             - remove req from list_in
           - if req.end pos == current pos
             - Call end for req
             - remove req from list_in
+          - if req.stop_flag == TRUE
+            - Call end for req
+            - remove req from list_in
 
 
 
 Notes :
 End criterions for process traceset middle :
 If the criterion is reached, event is out of boundaries and we return.
-Current time > End time
+Current time >= End time
 Event count > Number of events
 Current position >= End position
+Last hook list called returned TRUE
 
 The >= for position is necessary to make ensure consistency between start time
 requests and positions requests that happens to be at the exact same start time