From bc6e512fe9fe3ca9d2f5becf5cb9ef29228a6776 Mon Sep 17 00:00:00 2001 From: Marcus Winter Date: Tue, 24 Mar 2015 16:33:53 +0100 Subject: [PATCH] examples, tutorial: changed to use tasks_cpp --- doc/examples/CMakeLists.txt | 6 +++--- doc/examples/mtapi/mtapi_cpp-fragmented.cc | 64 ---------------------------------------------------------------- doc/examples/mtapi/mtapi_cpp_action_signature-snippet.h | 5 ----- doc/examples/mtapi/mtapi_cpp_calc_direct-snippet.h | 6 ------ doc/examples/mtapi/mtapi_cpp_calc_task-snippet.h | 10 ---------- doc/examples/mtapi/mtapi_cpp_get_node-snippet.h | 1 - doc/examples/mtapi/mtapi_cpp_start_task-snippet.h | 9 --------- doc/examples/mtapi/mtapi_cpp_wait_task-snippet.h | 2 -- doc/examples/tasks/tasks_cpp-fragmented.cc | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/examples/tasks/tasks_cpp_action_signature-snippet.h | 5 +++++ doc/examples/tasks/tasks_cpp_calc_direct-snippet.h | 6 ++++++ doc/examples/tasks/tasks_cpp_calc_task-snippet.h | 10 ++++++++++ doc/examples/tasks/tasks_cpp_get_node-snippet.h | 1 + doc/examples/tasks/tasks_cpp_start_task-snippet.h | 9 +++++++++ doc/examples/tasks/tasks_cpp_wait_task-snippet.h | 2 ++ doc/tutorial/content/mtapi.tex | 23 ++++++++++------------- doc/tutorial/content/tasks.tex | 45 +++++++++++++++++++++++++++++++++++++++++++++ doc/tutorial/tutorial.tex | 1 + 18 files changed, 156 insertions(+), 113 deletions(-) delete mode 100644 doc/examples/mtapi/mtapi_cpp-fragmented.cc delete mode 100644 doc/examples/mtapi/mtapi_cpp_action_signature-snippet.h delete mode 100644 doc/examples/mtapi/mtapi_cpp_calc_direct-snippet.h delete mode 100644 doc/examples/mtapi/mtapi_cpp_calc_task-snippet.h delete mode 100644 doc/examples/mtapi/mtapi_cpp_get_node-snippet.h delete mode 100644 doc/examples/mtapi/mtapi_cpp_start_task-snippet.h delete mode 100644 doc/examples/mtapi/mtapi_cpp_wait_task-snippet.h create mode 100644 doc/examples/tasks/tasks_cpp-fragmented.cc create mode 100644 doc/examples/tasks/tasks_cpp_action_signature-snippet.h create mode 100644 doc/examples/tasks/tasks_cpp_calc_direct-snippet.h create mode 100644 doc/examples/tasks/tasks_cpp_calc_task-snippet.h create mode 100644 doc/examples/tasks/tasks_cpp_get_node-snippet.h create mode 100644 doc/examples/tasks/tasks_cpp_start_task-snippet.h create mode 100644 doc/examples/tasks/tasks_cpp_wait_task-snippet.h create mode 100644 doc/tutorial/content/tasks.tex diff --git a/doc/examples/CMakeLists.txt b/doc/examples/CMakeLists.txt index 9393c95..f34f99d 100644 --- a/doc/examples/CMakeLists.txt +++ b/doc/examples/CMakeLists.txt @@ -10,8 +10,8 @@ include_directories( ${CMAKE_CURRENT_SOURCE_DIR}/../../base_cpp/include ${CMAKE_CURRENT_BINARY_DIR}/../../base_cpp/include ${CMAKE_CURRENT_SOURCE_DIR}/../../mtapi_c/include - ${CMAKE_CURRENT_SOURCE_DIR}/../../mtapi_cpp/include - ${CMAKE_CURRENT_BINARY_DIR}/../../mtapi_cpp/include + ${CMAKE_CURRENT_SOURCE_DIR}/../../tasks_cpp/include + ${CMAKE_CURRENT_BINARY_DIR}/../../tasks_cpp/include ${CMAKE_CURRENT_SOURCE_DIR}/../../containers_cpp/include ${CMAKE_CURRENT_SOURCE_DIR}/../../algorithms_cpp/include ${CMAKE_CURRENT_SOURCE_DIR}/../../dataflow_cpp/include @@ -22,6 +22,6 @@ if(CMAKE_COMPILER_IS_GNUCXX) endif() add_executable(examples ${EXAMPLES_SOURCES}) -target_link_libraries(examples embb_dataflow_cpp embb_algorithms_cpp embb_mtapi_cpp +target_link_libraries(examples embb_dataflow_cpp embb_algorithms_cpp embb_tasks_cpp embb_mtapi_c embb_base_cpp embb_base_c embb_containers_cpp ${compiler_libs}) CopyBin(BIN examples DEST ${local_install_dir}) diff --git a/doc/examples/mtapi/mtapi_cpp-fragmented.cc b/doc/examples/mtapi/mtapi_cpp-fragmented.cc deleted file mode 100644 index 700d758..0000000 --- a/doc/examples/mtapi/mtapi_cpp-fragmented.cc +++ /dev/null @@ -1,64 +0,0 @@ -/* - * Copyright (c) 2014-2015, Siemens AG. All rights reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions are met: - * - * 1. Redistributions of source code must retain the above copyright notice, - * this list of conditions and the following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above copyright notice, - * this list of conditions and the following disclaimer in the documentation - * and/or other materials provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE - * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - * POSSIBILITY OF SUCH DAMAGE. - */ - -#include - -#include - -#include "mtapi/mtapi_check_status-snippet.h" - -static -#include "mtapi/mtapi_cpp_action_signature-snippet.h" - /* get the node instance */ -#include "mtapi/mtapi_cpp_get_node-snippet.h" - /* calculate */ -#include "mtapi/mtapi_terminating_condition-snippet.h" - /* first recursive call spawned as task (x = fib(n - 1);) */ -#include "mtapi/mtapi_cpp_calc_task-snippet.h" - /* second recursive call can be called directly (y = fib(n - 2);) */ -#include "mtapi/mtapi_cpp_calc_direct-snippet.h" - /* wait for completion */ -#include "mtapi/mtapi_cpp_wait_task-snippet.h" - /* add the two preceeding numbers */ -#include "mtapi/mtapi_write_back-snippet.h" - -static -int fibonacci(int n) { - /* get the node instance, the node is initialized automatically */ - embb::mtapi::Node& node = embb::mtapi::Node::GetInstance(); - /* start calculation */ -#include "mtapi/mtapi_cpp_start_task-snippet.h" - /* wait for task completion */ - mtapi_status_t status = task.Wait(MTAPI_INFINITE); - MTAPI_CHECK_STATUS(status); - - return result; -} - -void RunMTAPI_CPP() { - int result = fibonacci(6); - std::cout << "result: " << result << std::endl; -} diff --git a/doc/examples/mtapi/mtapi_cpp_action_signature-snippet.h b/doc/examples/mtapi/mtapi_cpp_action_signature-snippet.h deleted file mode 100644 index f15cd7f..0000000 --- a/doc/examples/mtapi/mtapi_cpp_action_signature-snippet.h +++ /dev/null @@ -1,5 +0,0 @@ -void fibonacciActionFunction( - int n, - int* result, - embb::mtapi::TaskContext & task_context - ) { diff --git a/doc/examples/mtapi/mtapi_cpp_calc_direct-snippet.h b/doc/examples/mtapi/mtapi_cpp_calc_direct-snippet.h deleted file mode 100644 index eb08e75..0000000 --- a/doc/examples/mtapi/mtapi_cpp_calc_direct-snippet.h +++ /dev/null @@ -1,6 +0,0 @@ - int b = n - 2; - int y; - fibonacciActionFunction( - b, - &y, - task_context); diff --git a/doc/examples/mtapi/mtapi_cpp_calc_task-snippet.h b/doc/examples/mtapi/mtapi_cpp_calc_task-snippet.h deleted file mode 100644 index 4362f38..0000000 --- a/doc/examples/mtapi/mtapi_cpp_calc_task-snippet.h +++ /dev/null @@ -1,10 +0,0 @@ - int a = n - 1; - int x; - embb::mtapi::Task task = node.Spawn( - embb::base::Bind( - embb::base::MakeFunction(fibonacciActionFunction), - a, /* argument */ - &x, /* result */ - embb::base::Placeholder::_1 - ) - ); diff --git a/doc/examples/mtapi/mtapi_cpp_get_node-snippet.h b/doc/examples/mtapi/mtapi_cpp_get_node-snippet.h deleted file mode 100644 index b91d187..0000000 --- a/doc/examples/mtapi/mtapi_cpp_get_node-snippet.h +++ /dev/null @@ -1 +0,0 @@ - embb::mtapi::Node& node = embb::mtapi::Node::GetInstance(); diff --git a/doc/examples/mtapi/mtapi_cpp_start_task-snippet.h b/doc/examples/mtapi/mtapi_cpp_start_task-snippet.h deleted file mode 100644 index 7dddbb3..0000000 --- a/doc/examples/mtapi/mtapi_cpp_start_task-snippet.h +++ /dev/null @@ -1,9 +0,0 @@ - int result; - embb::mtapi::Task task = node.Spawn( - embb::base::Bind( - embb::base::MakeFunction(fibonacciActionFunction), - n, - &result, - embb::base::Placeholder::_1 - ) - ); diff --git a/doc/examples/mtapi/mtapi_cpp_wait_task-snippet.h b/doc/examples/mtapi/mtapi_cpp_wait_task-snippet.h deleted file mode 100644 index 21637fd..0000000 --- a/doc/examples/mtapi/mtapi_cpp_wait_task-snippet.h +++ /dev/null @@ -1,2 +0,0 @@ - mtapi_status_t status = task.Wait(MTAPI_INFINITE); - MTAPI_CHECK_STATUS(status); diff --git a/doc/examples/tasks/tasks_cpp-fragmented.cc b/doc/examples/tasks/tasks_cpp-fragmented.cc new file mode 100644 index 0000000..95b5143 --- /dev/null +++ b/doc/examples/tasks/tasks_cpp-fragmented.cc @@ -0,0 +1,64 @@ +/* + * Copyright (c) 2014-2015, Siemens AG. All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +#include + +#include + +#include "mtapi/mtapi_check_status-snippet.h" + +static +#include "tasks/tasks_cpp_action_signature-snippet.h" + /* get the node instance */ +#include "tasks/tasks_cpp_get_node-snippet.h" + /* calculate */ +#include "mtapi/mtapi_terminating_condition-snippet.h" + /* first recursive call spawned as task (x = fib(n - 1);) */ +#include "tasks/tasks_cpp_calc_task-snippet.h" + /* second recursive call can be called directly (y = fib(n - 2);) */ +#include "tasks/tasks_cpp_calc_direct-snippet.h" + /* wait for completion */ +#include "tasks/tasks_cpp_wait_task-snippet.h" + /* add the two preceeding numbers */ +#include "mtapi/mtapi_write_back-snippet.h" + +static +int fibonacci(int n) { + /* get the node instance, the node is initialized automatically */ + embb::tasks::Node& node = embb::tasks::Node::GetInstance(); + /* start calculation */ +#include "tasks/tasks_cpp_start_task-snippet.h" + /* wait for task completion */ + mtapi_status_t status = task.Wait(MTAPI_INFINITE); + MTAPI_CHECK_STATUS(status); + + return result; +} + +void RunMTAPI_CPP() { + int result = fibonacci(6); + std::cout << "result: " << result << std::endl; +} diff --git a/doc/examples/tasks/tasks_cpp_action_signature-snippet.h b/doc/examples/tasks/tasks_cpp_action_signature-snippet.h new file mode 100644 index 0000000..24aa989 --- /dev/null +++ b/doc/examples/tasks/tasks_cpp_action_signature-snippet.h @@ -0,0 +1,5 @@ +void fibonacciActionFunction( + int n, + int* result, + embb::tasks::TaskContext & task_context + ) { diff --git a/doc/examples/tasks/tasks_cpp_calc_direct-snippet.h b/doc/examples/tasks/tasks_cpp_calc_direct-snippet.h new file mode 100644 index 0000000..eb08e75 --- /dev/null +++ b/doc/examples/tasks/tasks_cpp_calc_direct-snippet.h @@ -0,0 +1,6 @@ + int b = n - 2; + int y; + fibonacciActionFunction( + b, + &y, + task_context); diff --git a/doc/examples/tasks/tasks_cpp_calc_task-snippet.h b/doc/examples/tasks/tasks_cpp_calc_task-snippet.h new file mode 100644 index 0000000..cfe5664 --- /dev/null +++ b/doc/examples/tasks/tasks_cpp_calc_task-snippet.h @@ -0,0 +1,10 @@ + int a = n - 1; + int x; + embb::tasks::Task task = node.Spawn( + embb::base::Bind( + embb::base::MakeFunction(fibonacciActionFunction), + a, /* argument */ + &x, /* result */ + embb::base::Placeholder::_1 + ) + ); diff --git a/doc/examples/tasks/tasks_cpp_get_node-snippet.h b/doc/examples/tasks/tasks_cpp_get_node-snippet.h new file mode 100644 index 0000000..f644ec5 --- /dev/null +++ b/doc/examples/tasks/tasks_cpp_get_node-snippet.h @@ -0,0 +1 @@ + embb::tasks::Node& node = embb::tasks::Node::GetInstance(); diff --git a/doc/examples/tasks/tasks_cpp_start_task-snippet.h b/doc/examples/tasks/tasks_cpp_start_task-snippet.h new file mode 100644 index 0000000..507e634 --- /dev/null +++ b/doc/examples/tasks/tasks_cpp_start_task-snippet.h @@ -0,0 +1,9 @@ + int result; + embb::tasks::Task task = node.Spawn( + embb::base::Bind( + embb::base::MakeFunction(fibonacciActionFunction), + n, + &result, + embb::base::Placeholder::_1 + ) + ); diff --git a/doc/examples/tasks/tasks_cpp_wait_task-snippet.h b/doc/examples/tasks/tasks_cpp_wait_task-snippet.h new file mode 100644 index 0000000..21637fd --- /dev/null +++ b/doc/examples/tasks/tasks_cpp_wait_task-snippet.h @@ -0,0 +1,2 @@ + mtapi_status_t status = task.Wait(MTAPI_INFINITE); + MTAPI_CHECK_STATUS(status); diff --git a/doc/tutorial/content/mtapi.tex b/doc/tutorial/content/mtapi.tex index e0cb5a3..f924f52 100644 --- a/doc/tutorial/content/mtapi.tex +++ b/doc/tutorial/content/mtapi.tex @@ -154,13 +154,12 @@ After everything is done, the action is deleted (\lstinline|mtapi_action_delete( \embb provides C++ wrappers for the MTAPI C interface. Using the example from the previous section, the signature of the action function for the C++ interface looks like this: % -\\\inputlisting{../examples/mtapi/mtapi_cpp_action_signature-snippet.h} +%\\\inputlisting{../examples/mtapi/mtapi_cpp_action_signature-snippet.h} % -First, the node instance needs to be obtained. If the node is not initialized yet, this function will do it. +First, the node instance needs to be initialized. % -\\\inputlisting{../examples/mtapi/mtapi_cpp_get_node-snippet.h} +%\\\inputlisting{../examples/mtapi/mtapi_cpp_initialize_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: % @@ -168,15 +167,15 @@ Checking the arguments and the result buffer is not necessary, since everything % After that, the first part of the computation is launched as an MTAPI task using \lstinline|embb::mtapi::Node::Spawn()| (registering an action function with a job is done automatically): % -\\\inputlisting{../examples/mtapi/mtapi_cpp_calc_task-snippet.h} +%\\\inputlisting{../examples/mtapi/mtapi_cpp_calc_task-snippet.h} % The second part can be executed directly: % -\\\inputlisting{../examples/mtapi/mtapi_cpp_calc_direct-snippet.h} +%\\\inputlisting{../examples/mtapi/mtapi_cpp_calc_direct-snippet.h} % Then, completion of the MTAPI task has to be waited for using \lstinline|embb::mtapi::Task::Wait()|: % -\\\inputlisting{../examples/mtapi/mtapi_cpp_wait_task-snippet.h} +%\\\inputlisting{../examples/mtapi/mtapi_cpp_wait_task-snippet.h} % Finally, the two parts can be added and written into the result buffer: % @@ -185,12 +184,10 @@ Finally, the two parts can be added and written into the result buffer: The \lstinline|fibonacci()| function also gets simpler compared to the C version. The MTAPI runtime is initialized automatically, only the node instance has to be fetched: % -\\\inputlisting{../examples/mtapi/mtapi_cpp_get_node-snippet.h} +%\\\inputlisting{../examples/mtapi/mtapi_cpp_get_node-snippet.h} % -The root task can be started using \lstinline|embb::mtapi::Node::Spawn()| directly, registering with a job is done automatically: +The root task can be started using \lstinline|embb::mtapi::Node::Start()| directly, registering with a job is done automatically: % -\\\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. - -\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|.} +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 by calling \lstinline|embb::mtapi::Node::Finalize|. diff --git a/doc/tutorial/content/tasks.tex b/doc/tutorial/content/tasks.tex new file mode 100644 index 0000000..45770bc --- /dev/null +++ b/doc/tutorial/content/tasks.tex @@ -0,0 +1,45 @@ +\chapter{Tasks} +\label{cha:tasks} + +\embb provides a simple task management wrapper for the MTAPI interface. Using the example from the previous section, the signature of the action function for the tasks interface looks like this: +% +\\\inputlisting{../examples/tasks/tasks_cpp_action_signature-snippet.h} +% +First, the node instance needs to be obtained. If the node is not initialized yet, this function will do it. +% +\\\inputlisting{../examples/tasks/tasks_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::tasks::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} +% +After that, the first part of the computation is launched as an MTAPI task using \lstinline|embb::tasks::Node::Spawn()| (registering an action function with a job is done automatically): +% +\\\inputlisting{../examples/tasks/tasks_cpp_calc_task-snippet.h} +% +The second part can be executed directly: +% +\\\inputlisting{../examples/tasks/tasks_cpp_calc_direct-snippet.h} +% +Then, completion of the MTAPI task has to be waited for using \lstinline|embb::tasks::Task::Wait()|: +% +\\\inputlisting{../examples/tasks/tasks_cpp_wait_task-snippet.h} +% +Finally, the two parts can be added and written into the result buffer: +% +\\\inputlisting{../examples/mtapi/mtapi_write_back-snippet.h} +% + +The \lstinline|fibonacci()| function also gets simpler compared to the C version. The MTAPI runtime is initialized automatically, only the node instance has to be fetched: +% +\\\inputlisting{../examples/tasks/tasks_cpp_get_node-snippet.h} +% +The root task can be started using \lstinline|embb::tasks::Node::Spawn()| directly, registering with a job is done automatically: +% +\\\inputlisting{../examples/tasks/tasks_cpp_start_task-snippet.h} +% +Again, the started task has to be waited for (using \lstinline|embb::tasks::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::tasks::Node::Initialize|, the runtime must also be shut down explicitly by calling \lstinline|embb::tasks::Node::Finalize|.} diff --git a/doc/tutorial/tutorial.tex b/doc/tutorial/tutorial.tex index 6a7c920..4e969e1 100644 --- a/doc/tutorial/tutorial.tex +++ b/doc/tutorial/tutorial.tex @@ -114,6 +114,7 @@ % \input{content/preface} \input{content/introduction} \input{content/mtapi} +\input{content/tasks} \input{content/algorithms} \input{content/dataflow} \input{content/containers} -- libgit2 0.26.0