WORK IN PROGRESS
\end_layout
-\begin_layout Section
-Introduction
-\end_layout
-
\begin_layout Standard
This document proposes some APIs for a trace viewing and analysis infrastructure.
\end_layout
Each time is accompanied by an uncertainty value.
\end_layout
+\begin_layout Subsection
+Modules
+\end_layout
+
+\begin_layout Standard
+The following modules should be part of the framework.
+ This list does not include modules related to the GUI, the controlling
+ of traces and the transfer of traces.
+\end_layout
+
+\begin_layout Description
+Trace Has one instance per open trace.
+ Allows the access to a trace by exporting the Low-level Trace Reading API.
+ The underlying implementation may change from one trace to another to adapt
+ to the specific format of each trace.
+\end_layout
+
+\begin_layout Description
+Traceset Receives data from several Traces using their Low-Level Trace Reading
+ API and merge them in a single stream.
+ May also receive data from other instances of Traceset.
+ Exports the High-level Trace Reading API and the Low-level Trace Reading
+ API.
+ Handles time offsetting if necessary to align traces.
+ Handles filtering.
+\end_layout
+
+\begin_layout Description
+State\InsetSpace ~
+providers They receive the stream of events from the Traceset, using
+ the High-level Trace Reading API.
+ They detect state changes.
+ Each one is designed to detect states of a particular level (kernel, applicatio
+n-level, UML states).
+ It pushes the detected states to the State module using the State Setting
+ API.
+\end_layout
+
+\begin_layout Description
+State Records changes in the system state received from State providers
+ by the State Setting API.
+ It implements an efficient state searching engine.
+ Exports the State Accessing API to allow plugins to access the information.
+\end_layout
+
+\begin_layout Description
+Event\InsetSpace ~
+description Receives the stream of events from the Traceset using the
+ High-level Trace Reading API.
+ It reads the events that describe other events and stores the information
+ they contain, possibly using the State module.
+ Other components can access this information through an exported API.
+\end_layout
+
+\begin_layout Description
+Plugins...
+ These are the graphical views, analyses and other components that need
+ access to the events.
+ They receive data from a traceset using the High-level Trace Reading API.
+ They use the services they need (State, Event Description, and/or others).
+ They may export a special API if other components need to access their
+ data.
+\end_layout
+
\begin_layout Section
Low level reading of traces
\end_layout
High level reading of traces
\end_layout
+\begin_layout Subsection
+Overview
+\end_layout
+
\begin_layout Standard
When reading/analyzing/viewing several traces of heterogenous types, these
traces are read by translator modules, which export the Low Level Trace
\end_layout
\end_deeper
-\begin_layout Subsection
+\begin_layout Itemize
+void traceset_process(struct traceset *tr, struct timeval *tv)
+\end_layout
+
+\begin_deeper
+\begin_layout Standard
+Process requests for the time specified by tv, then return to the caller.
+ The time is a wall time and has no relationship with the timestamps of
+ the trace.
+ It is used to process a part of the trace while allowing a GUI to remain
+ responsive.
+\end_layout
+
+\begin_layout Standard
+Arguments:
+\end_layout
+
+\begin_layout Itemize
+tr: the traceset
+\end_layout
+
+\begin_layout Itemize
+tv: the duration for which to process the trace
+\end_layout
+
+\end_deeper
+\begin_layout Section
State management
\end_layout
\begin_layout Standard
Keys are character strings.
+ They are organized in a filesystem-like hierarchy.
+\end_layout
+
+\begin_layout Standard
+Each key/value pair is associated either to a specific trace or to the traceset.
+\end_layout
+
+\begin_layout Standard
+State can persist between runs of the program.
+ This is useful both to reduce pre-calculation times when re-opening a trace,
+ and also to keep general parameters like bookmarks.
+\end_layout
+
+\begin_layout Standard
+It is possible to assign a state to the time range -infinity..infinity to
+ indicate that it is global to the trace.
\end_layout
\begin_layout Standard
\end_layout
\begin_layout Itemize
-blob (binary block of arbitrary length)
+uint64
\end_layout
\begin_layout Itemize
-float32
+int64
\end_layout
\begin_layout Itemize
-float64
+blob (binary block of arbitrary length)
\end_layout
-\begin_layout Standard
-The state information must be persistent between executions of the framework.
+\begin_layout Itemize
+float32
\end_layout
-\begin_layout Standard
-It is possible to assign a state to the range -infinity..infinity to indicate
- that it is global to the trace.
+\begin_layout Itemize
+float64
\end_layout
-\begin_layout Standard
-The key names should be hierarchical.
+\begin_layout Itemize
+others?
\end_layout
-\begin_layout Subsubsection
-State accessing API
+\begin_layout Subsection
+Methods of the State Accessing API
\end_layout
\begin_layout Itemize
\end_layout
\begin_layout Itemize
-The state value
+The state value.
+ A struct state_value contains the value and the time interval that applies
+ to it.
\end_layout
\end_deeper
\begin_deeper
\begin_layout Standard
-Request all the states changes of a given set of state variables between
+Request all the state changes of a given set of state variables between
two time indexes
\end_layout
range: the time range
\end_layout
+\begin_layout Standard
+Return value:
+\end_layout
+
+\begin_layout Itemize
+The values
+\end_layout
+
\end_deeper
\begin_layout Itemize
Other functions for getting values for a set of keys at once?
\end_layout
-\begin_layout Subsubsection
-State setting API
+\begin_layout Subsection
+Methods of the State Setting API
\end_layout
\begin_layout Itemize
\end_deeper
\begin_layout Subsection
-Event type description API
+Methods of the Event Type Description API
\end_layout
\begin_layout Standard
\end_layout
\begin_layout Subsection
-Event inspecting API
+Methods of the Event inspecting API
\end_layout
\begin_layout Itemize
\end_layout
\begin_layout Subsection
-Trace control API
+Methods of the Trace Control API
\end_layout
\begin_layout Itemize
\end_inset
+\end_layout
+
+\begin_layout Standard
+\begin_inset Note Note
+status open
+
+\begin_layout Section*
+TODO
+\end_layout
+
+\begin_layout Itemize
+extend APIs for monitoring (case where the flow of events is constant and
+ we cannot keep the whole trace forever)
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+views must be able to register the fact that they need the whole trace if
+ they do
+\end_layout
+
+\begin_layout Itemize
+there must be an elegant way to destroy old events
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+add API or infos about interaction with gui? ex: how traceset_process should
+ be called
+\end_layout
+
+\end_inset
+
+
\end_layout
\end_body