viewer -> lttvwindow name change

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

diff --git a/ltt/branches/poly/doc/developer/requests_servicing_schedulers.txt b/ltt/branches/poly/doc/developer/requests_servicing_schedulers.txt
index 40227fa2c2d6be144f8f146f809bdbdbe1274bf3..3686939be38b540437f690bdb7ad10e499504eac 100644 (file)
--- a/ltt/branches/poly/doc/developer/requests_servicing_schedulers.txt
+++ b/ltt/branches/poly/doc/developer/requests_servicing_schedulers.txt
@@ -61,12 +61,84 @@ specified time intervals.
 
 Background Scheduler
 
 
 Background Scheduler
 

-It has its own events requests pool. It services them just like a foreground
-scheduler. The difference comes in that there may be duplicated requests :
-for instance, statistics computation for a trace can be asked by two viewers
-at the same time. Another difference is that the hook_data of theses requests
-will typically be NULL, and the typical hook function will be located in a
-library upon which the viewer depends.
+Right now, to simplify the problem of the background scheduler, we assume that
+the module that loads the extended statistics hooks has been loaded before the
+data is requested and that it is not unloaded until the program stops. We will
+eventually have to deal with the requests removal based on module load/unload,
+but it complicates the problem quite a bit.
+
+A background scheduler adds hooks located under a global attributes path
+(specified by the viewer who makes the request) to the trace's traceset
+context (the trace is specified by the viewer). Then, it processes the whole
+trace with this context (and hooks).
+
+Typically, a module that extends statistics will register hooks in the global
+attributes tree under /TraceState/Statistics/ModuleName/hook_name . A viewer
+that needs these statistics for a set of traces does a background computation
+request through a call to the main window API function. It must specify all
+types of hooks that must be called for the specified trace.
+
+The background computation requests for a trace are queued. When the idle
+function kicks in to answer these requests, it add the hooks of all the requests
+toghether in the context and starts the read. It also keeps a list of the
+background requests currently serviced.
+
+The read is done from start to end of the trace, calling all the hooks present
+in the context. Only when the read is over, the after_request hooks of the
+currently serviced requests are called and the requests are destroyed.
+
+If there are requests in the waiting queue, they are all added to the current
+pool and processed. It is important to understand that, while a processing is in
+being done, no requests are added to the pool : they wait for their turn in the
+queue.
+
+Every hook that are added to the context by the scheduler comes from global
+attributes, i.e.
+/traces/trace_path/TraceState/Statistics/ModuleName/hook_name
+
+They come with a flag telling either in_progress or ready. If the flag
+ready is set, a viewer knows that the data it needs is already ready and he
+doesn't have to make a request.
+
+If the flag in_progress is set, that means that the data it needs is currently
+being serviced, and it must wait for the current servicing to be finished. It
+tells the lttvwindow API to call a hook when the actual servicing is over (there
+is a special function for this, as it requires to modify the pool of requests
+actually being serviced : we must make sure that no new reading hooks are
+added!).
+
+
+
+
+
+New Global Attributes
+
+When a hook is added to the trace context, The variable
+/traces/trace_path/TraceState/Statistics/ModuleName/hook_name is set.
+
+When a processing is fired, a variable
+/traces/trace_path/TraceState/Statistics/ModuleName/in_progress is set.
+
+When a processing finished, a variable
+/traces/trace_path/TraceState/Statistics/ModuleName/in_progress is unset
+/traces/trace_path/TraceState/Statistics/ModuleName/ready is set
+
+
+
+
+
+Typical Use For a Viewer
+
+When a viewer wants extended information, it must first check if it is ready.
+if not :
+Before a viewer makes a request, it must check the in_prgoress status of the
+hooks.
+
+If the in_progress is unset, it makes the request.
+
+If the in_progress is set, it makes a special request for being informed of the
+end of request.
+

 
 
 
 
 
 


@@ -79,6 +151,61 @@ from the list. Two hooks are identical if they have the same function pointer
 and hook_data.
 
 
 and hook_data.
 
 

+
+
+
+
+Implementation
+
+Ad Hoc Computation
+
+see lttvwindow_events_delivery.txt
+
+
+Hooks Lists
+
+need new ref_count field with each hook
+lttv_hook_add and lttv_hook_add_list must compare addition with present and
+increment ref counter if already present.
+
+lttv_hook_remove and remove_with_data must decrement ref_count is >1, or remove
+the element otherwise (==1).
+
+
+
+Background Scheduler
+
+Global traces
+
+Two global attributes per trace : 
+/traces/path_to_trace/LttvTrace
+  It is a pointer to the LttvTrace structure.
+/traces/path_to_trace/LttvBackgroundComputation
+/traces/path_to_trace/TraceState/...  hooks to add to background computation
+                                      in_progress and ready flags.
+
+struct _LttvBackgroundComputation {
+  GSList *events_requests;
+ /* A GSList * to the first events request of background computation for a
+  * trace. */
+  LttvTraceset *ts;
+ /* A factice traceset that contains just one trace */
+  LttvTracesetContext *tsc;
+ /* The traceset context that reads this trace */
+}
+
+
+
+
+Modify Traceset
+Points to the global traces. Opens new one only when no instance of the pathname
+exists.
+
+Modify LttvTrace ?
+
+Modify trace opening / close to make them create and destroy
+LttvBackgroundComputation (and call end requests hooks for servicing requests ?)
+

 EventsRequest Structure
 
 This structure is the element of the events requests pools. The viewer field is
 EventsRequest Structure
 
 This structure is the element of the events requests pools. The viewer field is


@@ -89,10 +216,36 @@ structure.
 In a ad hoc events request, a pointer to this structure is used as hook_data in
 the hook lists
 
 In a ad hoc events request, a pointer to this structure is used as hook_data in
 the hook lists
 

-The typical case for a background computation is that the hook_data will be set
-to NULL instead. No particular hook_data is needed as this type of request does
-only modify trace related data structures which are available through the
-call_data.

 
 
 
 

+Background Requests Servicing Algorithm (v1)
+
+
+list_in : currently serviced requests
+list_out : queue of requests waiting for processing
+
+
+1. Before processing
+  if list_in is empty
+    - Add all requests in list_out to list_in, empty list_out
+    - for each request in list_in
+      - add hooks to context
+      - set hooks'in_progress flag to TRUE
+    - seek trace to start
+
+2. call process traceset middle for a chunk
+  (assert list_in is not empty! : should not even be called in that case)
+
+3. After the chunk
+  3.1 call after_chunk hooks from list_in
+  3.2 if end of trace reached
+    - for each request in list_in
+      - set hooks'in_progress flag to FALSE
+      - set hooks'ready flag to TRUE
+      - call end request
+      - remove hooks from context
+      - remove request
+    - return FALSE (scheduler stopped)
+  3.3 else
+    - return TRUE (scheduler still registered)