tutorial: Added paragraph to MTAPI C++ description regarding the performance…

tutorial: Added paragraph to MTAPI C++ description regarding the performance impact of automatic initialization, references added in the algorithms and dataflow tutorials, added note to readme

README.md

@@ -172,6 +172,7 @@ EMB² can be built with and without C++ exception handling, which has to be
 specified on build file generation. When exceptions are turned off, an error
 specified on build file generation. When exceptions are turned off, an error
 message is emitted and the program aborts in case of an exception within EMB².
 message is emitted and the program aborts in case of an exception within EMB².
 To disable exceptions, add the option -DUSE_EXCEPTIONS=OFF.
 To disable exceptions, add the option -DUSE_EXCEPTIONS=OFF.
+
 Similarly, automatic initialization of the task scheduler by the MTAPI C++
 Similarly, automatic initialization of the task scheduler by the MTAPI C++
 interface can be disabled with -DUSE_AUTOMATIC_INITIALIZATION=OFF. This way,
 interface can be disabled with -DUSE_AUTOMATIC_INITIALIZATION=OFF. This way,
 unexpected delays after startup can be avoided, e.g. for timing measurements.
 unexpected delays after startup can be avoided, e.g. for timing measurements.
@@ -357,6 +358,16 @@ Please use these defines for new platform specific code. If additional defines
 are needed, they can be defined in the config.h or cmake_config.h.in files.
 are needed, they can be defined in the config.h or cmake_config.h.in files.
 
 
 
 
+Important Notes
+---------------
+
+- The MTAPI C++ interface supports automatic initialization, which allows for
+  easy usage of the MTAPI C++, Algorithms and Dataflow components. For
+  performance measurements, explicit initialization is strongly recommended
+  since the measurements will otherwise include the initialization time of
+  MTAPI.
+
+
 Links
 Links
 -----
 -----
 
 

doc/tutorial/content/algorithms.tex

 \chapter{Algorithms}
 \chapter{Algorithms}
 \label{cha:algorithms}
 \label{cha:algorithms}
 
 
-The \emph{Algorithms} building block of \embb provides high-level constructs for typical parallelization tasks. They are aligned to the functions provided by the C++ Standard Library, but contain additional functionality typical for embedded systems such as task priorities. Although the algorithms can be used in a black-box way, it is good to have a basic understanding of their implementation: The algorithms split computations to be performed in parallel into tasks which are executed by the MTAPI task scheduler (cf. Chapter~\ref{cha:mtapi}). For that purpose, the tasks are stored in queues and mapped to a fixed number of worker threads at runtime. Since MTAPI allocates the necessary data structures during initialization, the maximum number of tasks in flight is fixed. In case one of the algorithms exceeds this limit, an exception is thrown. 
+The \emph{Algorithms} building block of \embb provides high-level constructs for typical parallelization tasks. They are aligned to the functions provided by the C++ Standard Library, but contain additional functionality typical for embedded systems such as task priorities. Although the algorithms can be used in a black-box way, it is good to have a basic understanding of their implementation: The algorithms split computations to be performed in parallel into tasks which are executed by the MTAPI task scheduler (cf. Chapter~\ref{cha:mtapi}). For that purpose, the tasks are stored in queues and mapped to a fixed number of worker threads at runtime. Since MTAPI allocates the necessary data structures during initialization, the maximum number of tasks in flight is fixed. In case one of the algorithms exceeds this limit, an exception is thrown.
+
+\emph{\textbf{Note:} The \emph{Algorithms} building block is implemented using the MTAPI C++ interface. By calling \lstinline|embb::mtapi::Node::Initialize| task and other limits can be customized. Explicit initialization also eliminates unexpected delays when measuring performance. See Section~\ref{sec:mtapi_cpp_interface} for details.}
 
 
 In the following, we look at parallel function invocation (Section~\ref{sec:algorithms_invoke}), sorting (Section~\ref{sec:algorithms_sorting}), counting (Section~\ref{sec:algorithms_counting}), foreach loops (Section~\ref{sec:algorithms_foreach}), reductions (Section~\ref{sec:algorithms_reductions}), and prefix computations (Section~\ref{sec:algorithms_prefix}).
 In the following, we look at parallel function invocation (Section~\ref{sec:algorithms_invoke}), sorting (Section~\ref{sec:algorithms_sorting}), counting (Section~\ref{sec:algorithms_counting}), foreach loops (Section~\ref{sec:algorithms_foreach}), reductions (Section~\ref{sec:algorithms_reductions}), and prefix computations (Section~\ref{sec:algorithms_prefix}).
 
 

doc/tutorial/content/dataflow.tex

@@ -18,6 +18,8 @@ With the \emph{Dataflow} building block, \embb provides generic skeletons for th
 % \item dynamic control of data streams (conditional execution)
 % \item dynamic control of data streams (conditional execution)
 %\end{itemize}
 %\end{itemize}
 
 
+\emph{\textbf{Note:} The \emph{Dataflow} building block is implemented using the MTAPI C++ interface. Since MTAPI does not allocate memory after initialization, the number of tasks and other resources are limited. By calling \lstinline|embb::mtapi::Node::Initialize| these limits can be customized. Explicit initialization also eliminates unexpected delays when measuring performance. See Section~\ref{sec:mtapi_cpp_interface} for details.}
+
 \section{Linear Pipelines}
 \section{Linear Pipelines}
 
 
 Before we go into detail, we demonstrate the basic concepts of this building block by means of a simple application which finds and replaces strings in a file. Let us start with the sequential implementation. The program shown in Listing~\ref{lst:replace_seq} reads a file line by line and replaces each occurrence of a given string with a new string. The main part consists of the \lstinline|while| loop which performs three steps:
 Before we go into detail, we demonstrate the basic concepts of this building block by means of a simple application which finds and replaces strings in a file. Let us start with the sequential implementation. The program shown in Listing~\ref{lst:replace_seq} reads a file line by line and replaces each occurrence of a given string with a new string. The main part consists of the \lstinline|while| loop which performs three steps:
@@ -138,7 +140,7 @@ is used to construct the sink:
 %
 %
 %In order to avoid that the received string is overwritten accidentally, the parameter \lstinline|str| corresponding to the input port of \lstinline|write| must be constant.\\
 %In order to avoid that the received string is overwritten accidentally, the parameter \lstinline|str| corresponding to the input port of \lstinline|write| must be constant.\\
 
 
-\emph{Note: If you parallelize your own application using \embb and your compiler emits a lengthy error message containing lots of templates, it is very likely that for at least one process, the ports and their directions do not match the signature of the given function.}
+\emph{\textbf{Note:} If you parallelize your own application using \embb and your compiler emits a lengthy error message containing lots of templates, it is very likely that for at least one process, the ports and their directions do not match the signature of the given function.}
 
 
 The network needs to know about the processes declared above, so we add them to our network:
 The network needs to know about the processes declared above, so we add them to our network:
 %
 %

doc/tutorial/content/mtapi.tex

@@ -160,6 +160,8 @@ First, the node instance needs to be obtained. If the node is not initialized ye
 %
 %
 \\\inputlisting{../examples/mtapi/mtapi_cpp_get_node-snippet.h}
 \\\inputlisting{../examples/mtapi/mtapi_cpp_get_node-snippet.h}
 %
 %
+\emph{\textbf{Note:} Automatic initialization allows for easy usage of the \emph{Algorithms} and \emph{Dataflow} building blocks. For performance measurements however, explicit initialization by calling \lstinline|embb::mtapi::Node::Initialize| is imperative since the measurements will otherwise include the initialization time of MTAPI.}
+
 Checking the arguments and the result buffer is not necessary, since everything is safely typed. However, the terminating condition of the recursion still needs to be checked:
 Checking the arguments and the result buffer is not necessary, since everything is safely typed. However, the terminating condition of the recursion still needs to be checked:
 %
 %
 \\\inputlisting{../examples/mtapi/mtapi_terminating_condition-snippet.h}
 \\\inputlisting{../examples/mtapi/mtapi_terminating_condition-snippet.h}
@@ -190,3 +192,5 @@ The root task can be started using \lstinline|embb::mtapi::Node::Spawn()| direct
 \\\inputlisting{../examples/mtapi/mtapi_cpp_start_task-snippet.h}
 \\\inputlisting{../examples/mtapi/mtapi_cpp_start_task-snippet.h}
 %
 %
 Again, the started task has to be waited for (using \lstinline|embb::mtapi::Task::Wait()|) before the result can be returned. The runtime is shut down automatically in an \lstinline|atexit()| handler.
 Again, the started task has to be waited for (using \lstinline|embb::mtapi::Task::Wait()|) before the result can be returned. The runtime is shut down automatically in an \lstinline|atexit()| handler.
+
+\emph{\textbf{Note:} If the node was initialized explicitly by calling \lstinline|embb::mtapi::Node::Initialize|, the runtime must also be shut down explicitly by calling \lstinline|embb::mtapi::Node::Finalize|.}