Commit 3413abae authored by Mathieu Faverge's avatar Mathieu Faverge

add plugins and docs directory

parent c7714fc6
pile_pos : PILE d'entiers
pile_hauteur : PILE de reels
buf : conteneur
x : reel
y : reel
y_buf : reel
buf <- conteneur_racine
pile_pos.empiler(0)/* la racine */
pile_hauteur.empiler(0)/* hauteur de dessin de la racine */
si buf.nbFils() <= 1
x <- #LONGUEUR_CONTENEUR#
sinon
x <- #HAUTEUR_CONTENEUR#
y_buf <- 0
resteConteneur = vrai
tant que resteConteneur=vrai faire/* au moins un élément */
pos : Entier;
pos <- pile_pos.depiler()
si pos < buf.nbFils()
pile_pos.empiler(pos+1)
pile_pos.empiler(0)/* prepare pour le prochain */
buf <- buf.fils(pos)
si buf.nbFils() <= 1
x <- x + #LONGUEUR_CONTENEUR# + H_espace
sinon
x <- x + #HAUTEUR_CONTENEUR# + H_espace
sinon /* on a lu tous les fils ou il y en a aucun */
si buf.nbFils() <= 1
/* Si on n'a pas de fils, on augmente la hauteur des container */
si buf.nbFils() = 0
/* on recupere la valeur de la hauteur -> si aucun ou un fils : hauteur courante */
y_buf = #HAUTEUR_CONTENEUR#+V_espace
pile_hauteur.empiler(y_buf)
y += y_buf/* y contient la hauteur courante, y_buf la hauteur à ajouter */
/* Si 1 fils, y reste inchange */
dessiner horizontalement buf d'une longueur de #LONGUEUR_CONTENEUR# et d'une hauteur de #HAUTEUR_CONTENEUR# à la position x et y (dessin de la pointe superieur droite)
x <- x - #LONGUEUR_CONTENEUR# - H_espace
sinon
hauteur_buf <- 0
Pour tous les fils de buf
hauteur_buf <- hauteur_buf + pile_hauteur.depiler()/* on empile les hauteurs de tous les fils */
pile_hauteur.empiler(hauteur_buf) /* rempile la hauteur du container courant (pour être utilisé par son père plus tard) */
dessiner vericalement buf d'une hauteur égale à hauteur_buf et d'une largeur de #HAUTEUR_CONTENEUR# à la position x et y (dessin de la pointe superieur droite)
x <- x - #HAUTEUR_CONTENEUR# - H_espace
si buf.aPere() = vrai
buf <- buf.pere()
sinon
resteConteneur = faux
%%
%% This file is part of the ViTE project.
%%
%% This software is governed by the CeCILL-A license under French law
%% and abiding by the rules of distribution of free software. You can
%% use, modify and/or redistribute the software under the terms of the
%% CeCILL-A license as circulated by CEA, CNRS and INRIA at the following
%% URL: "http://www.cecill.info".
%%
%% As a counterpart to the access to the source code and rights to copy,
%% modify and redistribute granted by the license, users are provided
%% only with a limited warranty and the software's author, the holder of
%% the economic rights, and the successive licensors have only limited
%% liability.
%%
%% In this respect, the user's attention is drawn to the risks associated
%% with loading, using, modifying and/or developing or reproducing the
%% software by the user in light of its specific status of free software,
%% that may mean that it is complicated to manipulate, and that also
%% therefore means that it is reserved for developers and experienced
%% professionals having in-depth computer knowledge. Users are therefore
%% encouraged to load and test the software's suitability as regards
%% their requirements in conditions enabling the security of their
%% systems and/or data to be ensured and, more generally, to use and
%% operate it in the same conditions as regards security.
%%
%% The fact that you are presently reading this means that you have had
%% knowledge of the CeCILL-A license and that you accept its terms.
%%
%%
%% ViTE developers are:
%%
%% - COULOMB Kevin
%% - FAVERGE Mathieu
%% - JAZEIX Johnny
%% - LAGRASSE Olivier
%% - MARCOUEILLE Jule
%% - NOISETTE Pascal
%% - REDONDY Arthur
%% - VUCHENER Clément
%%
The data structure is composed by 2 main parts~:
\begin{itemize}
\item The first one where while parsing double chained list are built,
\item The second are trees that are built above the lists.
\end{itemize}
\section{The Main classes}
To represent the diversity of the Paj\'e trace format, we have created a wide variety of class that represent the various abstractions on objects~:
\begin{itemize}
\item Trace
\item Container
\item State
\item Event
\item Variable
\item Entity
\end{itemize}
Moreover, we had to create some other classes that help creating these objects such as their type. The definition of these types is necessary to use polymorphism in the optionnal fields that can be added (they all inherit from the Value class).
The basic types used in the data structure are defined in the \textit{values} directory. These types are :
\begin{itemize}
\item Color
\item Date
\item Double
\item Hex
\item Integer
\item Name
\item String
\item Value
\end{itemize}
The definitions for the tree and the interval are in the \textit{tree} directory.
\subsection{The class Trace}
The class \textit{Trace} represents the trace object generated by the user. It contains the elements~:
\begin{itemize}
\item List of type of container
\item List of container
\item List of states
\item List of events
\item List of links
\item List of variables
\end{itemize}
Moreover an attribute that contains the date when the latest action happens in the trace has been created. The methods only enable the construction of the trace, the possibility to get the values of the attributes, and to research some elements in the trace.
\subsection{The class container}
It represents an object of type container. In this class, there are~:
\begin{itemize}
\item A name
\item The date of the beginning and end of the container
\item Type of container
\item A father
\item A list of children
\item Set of states, events, links, and their cardinal
\end{itemize}
The methods are accessors.
\subsection{The class State}
It represents a state of a processor, a container. This class contains the only object of Paj\'e that is not directly presented. Because the use of trees of punctual events, we do not consider the states but the change of states as a relevant facts.
This class has~:
\begin{itemize}
\item Dates of beginning and end
\item Type of state
\item A descriptor of the value of the state, contains the optionnal fields.
\end{itemize}
The methods are accessors and a constructor attribute by attribute.
\subsection{The class event}
It represents an event that occurs in the trace. An event is made by~:
\begin{itemize}
\item A date when it occurs
\item A type of event
\item A descriptor of the value of the event, contains the optionnal fields.
\end{itemize}
Here, the only methods are accessors.
\subsection{The class Link}
It represents a communication between 2 containers in the trace. The attributes are~:
\begin{itemize}
\item Dates of beginning and end
\item A type of link
\item The containers source and destination of the communication
\item A descriptor with the value of the link(contains the optionnal fields).
Methods are accessors.
\end{itemize}
\section{The lists}
The lists are based on the std::list template. They are built in the logical order, each time an element is sent by the parser, it is added in last position in the right list (after making sure the data are rights).
The states are not seen as having a duration but punctual, as brief moments that represent either the beginning or the end of the action. So, to remain logical, a binary tree is not made with states, but with elements from the \textit{StateChange} class, because a state is not punctual whereas a change is, and represents the same information.
The lists may be :
\begin{itemize}
\item List of links, that are contained in the container that is related to the container where the communication starts and where it ends.
\item List of containers
\item List of States/Events, but they are transformed in binary trees after their construction
\end{itemize}
\section{The trees}
The trees do not concern the list of communications. The tree is binary and balanced.
Assuming there is a list, a class is used to build the tree reading only one time each element of the list.
The algorithm of construction is based on binary incrementation. To sum up the main idea, 1 element in the list on 2 is a leaf, as the lowest bit in binary, 1 element on 4 is a father of leaves, as the second lowest bit in binary, etc ...
Assuming we know the lenght of the list, we can calculate the height of the tree (because it is balanced) and then the number of leaves in the lowest level. While we have not reached this number of leaves, we build a binary tree linking the nodes depending on their position in the list (in binary). After this limit, a shift is necessary but the algorithm remain the same.
And so we have a binary tree, linked with an infix order kept : each node happen after all the nodes down in its left side, before all the nodes down in its right side, and these latter happen before the father date.
Then, there is a class that links the data structure and the interface, to be able to get all the events within an interval without being forced to visit each previous node.
%To understand the construction of the binary tree, here it's the diagram of class associated :
\section{Algorithms on the trees :}
\subsection{Browse tree}
\paragraph{The main idea} is a recursif browse of the tree. Going down we select the node that are in the interval, and going up we make sure the node is displayable, and prepare some data for the father to know if it can be displayed.
\paragraph{Algorithm :}
\begin{verbatim}
function browse_recursif ( root, interval, zoom)
if the node is in the interval
If the interval is wide enought to display the node
browse_recursif ( left child )
browse_recursif ( right child )
If there is a problem on the left side of the left child
Copy the problematic data in the node
end if
If there is a problem on the right side of the left side and
the left side of the right child
Making sure we can display the node, or be added to an
interval of conflict that is then displayed
end if
If there is a problem on the right of the right child
Copy the problematic data in the node
end if
If the node has not been displayed yet
Display the node
end if
else // Not wide enought to display
Current interval set as problematic in both problematic area
end if
Else if node is after the interval
browse_recursif ( left child )
Copy the data of conflict on the left in the left child
Else // Node before the interval
browse_recursif ( right child )
Copy the data of conflict on the right in the right child
end if
end function
\end{verbatim}
\subsection{Getting informations on a clicked element}
\paragraph{Principe :}
First we browse for the links (because if we start by something else : state, counter or event, we would not be able to find the links because they are over the others elements and thin enought not to hide them). Because the use of a distance, sometimes to get the right information, it is important to zoom enought.
\paragraph{Algorithm :}
\begin{verbatim}
function get_information( positionX, positionY)
calculate the lowest container in the tree of container where
the clic corresponds
for each container father of the container clicked
look for a communication close enought
if one is found
return this communication
end if
end for each
Search in the list of events of the lowest container
if one corresponds
return it
end if
end search
Search in the list of states of the lowest container
if one corresponds
return it
end if
end search
return no information found
end function
\end{verbatim}
SRC = technical_manual.tex \
convention.tex \
DataStructure.tex \
introduction.tex \
interface.tex \
render.tex \
render_svg.tex \
ParserOTF.tex \
ParserViTE.tex \
ParserPaje.tex \
plugin.tex
DOC = technical_manual
.PHONY = clean cleanout cleanall
default : $(DOC).pdf
$(DOC).pdf : $(DOC).dvi
dvipdf $(DOC).dvi
$(DOC).dvi : $(SRC)
latex $(DOC).tex
latex $(DOC).tex
latex $(DOC).tex
clean :
rm -f *~ *.aux *.log *.toc *.out
cleanout :
rm -f $(DOC).dvi $(DOC).pdf
cleanall : clean cleanout
%%
%% This file is part of the ViTE project.
%%
%% This software is governed by the CeCILL-A license under French law
%% and abiding by the rules of distribution of free software. You can
%% use, modify and/or redistribute the software under the terms of the
%% CeCILL-A license as circulated by CEA, CNRS and INRIA at the following
%% URL: "http://www.cecill.info".
%%
%% As a counterpart to the access to the source code and rights to copy,
%% modify and redistribute granted by the license, users are provided
%% only with a limited warranty and the software's author, the holder of
%% the economic rights, and the successive licensors have only limited
%% liability.
%%
%% In this respect, the user's attention is drawn to the risks associated
%% with loading, using, modifying and/or developing or reproducing the
%% software by the user in light of its specific status of free software,
%% that may mean that it is complicated to manipulate, and that also
%% therefore means that it is reserved for developers and experienced
%% professionals having in-depth computer knowledge. Users are therefore
%% encouraged to load and test the software's suitability as regards
%% their requirements in conditions enabling the security of their
%% systems and/or data to be ensured and, more generally, to use and
%% operate it in the same conditions as regards security.
%%
%% The fact that you are presently reading this means that you have had
%% knowledge of the CeCILL-A license and that you accept its terms.
%%
%%
%% ViTE developers are:
%%
%% - COULOMB Kevin
%% - FAVERGE Mathieu
%% - JAZEIX Johnny
%% - LAGRASSE Olivier
%% - MARCOUEILLE Jule
%% - NOISETTE Pascal
%% - REDONDY Arthur
%% - VUCHENER Clément
%%
\subsection{Introduction}
The OTF format is an open format. Moreover, the OTF library provides tools to convert Vampir'\url{http://www.vampir-ng.de/} or Tau(\url{http://www.cs.uoregon.edu/research/tau/home.php}) traces which are some of the most common used trace format.
An API is also provided in order to read the files.
More details can be found at \\\url{http://tu-dresden.de/die_tu_dresden/zentrale_einrichtungen/zih/forschung/software_werkzeuge_zur_unterstuetzung_von_programmierung_und_optimierung/otf} (in english or deutsch).
\subsection{Implementation}
The OTF parser uses two parsers like the Paj\'e one.
We decided to separate the definitions from events for a better scalabity.
Moreover, we use the provided API to parse the files because it is a portable interface.
\subsection{Supported functions}
Because they are optional and do not have a direct correspondance with the Paj\'e format, we do not handle the following functions~:
\begin{itemize}
\item \textit{Definition, event, snapshot and summary Comments}.
\item \textit{DefCreator}.
\item \textit{Collective operation}.
\item \textit{Snapshots}.
\item \textit{Summaries}.
\end{itemize}
Also we do not take in account the streams in optional fields.
In the future we could consider that snapshots are events.
\subsubsection{Correspondances and differences between this format and the Paj\'e one}
The genericity of the Paj\'e format is very useful because we do not need to create other classes for the trace.
So, a process will be designed as a container in Paj\'e format.
A process group will be considered as the container type in order to keep the Paj\'e format. If a process does not belong to a process group, we assign it to the empty process group (the 0). However, a process can belong to more than one process group. We do not handle this case and only consider that the first one found is the process group.
A function will be an event and its function group will be the EventType.
A counter will be a variable and a counter group the VariableType.
A message will be a link. Its value will be~: "sender\_name to receiver\_name" because there are no message value in the OTF format.
\subsection{Definition Parser}
This parser stores all the OTF objects (process, functions...).
In order to do it, we use the provided API which uses handlers.
Variables in the ParserDefinition are static because this is the only way to handle handlers.
While parsing, we only store each component. At the end of it, we create all the ContainerType. We can not create the EventType or VariableType because we do not know in which kind of process the event or the variable is used.
\subsection{Event Parser}
Due to the optionnality of the process creation, we have to check before each event or counter catched that the container exist.
Now that we know which kind of process uses the event or counter, we can create the eventType or variableType if they do not exist.
Because of the fact that if an event does not exist, it is automatically created by the trace, we can not add the optional fields like source file or color. In order to pass through it, we added a boolean attribute to the function structure which says if the function has already been defined.
For the counter, we are not sure that the sender has an ancestor. If it is not the case, we consider that the ancestor is also the sender.
The handling of the remaining time is in the EventParser too. Because we consider (good consideration?) that reading the definitions is done faster than reading the events, we only take the time for events to compute the remaining time.
%%
%% This file is part of the ViTE project.
%%
%% This software is governed by the CeCILL-A license under French law
%% and abiding by the rules of distribution of free software. You can
%% use, modify and/or redistribute the software under the terms of the
%% CeCILL-A license as circulated by CEA, CNRS and INRIA at the following
%% URL: "http://www.cecill.info".
%%
%% As a counterpart to the access to the source code and rights to copy,
%% modify and redistribute granted by the license, users are provided
%% only with a limited warranty and the software's author, the holder of
%% the economic rights, and the successive licensors have only limited
%% liability.
%%
%% In this respect, the user's attention is drawn to the risks associated
%% with loading, using, modifying and/or developing or reproducing the
%% software by the user in light of its specific status of free software,
%% that may mean that it is complicated to manipulate, and that also
%% therefore means that it is reserved for developers and experienced
%% professionals having in-depth computer knowledge. Users are therefore
%% encouraged to load and test the software's suitability as regards
%% their requirements in conditions enabling the security of their
%% systems and/or data to be ensured and, more generally, to use and
%% operate it in the same conditions as regards security.
%%
%% The fact that you are presently reading this means that you have had
%% knowledge of the CeCILL-A license and that you accept its terms.
%%
%%
%% ViTE developers are:
%%
%% - COULOMB Kevin
%% - FAVERGE Mathieu
%% - JAZEIX Johnny
%% - LAGRASSE Olivier
%% - MARCOUEILLE Jule
%% - NOISETTE Pascal
%% - REDONDY Arthur
%% - VUCHENER Clément
%%
\subsection{Representation of the file trace line by line}
\subsubsection{Introduction}
A line is a syntaxical unit in a file following the Paj\'e trace format. Tokens are supplied by a File (a class which encapsulates a std::ifstream). In Paj\'e file trace format, a line is the beginning of a definition, the end of a definition, a definition or an event.
For example :
\begin{itemize}
\item '\%EventDef PajeDefineContainerType 1'
\item '\% Name string'
\item '111 1.03305 MT 31:11392 315706-13 112'
\end{itemize}
\subsubsection{Implementation}
Line object stands for a line. The method fill\_line() fill the object. It enables the item() method to access line's tokens : the item() method is an indexed access to line's token.
\paragraph{Construction of a line}
A line is built by fill\_line() that consists in append character while they do a token and as long as the current token read is different from \verb?'\n'?.
\paragraph{Storage}
A private std::vector$<$std::string$>$ stores line's tokens. Actually there is no use of an indexed access. The item() method could simply supply the next token of a line.
\subsection{Representation of the definitions described in the trace file}
\subsubsection{Introduction}
A Definition is the definition of events found while parsing the file. It is always composed by a field "name", with other caracteristics of the event such as type or values.
The set of definition is stored in a table. The definition and its identifiers are paired. For example, with this file trace~:
\begin{verbatim}
%EventDef PajeDestroyContainer 8
% Time date
% Name string
% Type string
%EndEventDef
%EventDef PajeDefineStateType 3
% Alias string
% ContainerType string
% Name string
%EndEventDef
\end{verbatim}
The table of definitions will be \{(8, d1),(3,d2)\}, the d1 definition \{"PajeDestroyContainer",\{f1,f2,f3\}\} and the f1 field \{"Alias", "string"\}.
\subsubsection{Implementation}
Extensible definition fields are stored in a std::vector. Couples of definition and id are available in a std::map$<$int,Definition$>$ hash table.
\subsection{Acknowledge of definitions' lines}
\subsubsection{Introduction}
ParserDefinitionDecoder performs a received Line which starts with percent.
\subsubsection{Definition}
A field Line is a Line with the two first tokens that are the name of a variable and a name.
A EventDef Line is a Line with the first token that is EventDef.
A EndEventDef Line is a Line with the first token that is EndEventDef.
A definition is a set of lines that begins by an EndEventDef Line, have an indefinite number of fields Line and ends with an EndEventDef Line.
\subsubsection{Automaton of definition}
Implementation faithfully uses the automaton described.
Automaton reaches "in a definition" when an EventDef Line is read and instanciated a new definition which enables :
\begin{itemize}
\item reading a field Line : which is translated and read fields are added to the current definition.
\item reading an EndEventDef Line : which consists in storing the current definition in the table and fall in "out of a definition".
\end{itemize}
\subsubsection{Specification}
A ParserDefinitionDecoder can be instanciated by an empty constructor.
The store\_definition() method requires a filled Line Object which starts with percent tokens and returns when this line is read.
get\_definition() enables access to the table of definition.
\subsection{Event parser}
\subsubsection{Introduction}
The parser provides a Line which represents an event and the definition of this event. The purpose of the event parser is to give the values of this event to the data structure in order to store it.
\subsubsection{Implementation}
The event parser contains only one method which fills the data structure step by step with the lines (Line) provided. To do that, there are as many local variables as known field names in Paj\'e's events. The variables which fit the event defined by the definition (Definition) are filled ordered by the fields of the definition by converting the strings read in the line to the defined type. The values which do not fit some known field names are stored in a vector. Then, the event parser uses the data structure methods to fill it. The variables given as arguments for these methods depend on the Paj\'e event name.
\subsection{Handling of a trace}
\subsubsection{Introduction}
ParserPaje reads a file trace and sends messages to Trace accordingly.
\subsubsection{Implementation}
ParserPaje opens a file (instanciate a Line), instanciates a ParserEventDecoder and a ParserDefinitionDecoder.
It reads lines until the end of the file.
Each line is parsed by ParserEventDecoder or ParserDefinitionDecoder whether or not the line starts with \% token.
\begin{figure}[ht!]
\includegraphics[scale=0.5]{images/automateParserSyntaxique}
\caption{\label{ParserAutomaton} The Paj\'e parser automaton}
\end{figure}
\subsubsection{Specification}
A ParserPaje can be instanciated by an empty constructor.
The parse() method requires a filename to be opened and an instance of a trace object to proceed.
\subsubsection{Tests}
A test reads a trace file, uses the ParserDefinitionDecoder and ParserEventDecoder and prints the calls to the trace object. Each event produces a call as expected.
%%
%% This file is part of the ViTE project.
%%
%% This software is governed by the CeCILL-A license under French law
%% and abiding by the rules of distribution of free software. You can
%% use, modify and/or redistribute the software under the terms of the
%% CeCILL-A license as circulated by CEA, CNRS and INRIA at the following
%% URL: "http://www.cecill.info".
%%
%% As a counterpart to the access to the source code and rights to copy,
%% modify and redistribute granted by the license, users are provided
%% only with a limited warranty and the software's author, the holder of
%% the economic rights, and the successive licensors have only limited
%% liability.
%%
%% In this respect, the user's attention is drawn to the risks associated
%% with loading, using, modifying and/or developing or reproducing the
%% software by the user in light of its specific status of free software,
%% that may mean that it is complicated to manipulate, and that also
%% therefore means that it is reserved for developers and experienced
%% professionals having in-depth computer knowledge. Users are therefore
%% encouraged to load and test the software's suitability as regards
%% their requirements in conditions enabling the security of their
%% systems and/or data to be ensured and, more generally, to use and
%% operate it in the same conditions as regards security.
%%
%% The fact that you are presently reading this means that you have had
%% knowledge of the CeCILL-A license and that you accept its terms.
%%
%%
%% ViTE developers are:
%%
%% - COULOMB Kevin
%% - FAVERGE Mathieu
%% - JAZEIX Johnny
%% - LAGRASSE Olivier
%% - MARCOUEILLE Jule
%% - NOISETTE Pascal
%% - REDONDY Arthur
%% - VUCHENER Clément
%%
\subsection{Utility of this parser}
The aim of this parser is to split the Paj\'e traces in various files (one file per process). The main point is to enhance trace generationusing the Paj\'e format and avoid having various processes writting at the same time in the same file. The constraint is to have a synchron clock.
We have a definition file containing all the definitions and the creation of all the containers. An optional field containing the file name where all the events of this container is provided in order to parse it.
The other files only contain actions (events, links or state changes).
\subsection{How it works}
The first file given is parsed with a \textbf{ParserPaje} and all the definitions are stored in the parserViTE. Then we get from the trace all the filenames where there are events.
A parserEventPaje reads all the files and store in parallel all the end of links because it is possible to read an end before a start (in this case the link will not be printed).
At the end of all the parsing, a new parserEventPaje stores all the end links.
%%
%% This file is part of the ViTE project.
%%
%% This software is governed by the CeCILL-A license under French law
%% and abiding by the rules of distribution of free software. You can
%% use, modify and/or redistribute the software under the terms of the
%% CeCILL-A license as circulated by CEA, CNRS and INRIA at the following
%% URL: "http://www.cecill.info".
%%
%% As a counterpart to the access to the source code and rights to copy,
%% modify and redistribute granted by the license, users are provided
%% only with a limited warranty and the software's author, the holder of
%% the economic rights, and the successive licensors have only limited
%% liability.
%%
%% In this respect, the user's attention is drawn to the risks associated
%% with loading, using, modifying and/or developing or reproducing the
%% software by the user in light of its specific status of free software,
%% that may mean that it is complicated to manipulate, and that also
%% therefore means that it is reserved for developers and experienced