diff --git a/docs/Build.rst b/docs/Build.rst
index fd9aec9..079af7d 100755
--- a/docs/Build.rst
+++ b/docs/Build.rst
@@ -1,352 +1,353 @@
===========================
Building the RoSA Framework
===========================
.. contents::
:local:
Build Dependencies
==================
In order to build RoSA, the following tools are required:
* `CMake `_ (minimum version 3.6.0 if clang-tidy is used,
2.8.8 otherwise);
* Build system of your choice that can be targeted by CMake -- including a
compiler supporting *C++14*.
* Clang/LLVM -- minimum version 3.9.0
[#f-clang_template_argument_deduction_DeluxeAgent]_
The following additional tools are required to generate documentation:
* `Doxygen `_ -- for generating API documentation;
* `Graphviz `_ -- not necessary, but the API
documentation has nicer graphics when `dot` is available;
* `Sphinx `_ (with *Python 2*) -- for generating
documentation.
The following additional tools are required to check and possibly enforce coding
standard:
* `clang-tidy `_
* `clang-format `_
General notes
=============
* The framework is delivered with a CMake project, which can be used to generate
build projects to build the framework.
* The provided CMake project supports out-of-tree builds only, i.e. one must use
a separate build directory outside of the RoSA source directory.
+.. _doxygen-warnings:
+
* Doxygen warnings -- typically indicating actual errors -- are printed to
- `stderr`, do check that when generating API documentation which is under
- development.
+ `stderr`, do check that when generating API documentation.
.. _cmake-variables:
CMake Variables
===============
Beyond the usual CMake variables, the following project-related options are
available:
`ROSA_INCLUDE_TOOLS`
Generate build targets for RoSA tools. The tools are also built when the
option is set to `ON`, which is the default setting.
`ROSA_INCLUDE_EXAMPLES`
Generate build targets for RoSA examples. The examples are also built when the
option is set to `ON`, which is the default setting.
`ROSA_ENABLE_PEDANTIC`
Compile the framework with using `-pedantic` for GCC-compatible compilers,
otherwise ignored. The option defaults to `ON`.
`ROSA_ENABLE_ASSERTIONS`
Enable assertions for non-Debug builds, which defaults to `OFF`.
Note that assertions are always enabled for Debug builds and this option is
ignored for such builds.
.. _CMake_clang_tidy:
`ROSA_ENABLE_CLANG_TIDY`
Run *clang-tidy* checks when building RoSA, which defaults to `OFF`.
When the variable is enabled, build targets created by *Makefile* and *Ninja*
generators include calls for clang-tidy. Other generators ignore this option.
Note that CMake variables `CMAKE__CLANG_TIDY` are set when enabled.
Settings for clang-tidy are defined by the file `.clang-tidy` in the RoSA
source directory.
Consider the following options when the option is enabled:
`ROSA_CLANG_TIDY_PATH`
Custom path for `clang-tidy` executable.
In order to use clang-tidy, CMake needs to find the `clang-tidy`
executable. If `clang-tidy` to be used is available via `PATH`, just leave
the option empty -- which is default. Set the absolute path of the
directory containing the `clang-tidy` executable otherwise, in which case
no default path is searched for `clang-tidy`.
`ROSA_CLANG_TIDY_FIX`
Apply suggested clang-tidy fixes to the sources, which defaults to `OFF`.
Enable the option only if you know what you are doing.
.. _CMake_clang_format:
`ROSA_INCLUDE_CLANG_FORMAT` **[experimental]**
Generate build target -- `format-rosa` -- for formatting RoSA sources with
*clang-format*, which defatuls to `OFF`.
When the variable is enabled and *CMake is not running on a Windows host*, a
build target is generated which can be used to have all the RoSA sources
formatted with clang-format. Settings for clang-format are defined by the file
`.clang-format` in the RoSA source directory.
Note that executing build target `format-rosa` will reformat all the source
files *inplace*.
Consider the following option when a build target for clang-format is to be
generated:
`ROSA_CLANG_FORMAT_PATH`
Custom path for `clang-format` executable.
In order to use clang-format, CMake needs to find the `clang-format`
executable. If `clang-format` to be used is available via `PATH`, just
leave the option empty -- which is default. Set the absolute path of the
directory containing the `clang-format` executable otherwise, in which case
no default path is search for `clang-format`.
`ROSA_LOG_LEVEL`
Level of logging to be used, use one of the following valid integer values.
======== =========
Variable Log Level
======== =========
`0` `ERROR`
`1` `WARNING`
`2` `INFO`
`3` `DEBUG`
`4` `TRACE`
`5` *disabled*
======== =========
Level of logging defaults to *disabled*.
`ROSA_INCLUDE_DOCS`
Generate build targets for RoSA documentation, defaults to `ON`.
Note that the automatic execution of the generated build targets is
controlled by the option `ROSA_BUILD_DOCS`. The actual documentations to
build are controlled by the options `ROSA_ENABLE_DOXYGEN` and
`ROSA_ENABLE_SPHINX`.
`ROSA_BUILD_DOCS`
Build RoSA documentation automatically as part of the build process. The
option defaults to `OFF` and takes effect only if the option
`ROSA_INCLUDE_DOCS` is enabled.
.. _CMake_doxygen:
`ROSA_ENABLE_DOXYGEN`
Use *doxygen* to generate RoSA API documentation. The option defaults to `OFF`
and takes effect only if the option `ROSA_INCLUDE_DOCS` is enabled.
Doxygen documentation may be generated by executing build target
`doxygen-rosa`, which is done as part of the default build process if
`ROSA_BUILD_DOCS` is enabled.
Doxygen must be available via `PATH` if the option is enabled.
The following options are also available to tune doxygen:
`ROSA_DOXYGEN_SVG`
Use *svg* instead of *png* files for doxygen graphs. The option defaults to
`OFF` and takes effect if the tool *dot* is available via `PATH` to be used
to generated graph images.
`ROSA_DOXYGEN_EXTERNAL_SEARCH`
Enable doxygen external search, which defatuls to `OFF`.
The following options need to be set if the option is enabled:
`ROSA_DOXYGEN_SEARCHENGINE_URL`
URL to use for external search.
`ROSA_DOXYGEN_SEARCH_MAPPINGS`
Doxygen Search Mappings.
.. _CMake_sphinx:
`ROSA_ENABLE_SPHINX`
Use *Sphinx* to generate RoSA documentation. The option defaults to `OFF` and
takes effect only if the option `ROSA_INCLUDE_DOCS` is enabled.
Sphinx must be available via `PATH` if the option is enabled.
The following options are also available to tune Sphinx:
`SPHINX_OUTPUT_HTML`
Output standalone HTML files. The option defaults to `ON`.
Documentation may be generated by executing build target `docs-rosa-html`,
which is done as part of the default build process if `ROSA_BUILD_DOCS` is
enabled.
`SPHINX_OUTPUT_MAN`
Output man pages for RoSA tools. The option defaults to `ON`.
Man pages may be generated by executing build target `docs-rosa-man`, which
is done as part of the default build process if `ROSA_BUILD_DOCS` is
enabled.
`SPHINX_WARNINGS_AS_ERRORS`
When building documentation, treat Sphinx warnings as errors. The option
defaults to `ON`.
Building RoSA Step-by-Step
==========================
Building on Linux with Make
---------------------------
Configuring and building the framework on Linux using *Make* is a
straightforward process which does not require performing any tricks.
Set C and C++ compilers with the variables `CC` and `CXX`, respectively. Use the
CMake variable `CMAKE_BUILD_TYPE` to set the type of build: `Debug`, `Release`.
Follows an example on building the framework with all options turned on. CMake
variables may be skipped as necessary. You need to have RoSA sources on your
computer.::
rosa-src$ cd ..
$ mkdir rosa-build
$ cd rosa-build
rosa-build$ CC= CXX= -G "Unix Makefiles" -DROSA_ENABLE_CLANG_TIDY=ON -DROSA_CLANG_TIDY_PATH= -DROSA_INCLUDE_CLANG_FORMAT=ON -DROSA_CLANG_FORMAT_PATH= -DROSA_LOG_LEVEL=4 -DROSA_ENABLE_DOXYGEN=ON -DROSA_DOXYGEN_SVG=ON -DROSA_ENABLE_SPHINX=ON -DCMAKE_BUILD_TYPE=Debug ../rosa-src
[CMake configures and generates without errors]
$ make
[Make builds the project]
You just need to re-run Make in order to re-build the project after changing
the source code and the CMake project. In case the CMake project is changed,
Make automatically calls CMake to update the build project.
In order to build documentation and enforce coding standard, refer to
corresponding :ref:`cmake-variables`.
.. _Build_VS:
Building on Windows with Visual Studio
--------------------------------------
Unfortunately, the native MSVC compiler cannot compile the framework. One needs
to use Clang with Visual Studio in order to build the framework.
Microsoft recently started to bundle a special version of Clang to Visual Studio
as the *Clang/C2* module. That compiler is, however, several versions behind the
official LLVM releases as of Visual Studio 2017. Therefore, it is necessary to
use *LLVM for Windows* as an external toolset for Visual Studio.
For using *LLVM for Windows*, one downloads the official binary release from
http://llvm.org and consults with its documentation. The release provides
integration for Visual Studio starting from Visual Studio 2010.
Prepare your toolchain like this:
#. Install Visual Studio.
* If installing Visual Studio 2017, make sure the component
*VC++ 2015.3 v140 toolset (x86,x64)* on the *Individual components* tab is
selected in *Visual Studio Installer*. Installing the older *v140 toolset*
is necessary because the LLVM integration (as of version 4.0.1) does not
support the *v141 toolset*, which is default for Visual Studio 2017.
* Otherwise, default installation of Visual Studio should go.
#. Install *LLVM for Windows*.
#. Install the integration by executing as *Administrator*::
> \tools\msbuild\install.bat
Having your build system prepared and RoSA sources fetched to your computer,
configure and build the framework like this:
#. Generate Visual Studio solution with CMake:
#. Start CMake.
#. Define *source directory* and a separate *build directory* in CMake.
#. Click *Configure*.
#. Select the proper *generator* for your version of Visual Studio.
#. Define your optional toolset (argument for `-T`) as `LLVM-vs`.
* Note that `` refers to the version of Visual Studio: `2010`,
`2012`, `2013`, and `2014`. Visual Studio 2017 with the *v140 toolset*
uses `2014`.
#. Click *Finish*.
#. Tune CMake variables as you wish.
* Note that Visual Studio Generators are multi-configuration generators,
hence you cannot set `CMAKE_BUILD_TYPE`. You need to select a
configuration to build in Visual Studio.
#. Click *Generate*.
#. Build the framework with Visual Studio:
#. Open the generated `RoSA.sln` from the build directory with Visual
Studio.
#. Build the project `ALL_BUILD`.
You just need to re-build the project in Visual Studio after changing the
source code and the CMake project.
In case the CMake project is changed, Visual Studio automatically calls CMake
the update the build project.
Build Result
============
The build process works in the build directory. After a successful build, one
can find the following final outputs there -- besides some intermediate files.
.. _Build_Result_Software:
Software
--------
In the build directory, `include` contains header files which are generated by
CMake and provide configuration-specific information.
The build process generates static libraries in `lib` and executables --
examples and tools -- in `bin`. Projects generated by a multi-configuration
generator result in the actual libraries and executables being located in
subdirectories corresponding to different build configurations.
.. _Build_Result_Documentation:
Documentation
-------------
Documentation is generated in `docs`.
The general documentation can be found in `docs/html`. Man pages for tools can
be found in `docs/man`.
The API documentation can be found in `docs/doxygen/html`.
.. rubric:: Footnotes
.. [#f-clang_template_argument_deduction_DeluxeAgent]
Clang breaks on template argument deduction when instantiating the class
`rosa::deluxe::DeluxeAgent`, the issue is gone with clang version 3.9.0 and
newer. Check the documentation on the relevant constructor for more details.
diff --git a/docs/Dev.rst b/docs/Dev.rst
index 50b9c77..be05ab6 100755
--- a/docs/Dev.rst
+++ b/docs/Dev.rst
@@ -1,355 +1,357 @@
=============================
Developing the RoSA Framework
=============================
.. contents::
:local:
This document provides information that might be useful for contributing to
RoSA. Please also consult :doc:`Build`.
.. _Dev_Source_Directory:
The Source Directory
====================
The source directory consists of the following subdirectories:
`cmake`
Contains files used for configuring the `CMake Project`_.
`docs`
Contains `Documentation`_-related files.
`examples`
Contains `Examples`_ on using the public API.
`include/rosa`
Contains the RoSA public API -- that is the interface of RoSA `Libraries`_.
The directory `include` is to be used as include directory and RoSA header
files are to be included in C++ sources as `"rosa/"`.
`lib`
Contains the implementation of the RoSA public API -- that is the
implementation of RoSA `Libraries`_.
`tools`
Contains `Tools`_ based on RoSA features.
Software Sources
================
The section describes the `Logical Structure`_ of the software sources and what
`Coding Standards`_ are supposed to be followed for the implementation.
Logical Structure
-----------------
Various features provided by RoSA are sorted into different `Libraries`_.
`Examples`_ and `Tools`_ using those `Libraries`_ are separated from the
implementation of the RoSA features into different directories.
Libraries
~~~~~~~~~
The framework consists of separate libraries providing different features. The
public interfaces for RoSA libraries are defined in `include/rosa`, while
corresponding implementation is in `lib`. Each library has its own subdirectory
in the mentioned directories.
RoSA provides the following libraries:
`config`
Provides information on the configuration used to build the framework, e.g.,
version number, log level, assertions, and debugging.
`support`
Provides general features -- template metaprograms dealing with types, for
instance -- for implementing other libraries.
`core`
Provides the basic RoSA features, like systems managing agents passing
messages.
`agent`
Provides features to be used for implementing agents.
`deluxe`
Provides a somewhat more modular interface for defining systems with RoSA.
.. _Library_Dependencies:
Dependencies
''''''''''''
The following table summarizes dependencies among libraries.
A marking in a row denotes that the library in the beginning of the row depends
on the library in the head of the given column.
+---------+--------+---------+------+--------+-------+
| | config | support | core | deluxe | agent |
+=========+========+=========+======+========+=======+
| config | | | | | |
+---------+--------+---------+------+--------+-------+
| support | | | | | |
+---------+--------+---------+------+--------+-------+
| core | | × | | | |
+---------+--------+---------+------+--------+-------+
| deluxe | | | × | | |
+---------+--------+---------+------+--------+-------+
| agent | | | | | |
+---------+--------+---------+------+--------+-------+
Examples
~~~~~~~~
Some simple samples are provided in `examples` to demonstrate how to to use
different parts of the RoSA API.
Tools
~~~~~
Tools, programs based on the RoSA libraries, are implemented in `tools`.
.. _Coding_Standards:
Coding Standards
----------------
RoSA is implemented in standard *C++14* code. All the software sources are to
be written in accordance to the `LLVM Coding Standards`_.
Feature Restrictions
~~~~~~~~~~~~~~~~~~~~
Pay attention `not to use RTTI and Exceptions`_. Those features are disabled in
the CMake project.
Documentation Comments
~~~~~~~~~~~~~~~~~~~~~~
It is important to remember to document source code using `doxygen comments`_
as `API Documentation`_ is generated directly from sources.
Note that the syntax of documentation comments is checked during compilation --
-at least when using a GCC-compatible compiler.
+at least when using a GCC-compatible compiler. Further, check
+:ref:`Doxygen warnings ` as issues not being detected by the
+compiler may be found when actually generating the documentation.
Whenever you work on a source file, make sure your name is in the author-list
defined in the header comment of the file. Each author should be defined with a
separate `\\author` command so that recent authors come first. Authors not
participating in further development of a file anymore may be marked with the
period of their contribution.
If declarations belonging to a namespace are spread to more than one source
files, document the namespace in a separate `namespace.h` in the directory
belonging to the library. Otherwise, document the namespace in the only file in
which entities of the namespace are declared.
Header Files
~~~~~~~~~~~~
Follow the recommendations on public and private header files and the usage of
`#include` from the `LLVM Coding Standards`_.
Use `.h` and `.hpp` extensions to indicate the content of the header file:
* header files containing any *definition* -- template or inline definition --
or including another header file with `.hpp` extension have `.hpp` extension;
* header files containing only *declarations* and including only header files
with `.h` extension have `.h` extension.
It may happen that a header file does not need any corresponding implementation
in a `.cpp` file. Nevertheless, do create a corresponding `.cpp` file which only
includes the header file in this case. That makes sure that the header file is
compiled and hence checked for errors, and also a corresponding entry in the
compilation database is generated.
Checking and Enforcing the Coding Standards
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The tools `clang-tidy `_ and
`clang-format `_ can be used to
check and enforce the coding standards. The two tools are integrated into the
CMake project, refer to CMake variables
:ref:`ROSA_ENABLE_CLANG_TIDY ` and
:ref:`ROSA_INCLUDE_CLANG_FORMAT `.
Note that there may be situations when `clang-tidy` checks result in false
positives -- for example, for some cases of the order of `#include` directives.
One can order `clang-tidy` to suppress warnings for a line of code by marking
that line with::
// NOLINT
It may be preferred to diverge from the standard formatting -- for example for
the sake of readability of static definition of arrays following some
structure. One can disable `clang-format` for some lines of code by designating
a range with two special comments as::
// clang-format off
... clang-format is disabled here ...
// clang-format on
Documentation
=============
The RoSA Framework is delivered with two kinds of documentation: `General
Documentation`_ and `API Documentation`_, generation of both of which is
integrated into the CMake project.
References between the two documentations are relative addresses corresponding
to the directory structure of the
:ref:`generated documentation `.
General Documentation
---------------------
General documentation is written as
`reStructuredText `_ compiled with
`Sphinx `_. For build integration, refer to the
CMake variable :ref:`ROSA_ENABLE_SPHINX `.
Documentation files are located in `docs` with extension `.rst`. The main
page of the documentation is `docs/index.rst`. Configuration for building the
documentation is `docs/conf.py`.
The directory `docs/CommandGuide` contains documentation for each separate
tool. Those pages are included in the HTML documentation via
`docs/CommandGuide/index.rst`. Moreover, man pages can be generated from those
tool documentation pages.
API Documentation
-----------------
API documentation is directly generated from sources with
`Doxygen `_. For build integration, refer to the CMake
variable :ref:`ROSA_ENABLE_DOXYGEN `.
The main page used for the API documentation is `docs/doxygen-mainpage.dox`.
Configuration for generating the API documentation is `docs/doxygen.cfg.in`.
.. _CMake Project:
Managing the CMake Project
==========================
This section briefly summarizes when and how to modify CMake files during
the development process. No general discussion on CMake features is provided
here.
When modifying `Documentation`_, no need to update the CMake files.
Software
--------
One needs to modify the CMake files only if source files are to be added or
removed from the project. Here follows some typical scenarios.
Source Files
~~~~~~~~~~~~
Each library and executable target has its own directory and its own definition
as a file called `CMakeLists.txt` in that directory.
When adding or removing a source file -- both headers and `.cpp` files -- to a
library or executable, locate the corresponding `CMakeLists.txt` file. The file
is typically in the same directory where the file to be added or removed is
located. Except for header files of the public API, for which the corresponding
CMake target is defined in a `lib` subdirectory corresponding to the library the
header files belongs to.
Update the source list in the argument of the `add_library` or `add_executable`
command in the `CMakeLists.txt`, for libraries and executables, respectively.
A library and executable may use features provided by another library. Such a
dependency is to be defined in the `CMakeLists.txt` file of the dependent
target by using the `ROSA_add_library_dependencies` command.
CMake Libraries
~~~~~~~~~~~~~~~
When adding or removing a library, add or remove the corresponding directories
from `include` and `lib`, and also update `lib/CMakeLists.txt` by adding or
removing a `add_subdirectory` command for the library.
When defining a new library, the new subdirectory under `lib` needs to contain a
`CMakeLists.txt`, which needs to contain at least an `add_library` command
defining the name of the library and the source files belonging to it.
CMake Executables
~~~~~~~~~~~~~~~~~
When adding or removing an executable, add or remove the corresponding
directory from `examples` or `tools`, and also update `CMakeLists.txt` in the
containing directory as for libraries.
When defining a new executable, the new subdirectory needs to contain a
`CMakeLists.txt`, which needs to contain at least an `add_executable` command
defining the name of the executable and the source files belonging to it.
.. _Dev Managing Sources:
Managing Sources
================
Consider the followings before committing changes to the repository:
* your code complies with the `Coding Standards`_ as much as possible;
* your code is well documented;
* your code is not bloated with unusued code and/or comments;
* your changes do not break building and executing the framework:
* test all of the supported platforms if possible,
* look into the generated documentation if you have edited
`General Documentation`_;
* you do not pollute the repository with unused and generated files.
When committing changes to the repository, provide a concise log message with
your commit.
Miscellaneous Concerns
======================
Using YCM
---------
If you happen to use `YCM `_, just
make a copy of the provided `ycm_extra_conf.py.template` file as
`.ycm_extra_conf.py` in the RoSA source directory, and set the following two
variables in it:
`compilation_database_folder`
the absolute path of your build directory
`extra_system_include_dirs`
any system include directory which might not be searched by `libclang` [1]_.
You probably want compile with Clang if you use YCM, so run CMake with
environment variables `CC=clang` and `CXX=clang++` set.
Also note that header files in the `include` directory are compiled for YCM with
the compiler flags of a corresponding source file in the `lib` directory, if
any. Header files in other locations are supposed to have a corresponding source
file in the same directory.
Notes
~~~~~
* If the project's include directory (`include/rosa`) would ever be changed,
then the YCM configuration file needs to be adjusted accordingly.
.. rubric:: Footnotes
.. [1] See: https://github.com/Valloric/YouCompleteMe/issues/303; use the
following command to figure out the used system directories:
echo | clang -std=c++11 -v -E -x c++ -
.. _`LLVM Coding Standards`: http://llvm.org/docs/CodingStandards.html
.. _`not to use RTTI and Exceptions`: http://llvm.org/docs/CodingStandards.html#do-not-use-rtti-or-exceptions
.. _`doxygen comments`: http://llvm.org/docs/CodingStandards.html#doxygen-use-in-documentation-comments
diff --git a/docs/Issues.rst b/docs/Issues.rst
index 3f2a4b9..a0fd6bc 100755
--- a/docs/Issues.rst
+++ b/docs/Issues.rst
@@ -1,54 +1,53 @@
==================================================================
Known Issues with the Current Implementation of the RoSA Framework
==================================================================
.. contents::
:local:
TODO
====
* Project logo - `docs/_themes/rosa-theme/static/logo.png`
* License?
* Packaging with
`CPack `_.
* What about design documentation on the basics of RoSA?
* What about testing the framework?
Known Issues
============
* CMake
* VS2017 generates intermediate files for the `ZERO_CHECK` project out of the
build directory, see `CMake issue #16458`_.
* C++
* Mangled names of function pointers with non-throwing exception specification
in function signature will change in C++17. That renders binaries generated
with C++14 and C++17 incompatible (for linking).
* Since version 4.0.0, Clang warns about this compatibility issue as part
of `-Wc++1z-compat`. That warning is turned off in the build scripts.
* The langauge standard for building RoSA libraries and applications needs
to be lockstepped: now use C++14 only and step to C++17 later when it is
properly supported by all major compilers.
* Doxygen
- * There are some strange warnings reported by doxygen when generating
- documentation.
- * There are some entities for which no or partial documentation is generated,
- but no indication of any problem is reported by doxygen.
+ * "Potential recursive class relation" is detected for `rosa::GenSeq`, which
+ is true if one ignores the template specialization for the terminal case.
+ It would be nice not to have this pointless warning.
* clang-tidy
* Clang-tidy reports warnings about `noexcept` marking for the move
constructor and move assignment operator of `rosa::Optional` in some
situations when the template with the non-specialized argument list is used
-- for example, in the file `example/deluxe-interface/deluxe-interface.cpp`.
However, the condition for the `noexcept` marking should be met and the
warning is pointless.
.. _CMake issue #16458: https://gitlab.kitware.com/cmake/cmake/issues/16458
diff --git a/include/rosa/core/Invoker.hpp b/include/rosa/core/Invoker.hpp
index d13057e..32126ad 100644
--- a/include/rosa/core/Invoker.hpp
+++ b/include/rosa/core/Invoker.hpp
@@ -1,256 +1,256 @@
//===-- rosa/core/Invoker.hpp -----------------------------------*- C++ -*-===//
//
// The RoSA Framework
//
//===----------------------------------------------------------------------===//
///
/// \file rosa/core/Invoker.hpp
///
/// \author David Juhasz (david.juhasz@tuwien.ac.at)
///
/// \date 2017
///
/// \brief Facilities for providing actual arguments for functions as
/// \c rosa::Messageobjects.
///
//===----------------------------------------------------------------------===//
#ifndef ROSA_CORE_INVOKER_HPP
#define ROSA_CORE_INVOKER_HPP
#include "rosa/core/MessageMatcher.hpp"
#include "rosa/support/log.h"
#include "rosa/support/sequence.hpp"
#include
#include
namespace rosa {
/// Wraps a function and provides a simple interface to invoke the stored
/// function by passing actual arguments as a \c rosa::Message object.
///
/// \note A \c rosa::Invoker instance is supposed to be owned by a
/// \c rosa::MessageHandler instance, and not being used directly from user
/// code.
class Invoker {
protected:
/// Creates an instance.
///
/// \note Protected constructor restricts instantiation to derived classes.
Invoker(void) noexcept;
public:
/// Destroys \p this object.
virtual ~Invoker(void);
/// Possible results of an invocation.
enum class Result {
NoMatch, ///< The wrapped function could not be invoked
Invoked ///< The wrapped function has been invoked
};
/// Type alias for a smart-pointer for \c rosa::Invoker.
using invoker_t = std::unique_ptr;
/// Type alias for \c rosa::Invoker::Result.
using result_t = Result;
/// Tells if a \c rosa::Message object can be used to invoke the function
/// wrapped in \p this object.
///
/// \param Msg \c rosa::Message to check
///
/// \return whether \p Msg can be used to invoke the wrapped function
virtual bool match(const Message &Msg) const noexcept = 0;
/// Tries to invoke the wrapped function with a \c rosa::Message object.
///
/// The wrapped function is invoked if the actual \c rosa::Message object can
/// be used to invoke it.
///
/// \param Msg \c rosa::Message to try to invoke the wrapped function with
///
/// \return whether the wrapped function could be invoked with \p Msg
virtual result_t operator()(const Message &Msg) const noexcept = 0;
/// Instantiates an implementation of \c rosa::Invoker with the given
/// function.
///
/// \note As there is no empty \c rosa::Message, no \c rosa::Invoker wraps a
/// function without any argument.
///
/// \tparam T type of the first mandatory argument
/// \tparam Ts types of any further arguments
///
/// \param F function to wrap
///
/// \return new \c rosa::Invoker::invoker_t object created from the given
/// function
template
static invoker_t wrap(std::function &&F) noexcept;
/// Convenience template alias for casting callable stuff to function objects
/// for wrapping.
///
/// \tparam Ts types of arguments
///
/// \todo Should make it possible to avoid using an explicit conversion for
/// the arguments of wrap.
template using F = std::function;
/// Convenience template for preparing non-static member functions into
/// function objects for wrapping.
///
/// \tparam C type whose non-static member the function is
/// \tparam Ts types of arguments
///
/// \see \c THISMEMBER
template
static inline F M(C *O, void (C::*Fun)(Ts...) noexcept) noexcept;
};
/// Convenience preprocessor macro for the typical use of \c rosa::Invoker::M.
/// It can be used inside a class to turn a non-static member function into a
/// function object capturing this pointer, so using the actual object when
/// handling a \c rosa::Message.
///
/// \param FUN the non-static member function to wrap
///
/// \note Inside the class \c MyClass, use\code
/// THISMEMBER(fun)
/// \endcode instead of\code
/// Invoker::M(this, &MyClass::fun)
/// \endcode
#define THISMEMBER(FUN) \
Invoker::M(this, &std::decay::type::FUN)
/// Nested namespace with implementation of \c rosa::Invoker and helper
/// templates, consider it private.
namespace {
-/// \defgroup InvokerImpl
+/// \defgroup InvokerImpl Implementation for rosa::Invoker
///
/// Implements the \c rosa::Invoker interface for functions with different
/// signatures.
///
///@{
/// Declaration of \c rosa::InvokerImpl implementing \c rosa::Invoker.
///
/// \tparam Fun function to wrap
template class InvokerImpl;
/// Implementation of \c rosa::InvokerImpl for \c std::function.
///
/// \tparam T type of the first mandatory argument
/// \tparam Ts types of further arguments
///
/// \note As there is no empty \c rosa::Message, no \c rosa::Invoker wraps a
/// function without any argument, i.e., no
/// \c std::function.
template
class InvokerImpl> final
: public Invoker {
/// Type alias for the stored function.
using function_t = std::function;
/// Type alias for correctly typed argument-tuples as obtained from
/// \c rosa::Message.
using args_t = std::tuple;
/// Alias for \c rosa::MessageMatcher for the arguments of the stored
/// function.
using Matcher = MsgMatcher;
/// The wrapped function.
const function_t F;
/// Invokes \c InvokerImpl::F by unpacking arguments from a \c std::tuple with
/// the help of the actual template arguments.
///
/// \tparam S sequence of numbers indexing \c std::tuple for arguments
///
/// \param Args arguments to invoke \c InvokerImpl::F with
///
/// \pre the length of \p S and size of \p Args are matching:\code
/// sizeof...(S) == std::tuple_size::value
/// \endcode
template
inline void invokeFunction(Seq, const args_t &Args) const noexcept;
public:
/// Creates an instance.
///
/// \param F function to wrap
///
/// \pre \p F is valid:\code
/// bool(F)
/// \endcode
InvokerImpl(function_t &&F) noexcept : F(F) {
ASSERT(bool(F)); // Sanity check.
}
/// Destroys \p this object.
~InvokerImpl(void) = default;
/// Tells if a \c rosa::Message object can be used to invoke the function
/// wrapped in \p this object.
///
/// \param Msg \c rosa::Message to check
///
/// \return whether \p Msg can be used to invoke the wrapped function
bool match(const Message &Msg) const noexcept override {
return Matcher::doesStronglyMatch(Msg);
};
/// Tries to invoke the wrapped function with a \c rosa::Message object.
///
/// The wrapped function is invoked if the actual \c rosa::Message object can
/// be used to invoke it.
///
/// \param Msg \c rosa::Message to try to invoke the wrapped function with
///
/// \return whether the wrapped function could be invoked with \p Msg
result_t operator()(const Message &Msg) const noexcept override {
if (match(Msg)) {
LOG_TRACE("Invoking with matching arguments");
invokeFunction(typename GenSeq::Type(),
Matcher::extractedValues(Msg));
return result_t::Invoked;
} else {
LOG_TRACE("Tried to invoke with non-matching arguments");
return result_t::NoMatch;
}
}
};
template
template
void InvokerImpl>::invokeFunction(
Seq, const args_t &Args) const noexcept {
ASSERT(sizeof...(S) == std::tuple_size::value); // Sanity check.
F(std::get(Args)...);
}
///@}
} // End namespace
template
Invoker::invoker_t
Invoker::wrap(std::function &&F) noexcept {
return std::unique_ptr(
new InvokerImpl>(std::move(F)));
}
template
Invoker::F Invoker::M(C *O, void (C::*Fun)(Ts...) noexcept) noexcept {
return [ O, Fun ](Ts... Vs) noexcept->void { (O->*Fun)(Vs...); };
}
} // End namespace rosa
#endif // ROSA_CORE_INVOKER_HPP
diff --git a/include/rosa/core/Message.hpp b/include/rosa/core/Message.hpp
index 49e78aa..ce9e6ec 100644
--- a/include/rosa/core/Message.hpp
+++ b/include/rosa/core/Message.hpp
@@ -1,257 +1,258 @@
//===-- rosa/core/Message.hpp -----------------------------------*- C++ -*-===//
//
// The RoSA Framework
//
//===----------------------------------------------------------------------===//
///
/// \file rosa/core/Message.hpp
///
/// \author David Juhasz (david.juhasz@tuwien.ac.at)
///
/// \date 2017
///
/// \brief Declaration of \c rosa::Message base-class.
///
//===----------------------------------------------------------------------===//
#ifndef ROSA_CORE_MESSAGE_HPP
#define ROSA_CORE_MESSAGE_HPP
#include "rosa/support/log.h"
#include "rosa/support/tokenized_storages.hpp"
#include "rosa/core/forward_declarations.h"
namespace rosa {
/// *Message* interface.
///
/// The interface provides means to check the type of the stored values, but
/// actual data is to be managed by derived implementations.
///
/// A \c rosa::Message instance is an immutable data object that obtains its
/// data upon creation and provides only constant references for the stored
/// values.
///
/// \note Any reference obtained from a \c rosa::Message instance remains valid
/// only as long as the owning \c rosa::Message object is not destroyed.
///
/// \todo Some member functions of \c rosa::Message duplicate member functions
/// of \c rosa::TokenizedStorage, which cannot be easily factored out into a
/// common base class due to eventual diamond inheritance issues in derived
/// classes. Could this duplication be avoided?
class Message {
protected:
/// Creates a new instance.
///
/// \note No implementation for empty list.
///
/// \tparam Type type of the mandatory first argument
/// \tparam Types types of any further arguments
///
/// \note the actual arguments are ignored by the constructor it is only
/// their type that matters. The actual values are supposed to be handled by
/// any implementation derived from \c rosa::Message.
///
/// \pre \p Type and \p Types are all built-in types and the number of stored
/// values does not exceed \c rosa::token::MaxTokenizableListSize.
template
Message(const Type &, const Types &...) noexcept;
/// No copying and moving of \c rosa::Message instances.
///@{
Message(const Message &) = delete;
Message(Message &&) = delete;
Message &operator=(const Message &) = delete;
Message &operator=(Message &&) = delete;
///@}
public:
/// Creates a \c rosa::message_t object from constant lvalue references.
///
/// \tparam Type type of the mandatory first argument
/// \tparam Types types of any further arguments
///
/// \param T the first value to include in the \c rosa::Message
/// \param Ts optional further values to include in the \c rosa::Message
///
/// \return new \c rosa::message_t object created from the given arguments
template
static message_t create(const Type &T, const Types &... Ts) noexcept;
/// Creates a \c rosa::message_t object from rvalue references.
///
/// \tparam Type type of the mandatory first argument
/// \tparam Types types of any further arguments
///
/// \param T the first value to include in the \c rosa::Message
/// \param Ts optional further values to include in the \c rosa::Message
///
/// \return new \c rosa::message_t object created from the given arguments
template
static message_t create(Type &&T, Types &&... Ts) noexcept;
/// Represents the types of the values stored in \p this object.
///
/// A valid, non-empty \c rosa::Token representing the types of the values
/// stored in \p this object.
const Token T;
/// The number of values stored in \p this object.
///
/// That is the number of types encoded in \c rosa::Message::T.
const size_t Size;
/// Destroys \p this object.
virtual ~Message(void);
/// Tells if the value stored at a given index is of a given type.
///
/// \note Any \c rosa::AtomConstant is encoded in \c rosa::Token as
/// the \c rosa::AtomValue wrapped into it.
///
/// \tparam Type type to match against
///
/// \param Pos index the type of the value at is to be matched against \p Type
///
/// \return if the value at index \p Pos of type \p Type
///
/// \pre \p Pos is a valid index:\code
/// Pos < Size
/// \endcode
template bool isTypeAt(const size_t Pos) const noexcept;
/// Gives a constant reference of a value of a given type stored at a given
/// index.
///
/// \tparam Type type to give a reference of
///
/// \param Pos index to set the reference for
///
/// \return constant reference of \p Type for the value stored at index \p Pos
///
/// \pre \p Pos is a valid index and the value at index \p Pos is of type
- /// \p Type:\code
+ /// \p Type:
+ /// \code
/// Pos < Size && isTypeAt(Pos)
/// \endcode
template const Type &valueAt(const size_t Pos) const noexcept;
protected:
/// Provides an untyped pointer for the value at a given index.
///
/// \param Pos index to take a pointer for
///
/// \return untyped pointer for the value stored at index \p Pos
///
/// \pre \p Pos is a valid index:\code
/// Pos < Size
/// \endcode
virtual const void *pointerTo(const size_t Pos) const noexcept = 0;
};
/// Nested namespace with implementation for \c rosa::Message, consider it
/// private.
namespace {
/// Template class for an implementation of \c rosa::Message.
///
/// \tparam Types types whose values are to be stored
template class LocalMessage;
/// Implementation of the template \c rosa::LocalMessage providing facilities
/// for storing values as a \c rosa::Message object.
///
/// \tparam Type type of the first mandatory value of the \c rosa::Message
/// \tparam Types of any further values
template
class LocalMessage final
: public Message,
private TokenizedStorage {
public:
/// Creates an instance from constant lvalue references.
///
/// \param T the mandatory first value to store in the \c rosa::Message object
/// \param Ts optional further values to store in the \c rosa::Message object
LocalMessage(const Type &T, const Types &... Ts) noexcept
: Message(T, Ts...),
TokenizedStorage(T, Ts...) {
ASSERT(this->T == this->ST && Size == this->size()); // Sanity check.
}
/// Creates an instance from rvalue references.
///
/// \param T the mandatory first value to store in the \c rosa::Message object
/// \param Ts optional further values to store in the \c rosa::Message object
LocalMessage(Type &&T, Types &&... Ts) noexcept
: Message(T, Ts...),
TokenizedStorage(std::move(T), std::move(Ts)...) {
ASSERT(this->T == this->ST && Size == this->size()); // Sanity check.
}
/// Provides an untyped pointer for the constant value stored at a position.
///
/// \param Pos the index of the value to return an untyped pointer for
///
/// \return untyped pointer for the constant value stored at index \p Pos
///
/// \pre \p Pos is a valid index:\code
/// Pos < Size
/// \endcode
const void *pointerTo(const size_t Pos) const noexcept override {
ASSERT(Pos < Size);
return TokenizedStorage::pointerTo(Pos);
}
/// Aborts the program!
///
/// Since \c rosa::Message instances are supposed to be immutable, the
/// non-const inherited function is overridden so that it aborts execution.
void *pointerTo(const size_t) noexcept override {
ROSA_CRITICAL("Unallowed operation of rosa::LocalMessage");
}
};
} // End namespace
template
Message::Message(const Type &, const Types &...) noexcept
: T(TypeToken::type,
typename std::decay::type...>::Value),
Size(lengthOfToken(T)) {
ASSERT(validToken(T) &&
lengthOfToken(T) == (1 + sizeof...(Types))); // Sanity check.
LOG_TRACE("Creating Message with Token(" + to_string(T) + ")");
}
/// \note The implementation instantiates a private local template class
/// \c LocalMessage.
template
message_t Message::create(const Type &T, const Types &... Ts) noexcept {
return message_t(new LocalMessage(T, Ts...));
}
/// \note The implementation instantiates a private local template class
/// \c LocalMessage.
template
message_t Message::create(Type &&T, Types &&... Ts) noexcept {
return message_t(
new LocalMessage(std::move(T), std::move(Ts)...));
}
template
bool Message::isTypeAt(const size_t Pos) const noexcept {
ASSERT(Pos < Size);
Token TT = T;
dropNOfToken(TT, Pos);
return isHeadOfTokenTheSameType(TT);
}
template
const Type &Message::valueAt(const size_t Pos) const noexcept {
ASSERT(Pos < Size && isTypeAt(Pos));
return *static_cast(pointerTo(Pos));
}
} // End namespace rosa
#endif // ROSA_CORE_MESSAGE_HPP
diff --git a/include/rosa/core/MessageMatcher.hpp b/include/rosa/core/MessageMatcher.hpp
index 1b4e549..71bd69f 100644
--- a/include/rosa/core/MessageMatcher.hpp
+++ b/include/rosa/core/MessageMatcher.hpp
@@ -1,201 +1,201 @@
//===-- rosa/core/MessageMatcher.hpp ----------------------------*- C++ -*-===//
//
// The RoSA Framework
//
//===----------------------------------------------------------------------===//
///
/// \file rosa/core/MessageMatcher.hpp
///
/// \author David Juhasz (david.juhasz@tuwien.ac.at)
///
/// \date 2017
///
/// \brief Facilities for checking and matching types of values stored in
/// \c rosa::Message instances.
///
//===----------------------------------------------------------------------===//
#ifndef ROSA_CORE_MESSAGEMATCHER_HPP
#define ROSA_CORE_MESSAGEMATCHER_HPP
#include "rosa/core/Message.hpp"
#include
namespace rosa {
/// Provides features to type-check a \c rosa::Message instance and extract
/// stored values from it into an \c std::tuple instance with matching type
/// arguments.
///
/// \tparam List \c rosa::TypeList to check the stored values against
template struct MessageMatcher;
/// Definition of \c rosa::MessageMatcher for non-empty lists of types, like
/// \c rosa::Message itself.
///
/// \tparam Type first mandatory type
/// \tparam Types any further types
template
struct MessageMatcher> {
/// \c rosa::Token associated to the given \c rosa::TypeList.
static constexpr Token T = TypeToken::Value;
/// Tells if the values stored in a \c rosa::Message instance are matching
/// types given as \c rosa::TypeList, considering
/// \c rosa::AtomConstant instead of \c rosa::AtomValue.
///
/// \param Msg \c rosa::Message to match
///
/// \return whether the types of values stored in \p Msg matches
/// \c rosa::TypeList
static inline bool doesStronglyMatch(const Message &Msg) noexcept;
/// Gives a \c std::tuple with references to the values stored in a
/// type-matching instance of \c rosa::Message.
///
/// \param Msg \c rosa::Message to extract values from
///
/// \return \c std::tuple with references to the values stored in \p Msg
///
/// \pre Types of the values stored in \p Msg matches
/// \c rosa::TypeList:\code
/// doesStronglyMatch(Msg)
/// \endcode
static inline std::tuple
extractedValues(const Message &Msg) noexcept;
};
/// Turns a list of types into a \c rosa::TypeList for \c rosa::MessageMatcher.
template
using MsgMatcher = MessageMatcher>;
/// Nested namespace with implementation for features of
/// \c rosa::MessageMatcher, consider it private.
namespace {
-/// \defgroup MessageMatcherImpl
+/// \defgroup MessageMatcherImpl Implementation for rosa::MessageMatcher
///
/// An implementation of type-checking and value extraction for
/// \c rosa::MessageMatcher.
///
///@{
/// Template declaration of \c MessageMatcherImpl.
///
/// \tparam List \c rosa::TypeList to match against
template struct MessageMatcherImpl;
/// Specialization for \c rosa::EmptyTypeList.
template <> struct MessageMatcherImpl {
static bool doesStronglyMatchFrom(const Message &Msg,
const size_t Pos) noexcept {
// Matching EmptyTypeList only if reached the end of the stored types.
return Pos == Msg.Size;
}
static std::tuple<> extractedValuesFrom(const Message &Msg,
const size_t Pos) noexcept {
// It is valid to extract an empty list only if we reached the end of
// stored values.
ASSERT(doesStronglyMatchFrom(Msg, Pos));
return std::tie();
}
};
/// Specialization for \c rosa::AtomValue in the head.
template
struct MessageMatcherImpl, Ts...>> {
static bool doesHeadStronglyMatchAt(const Message &Msg,
const size_t Pos) noexcept {
// Matching a \c rosa::AtomConstant in the head if there is a type stored at
// \p Pos, the stored type is \c rosa::AtomValue, and the corresponding
// value matches the \c rosa::AtomValue \p V.
return Pos < Msg.Size && Msg.isTypeAt(Pos) &&
Msg.valueAt(Pos) == V;
}
static bool doesStronglyMatchFrom(const Message &Msg,
const size_t Pos) noexcept {
// Matching a non-empty list if the head is matching and the rest of the
// list is matching.
return doesHeadStronglyMatchAt(Msg, Pos) &&
MessageMatcherImpl>::doesStronglyMatchFrom(Msg,
Pos + 1);
}
static std::tuple &, const Ts &...>
extractedValuesFrom(const Message &Msg, const size_t Pos) noexcept {
// Extracting for a non-empty list with a matching \c rosa::AtomConstant in
// the head by getting the encoded \c rosa::AtomConstant and concatenating
// it with values extracted for the rest of the list.
ASSERT(doesHeadStronglyMatchAt(Msg, Pos));
return std::tuple_cat(
std::tie(AtomConstant::Value),
MessageMatcherImpl>::extractedValuesFrom(Msg, Pos + 1));
}
};
/// Definition for the general case when a regular built-in type (not a
/// \c rosa::AtomConstant) is in the head.
template
struct MessageMatcherImpl> {
static bool doesHeadStronglyMatchAt(const Message &Msg,
const size_t Pos) noexcept {
// Matching the head if there is a type stored at \p Pos, and the stored
// type is \p T.
return Pos < Msg.Size && Msg.isTypeAt(Pos);
}
static bool doesStronglyMatchFrom(const Message &Msg,
const size_t Pos) noexcept {
// Matching a non-empty list if the head is matching and the rest of the
// list is matching.
return doesHeadStronglyMatchAt(Msg, Pos) &&
MessageMatcherImpl>::doesStronglyMatchFrom(Msg,
Pos + 1);
}
static std::tuple
extractedValuesFrom(const Message &Msg, const size_t Pos) noexcept {
// Extracting for a non-empty list with a matching head by getting the
// value for the head and concatenating it with values extracted for the
// rest of the list.
ASSERT(doesHeadStronglyMatchAt(Msg, Pos));
return std::tuple_cat(
std::tie(Msg.valueAt(Pos)),
MessageMatcherImpl>::extractedValuesFrom(Msg, Pos + 1));
}
};
///@}
} // End namespace
-template
-bool MessageMatcher>::doesStronglyMatch(
+template
+bool MessageMatcher>::doesStronglyMatch(
const Message &Msg) noexcept {
// \note Fail quick on \c rosa::MessageMatcher::T, then match against list
// with squashed integers the way \c rosa::Token is generated.
return T == Msg.T &&
MessageMatcherImpl>::Type>::doesStronglyMatchFrom(Msg, 0);
+ TypeList>::Type>::doesStronglyMatchFrom(Msg, 0);
}
-template
-std::tuple
-MessageMatcher>::extractedValues(
+template
+std::tuple
+MessageMatcher>::extractedValues(
const Message &Msg) noexcept {
ASSERT(doesStronglyMatch(Msg));
// \note Match against a list with squashed integers as \c rosa::Token is
// generated.
return MessageMatcherImpl>::Type>::extractedValuesFrom(Msg, 0);
+ TypeList>::Type>::extractedValuesFrom(Msg, 0);
}
} // End namespace rosa
#endif // ROSA_CORE_MESSAGEMATCHER_HPP
diff --git a/include/rosa/core/MessagingSystem.hpp b/include/rosa/core/MessagingSystem.hpp
index 5b6fd14..7e9b3cf 100644
--- a/include/rosa/core/MessagingSystem.hpp
+++ b/include/rosa/core/MessagingSystem.hpp
@@ -1,198 +1,201 @@
//===-- rosa/core/MessagingSystem.hpp ---------------------------*- C++ -*-===//
//
// The RoSA Framework
//
//===----------------------------------------------------------------------===//
///
/// \file rosa/core/MessagingSystem.hpp
///
/// \author David Juhasz (david.juhasz@tuwien.ac.at)
///
/// \date 2017
///
/// \brief Declaration of an interface extending \c rosa::System with messaging.
///
//===----------------------------------------------------------------------===//
#ifndef ROSA_CORE_MESSAGINGSYSTEM_HPP
#define ROSA_CORE_MESSAGINGSYSTEM_HPP
#include "rosa/core/AgentHandle.hpp"
#include "rosa/core/System.hpp"
#include "rosa/support/atom.hpp"
namespace rosa {
/// Extends the \c rosa::System interface with features to create \c rosa::Agent
/// instancess and register \c rosa::Message objects for them.
class MessagingSystem : public System {
friend class AgentHandle; ///< \c rosa::AgentHandle is our friend.
public:
/// Returns an object implementing the \c rosa::MessagingSystem interface.
///
/// \param Name name of the new instance
///
/// \return \c std::unique_ptr for the new instance of
/// \c rosa::MessagingSystem
static std::unique_ptr
createSystem(const std::string &Name) noexcept;
private:
/// Kind for categorizing \c rosa::Unit instances as *agents*.
static constexpr AtomValue AgentKind = atom("agent");
protected:
/// Creates a new instance.
///
/// \note Protected constructor restricts instantiation for subclasses.
MessagingSystem(void) noexcept = default;
protected:
/// Creates a \c rosa::Agent instance owned by \p this object and returns a
/// \c rosa::AgentHandle for it.
///
/// \tparam T type of the actual \c rosa::Agent to instantiate
/// \tparam Funs types of the functions to instantiate \c rosa::Agent with
///
/// \note \c rosa::Agent requires at least one function for its constructor,
/// but derived classes may do not need that. That's the reason of allowing
/// zero \p Funs for this template function.
///
/// \param Name name of the new \c rosa::Unit instance
/// \param Fs functions to instantiate \c rosa::Unit with
///
- /// \pre Statically, \p T is a subclass of \c rosa::Agent:\code
+ /// \return handle for the new \c rosa::Agent instance
+ ///
+ /// \pre Statically, \p T is a subclass of \c rosa::Agent:
+ /// \code
/// std::is_base_of::value
/// \endcode
template
AgentHandle createAgent(const std::string &Name, Funs &&... Fs);
/// Unregisters and destroys a \c rosa::Agent referred by a
/// \c rosa::AgentHandle.
///
/// The function uses \c rosa::System::destroyUnit.
///
/// \param H refers to the \c rosa::Agent to destroy
///
/// \pre The referred \c rosa::Agent is registered.
///
/// \post The referred \c rosa::Agent is not registered and also destroyed.
void destroyAgent(const AgentHandle &H) noexcept;
/// Gives the referenced \c rosa::Agent instance for a \c rosa::AgentHandle.
///
/// \note Intended for derived classes to be able to inspect
/// \c rosa::AgentHandle instances.
///
/// \param H \c rosa::AgentHandle to take the referenced \c rosa::Agent from
///
/// \return reference to the \c rosa::Agent instance from \p H
static Agent &unwrapAgent(const AgentHandle &H) noexcept { return H.A; }
/// Gives the owning \c rosa::MessagingSystem of a \c rosa::Agent instance
/// for a \c rosa::AgentHandle.
///
/// \note Intended for for derived classes to be able to inspect
/// \c rosa::AgentHandle instances.
///
/// \param H \c rosa::AgentHandle to take the owning
/// \c rosa::MessagingSystem from
///
/// \return reference to the \c rosa::MessagingSystem owning the
/// \c rosa::Agent instance from \p H
static MessagingSystem &unwrapSystem(const AgentHandle &H) noexcept {
return H.S;
}
public:
/// Sends a \c rosa::message_t instance to the \c rosa::Agent instance
/// referred by a \c rosa::AgentHandle.
///
/// \note If the given \c rosa::Message object cannot be handled by the
/// referred \c rosa::Agent instance, the \c rosa::Message object is simply
/// ignored.
///
/// \param H refers to the \c rosa::Agent instance to send to
/// \param M message to send
///
/// \pre The referred \c rosa::Agent instance is owned by \p this object and
/// also registered: \code
/// &unwrapSystem(H) == this && isUnitRegistered(unwrapAgent(H))
/// \endcode
virtual void send(const AgentHandle &H, message_t &&M) noexcept = 0;
/// Sends a message -- created from given constant lvalue references --
/// to the \c rosa::Agent instance referred by a \c rosa::AgentHandle.
///
/// \note If the given \c rosa::Message object cannot be handled by the
/// referred \c rosa::Agent instance, the \c rosa::Message object is simply
/// ignored.
///
/// \note The message must consists of at least one value.
///
/// \tparam Type type of the first mandatory value
/// \tparam Types types of any further values
///
/// \param H refers to the \c rosa::Agent instance to send to
/// \param T the first value to include in the message
/// \param Ts optional further values to include in the message
///
/// \pre The referred \c rosa::Agent instance is owned by \p this object and
/// also registered: \code
/// &unwrapSystem(H) == this && isUnitRegistered(unwrapAgent(H))
/// \endcode
template
void send(const AgentHandle &H, const Type &T, const Types &... Ts) noexcept;
/// Sends a message -- created from given rvalue references --
/// to the \c rosa::Agent instance referred by a \c rosa::AgentHandle.
///
/// \note If the given \c rosa::Message object cannot be handled by the
/// referred \c rosa::Agent instance, the \c rosa::Message object is simply
/// ignored.
///
/// \note The message must consists of at least one value.
///
/// \tparam Type type of the first mandatory value
/// \tparam Types types of any further values
///
/// \param H refers to the \c rosa::Agent instance to send to
/// \param T the first value to include in the message
/// \param Ts optional further values to include in the message
///
/// \pre The referred \c rosa::Agent instance is owned by \p this object and
/// also registered: \code
/// &unwrapSystem(H) == this && isUnitRegistered(unwrapAgent(H))
/// \endcode
template
void send(const AgentHandle &H, Type &&T, Types &&... Ts) noexcept;
};
template
AgentHandle MessagingSystem::createAgent(const std::string &Name,
Funs &&... Fs) {
STATIC_ASSERT((std::is_base_of::value), "not an Agent");
Agent &A = createUnit([&](const id_t Id,
MessagingSystem &S) noexcept {
return new T(AgentKind, Id, Name, S, std::move(Fs)...);
});
return {A};
}
template
void MessagingSystem::send(const AgentHandle &H, const Type &T,
const Types &... Ts) noexcept {
send(H, Message::create(T, Ts...));
}
template
void MessagingSystem::send(const AgentHandle &H, Type &&T,
Types &&... Ts) noexcept {
send(H, Message::create(std::move(T), std::move(Ts)...));
}
} // End namespace rosa
#endif // ROSA_CORE_MESSAGINGSYSTEM_HPP
diff --git a/include/rosa/core/System.hpp b/include/rosa/core/System.hpp
index 8925692..7a5488d 100644
--- a/include/rosa/core/System.hpp
+++ b/include/rosa/core/System.hpp
@@ -1,238 +1,240 @@
//===-- rosa/core/System.hpp ------------------------------------*- C++ -*-===//
//
// The RoSA Framework
//
//===----------------------------------------------------------------------===//
///
/// \file rosa/core/System.hpp
///
/// \author David Juhasz (david.juhasz@tuwien.ac.at)
///
/// \date 2017
///
/// \brief Declaration of *System* interface.
///
//===----------------------------------------------------------------------===//
#ifndef ROSA_CORE_SYSTEM_HPP
#define ROSA_CORE_SYSTEM_HPP
#include "rosa/config/config.h"
#include "rosa/core/forward_declarations.h"
#include "rosa/support/debug.hpp"
#include "rosa/support/log.h"
#include
#include
#include
namespace rosa {
/// Base interface for actual agent-systems.
///
/// The class provides facilities to keep track of \c rosa::Unit instances owned
/// by a \c rosa::System.
///
/// \note Any subclass is supposed to provide thread-safe implementation.
///
/// \note The class declares only an interface to avoid trouble with multiple
/// inheritance in various subclasses as in derived interfaces and derived
/// implementations.
///
/// \note Actual implementations are supposed to derive from \c rosa::SystemBase
/// implenenting a base feature-set.
class System {
public:
/// Signature of creator functions for \c rosa::Unit instances.
///
/// \tparam T type derived from \c rosa::Unit
/// \tparam S type derived from \c rosa::System
template
using UnitCreator = std::function;
/// Returns an object implementing the \c rosa::System interface.
///
/// \param Name name of the new instance
///
/// \return \c std::unique_ptr for a new instance of \c rosa::System
static std::unique_ptr createSystem(const std::string &Name) noexcept;
protected:
/// Creates an instance.
///
/// \note Protected constructor restricts instantiation for subclasses.
System(void) noexcept = default;
/// No copying and moving of \c rosa::System.
///@{
System(const System &) = delete;
System(System &&) = delete;
System &operator=(const System &) = delete;
System &operator=(System &&) = delete;
///@}
public:
/// Destroys \p this object.
///
/// \note Any implementation makes sure that a \c rosa::System can be
/// destroyed only if it is marked *cleaned*
/// \see \c rosa::System::isSystemCleaned
virtual ~System(void) = default;
/// Tells whether \p this object is the same as \p Other.
///
/// \note Whenever checking equality of two objects, use the one with the
/// more specialized static type on the left-hand side of the operator. The
/// static type of the object on the right-hand side is better to be
/// \c rosa::System, ambiguous conversion might happen otherwise.
///
/// \param Other another \c rosa::System instance to compare to
///
/// \return whether \p this object and \p Other is the same
virtual bool operator==(const System &Other) const noexcept = 0;
/// Tells whether \p this object is not the same as \p Other.
///
/// \note Whenever checking inequality of two objects, use the one with the
/// more specialized static type on the left-hand side of the operator. The
/// static type of the object on the right-hand side is better to be
/// \c rosa::System, ambiguous conversion might happen otherwise.
///
/// \param Other another \c rosa::System instance to compare to
///
/// \return whether \p this object and \p Other is not the same
bool operator!=(const System &Other) const noexcept {
return !operator==(Other);
}
protected:
/// Tells the next unique identifier to be used for a newly created
/// \c rosa::Unit.
///
/// \return \c rosa::id_t which is unique within the context of \p this
/// object.
///
/// \note Never returs the same value twice.
virtual id_t nextId(void) noexcept = 0;
/// Tells if \p this object has been marked cleaned and is ready for
/// destruction.
///
/// \return if \p this object is marked clean.
virtual bool isSystemCleaned(void) const noexcept = 0;
/// Marks \p this object cleaned.
///
/// \note Can be called only once when the System does not have any live
/// \c rosa::Unit instances.
///
/// \pre \p this object has not yet been marked as cleaned and it has no
/// \c rosa::Unit instances registered:\code
/// !isSystemCleaned() && empty()
/// \endcode
///
/// \post \p this object is marked cleaned:\code
/// isSystemCleaned()
- /// \encode
+ /// \endcode
virtual void markCleaned(void) noexcept = 0;
/// Registers a \c rosa::Unit instance to \p this object.
///
/// \param U \c rosa::Unit to register
///
/// \pre \p this object has not yet been marked as cleaned and \p U is not
/// registered yet:\code
/// !isSystemCleaned() && !isUnitRegistered(U)
/// \endcode
///
/// \post \p U is registered:\code
/// isUnitRegistered(U)
/// \endcode
virtual void registerUnit(Unit &U) noexcept = 0;
/// Unregisters and destroys a registered \c rosa::Unit instance.
///
/// \param U \c rosa::Unit to destroy
///
/// \pre \p U is registered:\code
/// isUnitRegistered(U)
/// \endcode
///
/// \post \p U is not registered and also destroyed.
virtual void destroyUnit(Unit &U) noexcept = 0;
/// Tells if a \c rosa::Unit is registered in \p this object.
///
/// \param U \c rosa::Unit to check
///
/// \return whether \p U is registered in \p this object
virtual bool isUnitRegistered(const Unit &U) const noexcept = 0;
/// Creates a \c rosa::Unit instance with the given
/// \c rosa::System::UnitCreator and registers the new instance.
///
/// \tparam T type of the actual \c rosa::Unit to instantiate
/// \tparam S type of the actual \c rosa::System instantiating
///
/// \param C function creating an instance of type \p T
///
/// \note \p S must be the actual subclass that wants to instantiate
/// \c rosa::Unit. That cannot be statically enforced, it is the
/// reponsibility of the caller to provide the proper \c rosa::System
/// subclass.
///
/// \pre Statically, \p T is a subclass of \c rosa::Unit and \p S is a
- /// subclass of \c rosa::System:\code
+ /// subclass of \c rosa::System:
+ /// \code
/// std::is_base_of::value && std::is_base_of::value
- /// \endcode Dynamically, \p this object has not yet been marked cleaned:\code
+ /// \endcode
+ /// Dynamically, \p this object has not yet been marked cleaned:\code
/// !isSystemCleaned()
/// \endcode
template T &createUnit(UnitCreator C) noexcept;
public:
/// Tells the name of \p this object
///
/// \note The returned reference remains valid as long as \p this object is
/// not destroyed.
///
/// \return name of \p this object
virtual const std::string &name(void) const noexcept = 0;
/// Tells the number of \c rosa::Unit instances constructed in the context of
/// \p this object so far, including those being already destroyed.
///
/// \return number of \c rosa::Unit instances created so far
virtual size_t numberOfConstructedUnits(void) const noexcept = 0;
/// Tells the number of live \c rosa::Unit instances in the context \p this
/// object, those being constructed and not destroyed yet.
///
/// \return number of \c rosa::Unit instances alive
virtual size_t numberOfLiveUnits(void) const noexcept = 0;
/// Tells if \p this object has no live \c rosa::Unit instances.
///
/// \return whether \p this object has any live \c rosa::Unit instances
virtual bool empty(void) const noexcept = 0;
};
template
T &System::createUnit(UnitCreator C) noexcept {
STATIC_ASSERT((std::is_base_of::value), "not a Unit");
STATIC_ASSERT((std::is_base_of::value), "not a System");
if (isSystemCleaned()) {
ROSA_CRITICAL("Trying to create a Unit in a cleaned System '" + name() +
"'");
}
const id_t Id = nextId();
T *U = C(Id, static_cast(*this));
registerUnit(*U);
LOG_TRACE("Unit created and registered '" + U->FullName + "'");
return *U;
}
} // End namespace rosa
#endif // ROSA_CORE_SYSTEM_HPP
diff --git a/include/rosa/core/SystemBase.hpp b/include/rosa/core/SystemBase.hpp
index 83439e7..a5ca0d2 100644
--- a/include/rosa/core/SystemBase.hpp
+++ b/include/rosa/core/SystemBase.hpp
@@ -1,138 +1,138 @@
//===-- rosa/core/SystemBase.hpp -----------------------------*- C++ -*-===//
//
// The RoSA Framework
//
//===----------------------------------------------------------------------===//
///
/// \file rosa/core/SystemBase.hpp
///
/// \author David Juhasz (david.juhasz@tuwien.ac.at)
///
/// \date 2017
///
/// \brief Base implementation of the \c rosa::System interface.
///
//===----------------------------------------------------------------------===//
#ifndef ROSA_CORE_SYSTEMBASE_HPP
#define ROSA_CORE_SYSTEMBASE_HPP
#include "rosa/core/System.hpp"
#include
namespace rosa {
/// Base implementation of the \c rosa::System interface.
///
/// This implementation provides only equality checking and *name* for
/// \c rosa::System, identifiers for \c rosa::Unit instances, and marking the
/// \c rosa::System cleaned for destruction.
///
/// \note Actual implementations of \c rosa::System and derived interfaces are
/// supposed to inherit from this implementation.
class SystemBase : public System {
protected:
/// Creates an instance.
///
/// \note Protected constructor restrict instantiation for subclasses.
///
/// \param Name name of the new instance
SystemBase(const std::string &Name) noexcept;
public:
/// Destroys \p this object.
///
/// \pre \p this object is marked cleaned:\code
/// isSystemCleaned()
/// \endcode
~SystemBase(void);
/// Tells whether \p this object is the same as \p Other.
///
/// Two \c rosa::System instances are considered equal if they share a common
/// \c rosa::SystemBase::Name member field. That should do among various
/// subclasses.
///
/// \param Other another \c rosa::System instance to compare to
///
/// \return whether \p this object and \p Other is the same
bool operator==(const System &Other) const noexcept override;
protected:
/// The textual name of \p this object implementing \c rosa::System.
const std::string Name;
private:
/// Number of \c rosa::Unit instances constructed by \p this object.
///
/// \note Should never be decremented!
std::atomic UnitCount;
/// Indicates that \p this object has been cleaned and is ready for
/// destruction.
///
/// The field is initialized as \c false and can be set by
/// \c rosa::SystemBase::markCleaned.
///
/// \note Subclasses must set the flag upon destructing their instances, which
/// indicates to the destructor of the base-class that all the managed
/// resources has been properly released.
std::atomic SystemIsCleaned;
public:
/// Tells the name of \p this object
///
/// \note The returned reference remains valid as long as \p this object is
/// not destroyed.
///
/// \return reference to \c rosa::SystemBase::Name
const std::string &name(void) const noexcept override;
protected:
/// Tells the next unique identifier to be used for a newly created
/// \c rosa::Unit.
///
/// The functions takes the current value of the internal counter
/// \c rosa::SystemBase::UnitCount and then increments it.
///
/// \note This is the only function modifying
/// \c rosa::SystemBase::UnitCount.
///
/// \return \c rosa::id_t which is unique within the context of \p this
/// object.
id_t nextId(void) noexcept override;
/// Tells if \p this object has been marked cleaned and is ready for
/// destruction.
///
/// \return if \p this object is marked clean.
bool isSystemCleaned(void) const noexcept override;
/// Marks \p this object cleaned by setting
/// \c rosa::SystemBase::SystemIsCleaned.
///
/// \note Can be called only once when the System does not have any live
/// \c rosa::Unit instances.
///
/// \pre \p this object has not yet been marked as cleaned and it has no
/// \c rosa::Unit instances registered:\code
/// !isSystemCleaned() && empty()
/// \endcode
///
/// \post \p this object is marked cleaned:\code
/// isSystemCleaned()
- /// \encode
+ /// \endcode
void markCleaned(void) noexcept override;
/// Tells the number of \c rosa::Unit instances constructed in the context of
/// \p this object so far, including those being already destroyed.
///
/// \return current value of \c rosa::SystemBase::UnitCount that is the number
/// of \c rosa::Unit instances created so far
size_t numberOfConstructedUnits(void) const noexcept override;
};
} // End namespace rosa
#endif // ROSA_LIB_CORE_SYSTEMBASE_HPP
diff --git a/include/rosa/deluxe/DeluxeAgent.hpp b/include/rosa/deluxe/DeluxeAgent.hpp
index 479b09d..720576f 100755
--- a/include/rosa/deluxe/DeluxeAgent.hpp
+++ b/include/rosa/deluxe/DeluxeAgent.hpp
@@ -1,680 +1,680 @@
//===-- rosa/deluxe/DeluxeAgent.hpp -----------------------------*- C++ -*-===//
//
// The RoSA Framework
//
//===----------------------------------------------------------------------===//
///
/// \file rosa/deluxe/DeluxeAgent.hpp
///
/// \author David Juhasz (david.juhasz@tuwien.ac.at)
///
/// \date 2017
///
/// \brief Specialization of \c rosa::Agent for *agent* role of the *deluxe
/// interface*.
///
/// \see \c rosa::deluxe::DeluxeContext
///
//===----------------------------------------------------------------------===//
#ifndef ROSA_DELUXE_DELUXEAGENT_HPP
#define ROSA_DELUXE_DELUXEAGENT_HPP
#include "rosa/core/Agent.hpp"
#include "rosa/deluxe/DeluxeAtoms.hpp"
#include