From b5e32877200401df9a55029e3ed605d5ed900d8b Mon Sep 17 00:00:00 2001 From: Marcus Winter Date: Wed, 25 Feb 2015 13:49:50 +0100 Subject: [PATCH] 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 | 11 +++++++++++ doc/tutorial/content/algorithms.tex | 4 +++- doc/tutorial/content/dataflow.tex | 4 +++- doc/tutorial/content/mtapi.tex | 4 ++++ 4 files changed, 21 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c30af40..ae23f11 100644 --- a/README.md +++ b/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 message is emitted and the program aborts in case of an exception within EMB². To disable exceptions, add the option -DUSE_EXCEPTIONS=OFF. + Similarly, automatic initialization of the task scheduler by the MTAPI C++ interface can be disabled with -DUSE_AUTOMATIC_INITIALIZATION=OFF. This way, 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. +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 ----- diff --git a/doc/tutorial/content/algorithms.tex b/doc/tutorial/content/algorithms.tex index 9a52973..14bff9f 100644 --- a/doc/tutorial/content/algorithms.tex +++ b/doc/tutorial/content/algorithms.tex @@ -1,7 +1,9 @@ \chapter{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}). diff --git a/doc/tutorial/content/dataflow.tex b/doc/tutorial/content/dataflow.tex index 3274bf8..7d09e6b 100644 --- a/doc/tutorial/content/dataflow.tex +++ b/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) %\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} 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.\\ -\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: % diff --git a/doc/tutorial/content/mtapi.tex b/doc/tutorial/content/mtapi.tex index 06ea39e..e0cb5a3 100644 --- a/doc/tutorial/content/mtapi.tex +++ b/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} % +\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: % \\\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} % 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|.} -- libgit2 0.26.0