diff --git a/CMakeLists.txt b/CMakeLists.txt
index 846833f..d284dd1 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1,186 +1,181 @@
cmake_minimum_required(VERSION 2.8.8)
# Start project, set version here.
project("RoSA")
# NOTE: Adjust the variables version and release in docs/conf.py according to
# version changes here.
set(ROSA_VERSION_MAJOR 0)
set(ROSA_VERSION_MINOR 1)
set(ROSA_VERSION_PATCH 0)
# Add path for custom modules
set(CMAKE_MODULE_PATH
${CMAKE_MODULE_PATH}
"${CMAKE_CURRENT_SOURCE_DIR}/cmake"
"${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules"
)
# Package information
if( NOT PACKAGE_VERSION )
set(PACKAGE_VERSION "${ROSA_VERSION_MAJOR}.${ROSA_VERSION_MINOR}.${ROSA_VERSION_PATCH}")
endif()
set(PACKAGE_NAME "Research on Self-Awareness Framework")
set(PACKAGE_STRING "${PACKAGE_NAME} ${PACKAGE_VERSION}")
set(PACKAGE_BUGREPORT "david.juhasz@tuwien.ac.at")
#TODO: cpack?
# Sanity check we are to make out-of-tree build
if( CMAKE_SOURCE_DIR STREQUAL CMAKE_BINARY_DIR )
message(FATAL_ERROR "In-source builds are not allowed.")
endif()
string(TOUPPER "${CMAKE_BUILD_TYPE}" uppercase_CMAKE_BUILD_TYPE)
# Set various paths
set(ROSA_MAIN_SRC_DIR ${CMAKE_CURRENT_SOURCE_DIR})
set(ROSA_MAIN_INCLUDE_DIR ${ROSA_MAIN_SRC_DIR}/include)
set(ROSA_MAIN_BIN_DIR ${ROSA_MAIN_SRC_DIR}/bin)
set(ROSA_BINARY_DIR ${CMAKE_CURRENT_BINARY_DIR})
set(ROSA_RUNTIME_OUTPUT_INTDIR ${ROSA_BINARY_DIR}/${CMAKE_CFG_INTDIR}/bin)
set(ROSA_LIBRARY_OUTPUT_INTDIR ${ROSA_BINARY_DIR}/${CMAKE_CFG_INTDIR}/lib)
set(ROSA_TOOLS_BINARY_DIR ${ROSA_RUNTIME_OUTPUT_INTDIR})
set(ROSA_LIBRARY_DIR ${ROSA_LIBRARY_OUTPUT_INTDIR})
set(ROSA_INCLUDE_DIR ${ROSA_BINARY_DIR}/include)
# Set build options
option(ROSA_INCLUDE_TOOLS "Generate build targets for RoSA tools." ON)
option(ROSA_INCLUDE_EXAMPLES "Generate build targets for RoSA examples." ON)
option(ROSA_ENABLE_PEDANTIC "Compile with pedantic enabled." ON)
# Assertions are always enabled for Debug builds, this option is respected only
# for non-Debug builds.
option(ROSA_ENABLE_ASSERTIONS "Enable assertions for non-Debug builds." OFF)
option(ROSA_ENABLE_CLANG_TIDY "Run clang-tidy checks when building RoSA." OFF)
option(ROSA_INCLUDE_CLANG_FORMAT "Generate build target for formatting RoSA sources with clang-format." OFF)
option(ROSA_INCLUDE_DOCS "Generate build targets for RoSA documentation." ON)
option(ROSA_BUILD_DOCS "Build RoSA documentation." OFF)
option(ROSA_ENABLE_DOXYGEN "Use doxygen to generate RoSA API documentation." OFF)
option(ROSA_ENABLE_SPHINX "Use Sphinx to generate RoSA documentation." OFF)
set(ROSA_LOG_LEVEL "" CACHE STRING "Level of logging to be used.")
# All options referred to from HandleROSAOptions have to be specified
# BEFORE this include, otherwise options will not be correctly set on
# first cmake run
include(config-ix)
include(HandleROSAOptions)
# Configure the ROSA configuration header file.
if( NOT ROSA_LOG_LEVEL STREQUAL "")
if( ${ROSA_LOG_LEVEL} EQUAL 5 )
set(ROSA_LOG_LEVEL_INT -1)
else()
set(ROSA_LOG_LEVEL_INT ${ROSA_LOG_LEVEL})
endif()
else()
set(ROSA_LOG_LEVEL_INT -1)
endif()
configure_file(
${ROSA_MAIN_INCLUDE_DIR}/rosa/config/rosa_config.h.cmake
${ROSA_INCLUDE_DIR}/rosa/config/rosa_config.h
)
# They are not referenced. See set_output_directory().
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${ROSA_BINARY_DIR}/bin)
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${ROSA_BINARY_DIR}/lib)
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${ROSA_BINARY_DIR}/lib)
# Set include directories
set(CMAKE_INCLUDE_CURRENT_DIR ON)
include_directories(${ROSA_INCLUDE_DIR} ${ROSA_MAIN_INCLUDE_DIR})
-# Set extra compiler options for Visual Studio
-if ( MSVC )
- add_definitions(-EHsc) # Use Exception Handling
-endif()
-
# Set up YCM
set(CMAKE_EXPORT_COMPILE_COMMANDS 1)
message("Set compilation_database_folder in .ymc_extra_conf.py in the source directory if you want to use YMC.")
# Add parts of the project
include(AddROSATools)
add_subdirectory(lib)
if( ROSA_INCLUDE_TOOLS )
add_subdirectory(tools)
endif()
if( ROSA_INCLUDE_EXAMPLES )
add_subdirectory(examples)
endif()
if( ROSA_INCLUDE_DOCS )
add_subdirectory(docs)
endif()
#TODO: install?
# Print summary
set(ROSA_ENABLE_ASSERTIONS_STR "OFF")
if( ROSA_ENABLE_ASSERTIONS_INT EQUAL 1 )
set(ROSA_ENABLE_ASSERTIONS_STR "ON")
endif()
set(LOG_LEVEL_STR "disabled")
if( NOT ROSA_LOG_LEVEL STREQUAL "" )
if( ${ROSA_LOG_LEVEL} EQUAL 0 )
set(LOG_LEVEL_STR "ERROR")
elseif( ${ROSA_LOG_LEVEL} EQUAL 1 )
set(LOG_LEVEL_STR "WARNING")
elseif( ${ROSA_LOG_LEVEL} EQUAL 2 )
set(LOG_LEVEL_STR "INFO")
elseif( ${ROSA_LOG_LEVEL} EQUAL 3 )
set(LOG_LEVEL_STR "DEBUG")
elseif( ${ROSA_LOG_LEVEL} EQUAL 4 )
set(LOG_LEVEL_STR "TRACE")
elseif( ${ROSA_LOG_LEVEL} EQUAL 5 )
set(LOG_LEVEL_STR "disabled")
else()
set(LOG_LEVEL_STR "invalid")
endif()
endif()
message(STATUS
"\n====================| Build Summary |===================="
"\n"
"\nRoSA version: ${PACKAGE_VERSION}"
"\n"
"\nBuild type: ${CMAKE_BUILD_TYPE}"
"\nAssertions: ${ROSA_ENABLE_ASSERTIONS_STR}"
"\nClang-tidy: ${ROSA_ENABLE_CLANG_TIDY}"
"\nClang-format: ${ROSA_INCLUDE_CLANG_FORMAT}"
"\nLog level: ${LOG_LEVEL_STR}"
"\n"
"\nBuild tools: ${ROSA_INCLUDE_TOOLS}"
"\nBuild examples: ${ROSA_INCLUDE_EXAMPLES}"
"\nInclude docs: ${ROSA_INCLUDE_DOCS}"
"\nBuild docs: ${ROSA_BUILD_DOCS}"
"\n -enable doxygen: ${ROSA_ENABLE_DOXYGEN}"
"\n -enable Sphinx: ${ROSA_ENABLE_SPHINX}"
"\n"
"\nCC: ${CMAKE_C_COMPILER}"
"\nCFLAGS: ${CMAKE_C_FLAGS}"
"\nCXX: ${CMAKE_CXX_COMPILER}"
"\nCXXFLAGS: ${CMAKE_CXX_FLAGS}"
"\nLIBRARIES: ${LD_FLAGS}"
"\n"
"\nSource directory: ${ROSA_MAIN_SRC_DIR}"
"\nBuild directory: ${ROSA_BINARY_DIR}"
"\nExecutable path: ${ROSA_TOOLS_BINARY_DIR}"
"\nLibrary path: ${ROSA_LIBRARY_DIR}"
"\nGenerator: ${CMAKE_GENERATOR}"
"\n"
"\n===========================================================\n")
diff --git a/cmake/modules/HandleROSAOptions.cmake b/cmake/modules/HandleROSAOptions.cmake
index 98102e8..c64f194 100644
--- a/cmake/modules/HandleROSAOptions.cmake
+++ b/cmake/modules/HandleROSAOptions.cmake
@@ -1,171 +1,204 @@
# This CMake module is responsible for interpreting the user defined ROSA_
# options and executing the appropriate CMake commands to realize the users'
# selections.
include(CheckCCompilerFlag)
include(CheckCXXCompilerFlag)
if ( "${CMAKE_CXX_COMPILER_ID}" MATCHES "Clang" )
set(ROSA_COMPILER_IS_CLANG ON)
# Enforce minimum version.
if ( CMAKE_CXX_COMPILER_VERSION VERSION_LESS "3.9.0" )
message(FATAL_ERROR "Insufficient LLVM version")
endif()
else()
set(ROSA_COMPILER_IS_CLANG OFF)
endif()
if( CMAKE_COMPILER_IS_GNUCXX )
set(ROSA_COMPILER_IS_GCC_COMPATIBLE ON)
elseif( MSVC )
set(ROSA_COMPILER_IS_GCC_COMPATIBLE OFF)
elseif( ROSA_COMPILER_IS_CLANG )
set(ROSA_COMPILER_IS_GCC_COMPATIBLE ON)
else()
message(FATAL_ERROR "Unexpected C++ compiler!")
endif()
function(append value)
foreach(variable ${ARGN})
set(${variable} "${${variable}} ${value}" PARENT_SCOPE)
endforeach(variable)
endfunction()
function(append_if condition value)
if (${condition})
foreach(variable ${ARGN})
set(${variable} "${${variable}} ${value}" PARENT_SCOPE)
endforeach(variable)
endif()
endfunction()
# NDEBUG on non-Debug builds
append("-DNDEBUG" CMAKE_CXX_FLAGS_RELEASE
CMAKE_CXX_FLAGS_RELWITHDEBINFO
CMAKE_CXX_FLAGS_MINSIZEREL
CMAKE_C_FLAGS_RELEASE
CMAKE_C_FLAGS_RELWITHDEBINFO
CMAKE_C_FLAGS_MINSIZEREL)
# Assertions are always enabled on Debug builds, this is interesting for
# non-Debug builds.
if( NOT "${uppercase_CMAKE_BUILD_TYPE}" STREQUAL "DEBUG" AND ${ROSA_ENABLE_ASSERTIONS} )
# MSVC doesn't like _DEBUG on release builds. See PR 4379.
if( NOT MSVC )
add_definitions( -D_DEBUG )
set(ENABLE_ASSERTIONS "1")
else()
set(ENABLE_ASSERTIONS "0")
endif()
# On non-Debug builds we NDEBUG, but in this case we need to undefine it:
add_definitions(-UNDEBUG)
# Also remove /D NDEBUG to avoid MSVC warnings about conflicting defines.
foreach (flags_var_to_scrub
CMAKE_CXX_FLAGS_RELEASE
CMAKE_CXX_FLAGS_RELWITHDEBINFO
CMAKE_CXX_FLAGS_MINSIZEREL
CMAKE_C_FLAGS_RELEASE
CMAKE_C_FLAGS_RELWITHDEBINFO
CMAKE_C_FLAGS_MINSIZEREL)
string (REGEX REPLACE "(^| )[/-]D *NDEBUG($| )" " "
"${flags_var_to_scrub}" "${${flags_var_to_scrub}}")
endforeach()
endif()
set(ROSA_ENABLE_ASSERTIONS_INT -1)
if( "${uppercase_CMAKE_BUILD_TYPE}" STREQUAL "DEBUG" OR ${ROSA_ENABLE_ASSERTIONS} )
set(ROSA_ENABLE_ASSERTIONS_INT 1)
endif()
if( ROSA_COMPILER_IS_GCC_COMPATIBLE )
append("-Wall -Wextra -Wdocumentation -Werror" CMAKE_C_FLAGS CMAKE_CXX_FLAGS)
append_if(ROSA_ENABLE_PEDANTIC "-pedantic -Wno-long-long" CMAKE_C_FLAGS CMAKE_CXX_FLAGS)
append("-fno-rtti -fno-exceptions" CMAKE_CXX_FLAGS)
append("-Wno-c++1z-compat" CMAKE_CXX_FLAGS)
- check_cxx_compiler_flag("-std=c++14" CXX_SUPPORTS_CXX14)
- if ( CXX_SUPPORTS_CXX14 )
- append("-std=c++14" CMAKE_CXX_FLAGS)
+ check_cxx_compiler_flag("-std=c++17" CXX_SUPPORTS_CXX17)
+ if ( CXX_SUPPORTS_CXX17 )
+ append("-std=c++17" CMAKE_CXX_FLAGS)
else()
- message(FATAL_ERROR "RoSA requires C++14 support but the '-std=c++14' flag isn't supported.")
+ message(FATAL_ERROR "RoSA requires C++17 support but the '-std=c++17' flag isn't supported.")
endif()
check_c_compiler_flag("-std=c11" C_SUPPORTS_C11)
if ( C_SUPPORTS_C11 )
append("-std=c11" CMAKE_C_FLAGS)
else()
message(FATAL_ERROR "RoSA requires C11 support but the '-std=c11' flag isn't supported.")
endif()
elseif ( MSVC )
if (ROSA_COMPILER_IS_CLANG)
# Remove/adjsut incorrect flags that might be generated automatically.
foreach (flags_var_to_scrub
CMAKE_CXX_FLAGS
CMAKE_CXX_FLAGS_DEBUG
CMAKE_CXX_FLAGS_RELEASE
CMAKE_CXX_FLAGS_RELWITHDEBINFO
CMAKE_CXX_FLAGS_MINSIZEREL
CMAKE_C_FLAGS
CMAKE_C_FLAGS_DEBUG
CMAKE_C_FLAGS_RELEASE
CMAKE_C_FLAGS_RELWITHDEBINFO
CMAKE_C_FLAGS_MINSIZEREL)
string (REGEX REPLACE "(^| )-Wall($| )" " "
"${flags_var_to_scrub}" "${${flags_var_to_scrub}}")
string (REGEX REPLACE "(^| )-frtti($| )" " "
"${flags_var_to_scrub}" "${${flags_var_to_scrub}}")
string (REGEX REPLACE "(^| )-fexceptions($| )" " "
"${flags_var_to_scrub}" "${${flags_var_to_scrub}}")
string (REGEX REPLACE "(^| )-fno-inline($| )" " -Ob0 "
"${flags_var_to_scrub}" "${${flags_var_to_scrub}}")
string (REGEX REPLACE "(^| )-gline-tables-only($| )" " "
"${flags_var_to_scrub}" "${${flags_var_to_scrub}}")
message("${flags_var_to_scrub}: ${${flags_var_to_scrub}}")
endforeach()
endif()
# Flags matching GCC-compatible "-Wall -Wextra -Werror".
- append("/Wall /WX" CMAKE_C_FLAGS CMAKE_CXX_FLAGS)
+ # NOTE: Do not use -Wall for MSVC because it generates silly warning (e.g.,
+ # warnings about things in external libraries), use -W4 instead.
+ append("/W4 /WX" CMAKE_C_FLAGS CMAKE_CXX_FLAGS)
if ( ROSA_COMPILER_IS_CLANG )
# GCC-compatible flags without corresponding MSVC options.
append("-Wdocumentation" CMAKE_C_FLAGS CMAKE_CXX_FLAGS)
# The flag "-pedantic" is not in the MSVC flavour.
append_if(ROSA_ENABLE_PEDANTIC "-Wno-long-long" CMAKE_C_FLAGS CMAKE_CXX_FLAGS)
endif()
- # Flags matching GCC-compatible "-fno-rtti -fno-exceptions".
- append("/GR- /EHs-c-" CMAKE_CXX_FLAGS)
+ # Flags matching GCC-compatible "-fno-rtti".
+ append("/GR-" CMAKE_CXX_FLAGS)
+
+ # NOTE: We cannot disable unwind semantics (i.e., -fno-exceptions) for Windows
+ # libraries...
+ append("/EHsc" CMAKE_CXX_FLAGS)
if ( ROSA_COMPILER_IS_CLANG )
append("-Wno-c++1z-compat" CMAKE_CXX_FLAGS)
# MSVC puts there some garbage which needs to be ignored...
append("-Qunused-arguments" CMAKE_C_FLAGS CMAKE_CXX_FLAGS)
endif()
if ( ROSA_COMPILER_IS_CLANG )
- # Clang is surely a new version, must know about these flags.
- append("-Xclang -std=c++14" CMAKE_CXX_FLAGS)
- append("-Xclang -std=c11" CMAKE_C_FLAGS)
+
+ check_cxx_compiler_flag("-Xclang -std=c++17" CXX_SUPPORTS_CXX17)
+ if ( CXX_SUPPORTS_CXX17 )
+ append("-Xclang -std=c++17" CMAKE_CXX_FLAGS)
+ else()
+ message(FATAL_ERROR "RoSA requires C++17 support but the '-std=c++17' flag isn't supported.")
+ endif()
+
+ check_c_compiler_flag("-Xclang -std=c11" C_SUPPORTS_C11)
+ if ( C_SUPPORTS_C11 )
+ append("-Xclang -std=c11" CMAKE_C_FLAGS)
+ else()
+ message(FATAL_ERROR "RoSA requires C11 support but the '-std=c11' flag isn't supported.")
+ endif()
+
+ else ()
+
+ check_cxx_compiler_flag("/std:c++17 /permissive-" CXX_SUPPORTS_CXX17)
+ if ( CXX_SUPPORTS_CXX17 )
+ append("/std:c++17 /permissive-" CMAKE_CXX_FLAGS)
+ else()
+ message(FATAL_ERROR "RoSA requires C++17 support but the '/std:c++17 /permissive-' flags aren't supported.")
+ endif()
+
+ message(WARNING "RoSA is supposed to use C11 code in C files, which MSVC might not fully support.")
+
+ # Make MSVC ignore warning LNK4221 in libraries. The warning is caused by
+ # empty object files that correspond to the empty .cpp files, which we have
+ # for generating compile database entries for all header files.
+ append("/IGNORE:4221" CMAKE_STATIC_LINKER_FLAGS)
+
endif()
- # No need to select C/C++ standard otherwise?
endif()
if( ROSA_ENABLE_CLANG_TIDY )
# Set clang-tidy arguments, use the same for both C and CXX.
set(CMAKE_C_CLANG_TIDY "${CLANGTIDY_EXECUTABLE};-header-filter=.*")
set(CMAKE_CXX_CLANG_TIDY ${CMAKE_C_CLANG_TIDY})
# Apply suggested fixes if requested.
append_if(ROSA_CLANG_TIDY_FIX ",-fix" CMAKE_C_CLANG_TIDY CMAKE_CXX_CLANG_TIDY)
endif( ROSA_ENABLE_CLANG_TIDY )
diff --git a/docs/Build.rst b/docs/Build.rst
index 079af7d..6b84461 100755
--- a/docs/Build.rst
+++ b/docs/Build.rst
@@ -1,353 +1,318 @@
===========================
Building the RoSA Framework
===========================
.. contents::
:local:
+.. _build_deps:
+
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*.
+ compiler supporting *C++17*.
- * Clang/LLVM -- minimum version 3.9.0
- [#f-clang_template_argument_deduction_DeluxeAgent]_
+ * Clang/LLVM -- minimum version 5.0.0
+ * Visual Studio 2017 -- minimum version 15.7
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.
.. _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.
+This is how to use the native MSVC compiler to build RoSA.
-#. 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:
+Having your build system prepared (see `Build Dependencies`_) 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 be05ab6..4da5fb0 100755
--- a/docs/Dev.rst
+++ b/docs/Dev.rst
@@ -1,357 +1,359 @@
=============================
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
+RoSA is implemented in standard *C++17* code. All the software sources are to
be written in accordance to the `LLVM Coding Standards`_.
+.. _nortti-noexceptions:
+
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. 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 a0fd6bc..b3f6fd0 100755
--- a/docs/Issues.rst
+++ b/docs/Issues.rst
@@ -1,53 +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`_.
+The issues that are listed below are described assuming :ref:`minimal build
+dependencies ` are met.
* 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).
+ * The noexcept-specification is part of the function type since C++17 but
+ `std::function` is not defined for noexcept template arguments. So we cannot
+ enforce the expected noexcept semantics for functions stored in
+ `std::function`. See affected functions
+ `rosa::Invoker::wrap()`, `rosa::deluxe::DeluxeAgent::DeluxeAgent()`,
+ `rosa::deluxe::DeluxeSensor::DeluxeSensor()`, and
+ `rosa::deluxe::DeluxeSensor::registerSimulationDataSource()`.
+
+* MSVC
- * 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.
+ * While :ref:`RoSA does not use exceptions `, we cannot
+ disable unwind semantics with MSVC because some included header files define
+ functions that use exceptions.
* 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/examples/agent-modules/agent-modules.cpp b/examples/agent-modules/agent-modules.cpp
index 04fce75..c559136 100644
--- a/examples/agent-modules/agent-modules.cpp
+++ b/examples/agent-modules/agent-modules.cpp
@@ -1,108 +1,108 @@
//===-- examples/agent-modules/agent-modules.cpp ----------------*- C++ -*-===//
//
// The RoSA Framework
//
//===----------------------------------------------------------------------===//
///
/// \file examples/agent-modules/agent-modules.cpp
///
/// \author David Juhasz (david.juhasz@tuwien.ac.at)
///
/// \date 2017
///
/// \brief A simple example on defining \c rosa::Agent instances using
/// \c rosa::agent::Module object as components.
///
//===----------------------------------------------------------------------===//
#include "rosa/agent/Abstraction.hpp"
#include "rosa/agent/Confidence.hpp"
#include "rosa/config/version.h"
#include "rosa/core/Agent.hpp"
#include "rosa/core/MessagingSystem.hpp"
#include "rosa/support/log.h"
#include "rosa/support/terminal_colors.h"
#include
using namespace rosa;
using namespace rosa::agent;
using namespace rosa::terminal;
/// A dummy wrapper for testing \c rosa::MessagingSystem.
///
/// \note Since we test \c rosa::MessagingSystem directly here, we need to get
/// access to its protected members. That we do by imitating to be a decent
/// subclass of \c rosa::MessagingSystem, while calling protected member
/// functions on an object of a type from which we actually don't inherit.
struct SystemTester : protected MessagingSystem {
template
static AgentHandle createMyAgent(MessagingSystem *S, const std::string &Name,
Funs &&... Fs) {
return ((SystemTester *)S)->createAgent(Name, std::move(Fs)...);
}
static void destroyMyAgent(MessagingSystem *S, const AgentHandle &H) {
((SystemTester *)S)->destroyUnit(unwrapAgent(H));
}
};
/// A special \c rosa::Agent with its own state.
class MyAgent : public Agent {
public:
using Tick = AtomConstant;
private:
enum class Categories { Bad, Normal, Good };
static const std::map CategoryNames;
History H;
Confidence C;
RangeAbstraction A;
public:
void handler(Tick, uint8_t V) noexcept {
// Record \p V to the \c rosa::agent::History, then print state info.
H << V;
ASSERT(H.entry() == V); // Sanity check.
LOG_INFO_STREAM << "\nNext value: " << PRINTABLE(V)
<< ", confidence: " << C(H)
<< ", category: " << CategoryNames.at(A(H.entry())) << '\n';
}
MyAgent(const AtomValue Kind, const rosa::id_t Id, const std::string &Name,
MessagingSystem &S)
: Agent(Kind, Id, Name, S, THISMEMBER(handler)), H(), C(5, 20, 1),
- A({{{10, 14}, Categories::Normal},
- {{15, 17}, Categories::Good},
- {{18, 19}, Categories::Normal}},
+ A({{{(uint8_t)10, (uint8_t)14}, Categories::Normal},
+ {{(uint8_t)15, (uint8_t)17}, Categories::Good},
+ {{(uint8_t)18, (uint8_t)19}, Categories::Normal}},
Categories::Bad) {}
};
const std::map MyAgent::CategoryNames{
{Categories::Bad, "Bad"},
{Categories::Normal, "Normal"},
{Categories::Good, "Good"}};
int main(void) {
LOG_INFO_STREAM << library_string() << " -- " << Color::Red
<< "agent-modules example" << Color::Default << '\n';
std::unique_ptr S = MessagingSystem::createSystem("Sys");
MessagingSystem *SP = S.get();
AgentHandle A = SystemTester::createMyAgent(SP, "MyAgent");
std::vector Vs{4, 5, 6, 7, 9, 10, 11, 13,
15, 14, 15, 16, 19, 20, 21};
for (auto I = Vs.begin(); I != Vs.end(); ++I) {
A.send(MyAgent::Tick::Value, *I);
}
SystemTester::destroyMyAgent(SP, A);
return 0;
}
diff --git a/examples/deluxe-interface/deluxe-interface.cpp b/examples/deluxe-interface/deluxe-interface.cpp
index 6f3b8e2..5e569ba 100755
--- a/examples/deluxe-interface/deluxe-interface.cpp
+++ b/examples/deluxe-interface/deluxe-interface.cpp
@@ -1,312 +1,312 @@
//===-- examples/deluxe-interface/deluxe-interface.cpp ----------*- C++ -*-===//
//
// The RoSA Framework
//
//===----------------------------------------------------------------------===//
///
/// \file examples/deluxe-interface/deluxe-interface.cpp
///
/// \author David Juhasz (david.juhasz@tuwien.ac.at)
///
/// \date 2017
///
/// \brief A simple example on the \c rosa::deluxe::DeluxeContext and related
/// classes.
//===----------------------------------------------------------------------===//
#include "rosa/agent/Abstraction.hpp"
#include "rosa/agent/Confidence.hpp"
#include "rosa/config/version.h"
#include "rosa/deluxe/DeluxeContext.hpp"
#include "rosa/support/csv/CSVReader.hpp"
#include "rosa/support/csv/CSVWriter.hpp"
#include
using namespace rosa;
using namespace rosa::agent;
using namespace rosa::deluxe;
using namespace rosa::terminal;
/// Paths for the CSV files for simulation.
///
///@{
const std::string HRCSVPath = "HR.csv";
const std::string BRCSVPath = "BR.csv";
const std::string SpO2CSVPath = "SpO2.csv";
const std::string BPSysCSVPath = "BPSys.csv";
const std::string BodyTempCSVPath = "BodyTemp.csv";
const std::string ScoreCSVPath = "Score.csv";
///@}
/// How many cycles of simulation to perform.
const size_t NumberOfSimulationCycles = 16;
/// Warning levels for abstraction.
enum WarningScore { No = 0, Low = 1, High = 2, Emergency = 3 };
/// Helper function creating a deluxe agent for pre-processing sensory values.
///
/// Received values are first validated for confidence. Values which the
/// validator does not mark confident are ignored. Confident values are
/// abstracted into a \c WarningScore value, which is the result of the
/// processing function.
///
/// \note The result, \c WarningScore, is returned as \c uint32_t because
/// enumeration types are not integrated into built-in types. Hence, a master
/// to these agents receives its input as \c uint32_t values, and may cast them
/// to \c WarningScore explicitly.
///
/// \tparam T type of values to receive from the sensor
///
/// \param C the deluxe context to create the agent in
/// \param Name name of the new agent
/// \param CC confidence validator to use
/// \param A abstraction to use
///
/// \return handle for the new agent
template
AgentHandle createLowLevelAgent(std::unique_ptr &C,
const std::string &Name,
const Confidence &CC,
const Abstraction &A) {
using handler = DeluxeAgent::D;
using result = Optional;
return C->createAgent(
Name, handler([&, Name](std::pair I) -> result {
LOG_INFO_STREAM << "\n******\n"
<< Name << " " << (I.second ? "" : "")
<< " value: " << I.first << "\n******\n";
return (I.second && CC(I.first)) ? result(A(I.first)) : result();
}));
}
int main(void) {
LOG_INFO_STREAM
<< '\n'
<< library_string() << " -- " << Color::Red << "deluxe-interface example"
<< Color::Default << '\n'
<< Color::Yellow
<< "CSV files are read from and written to the current working directory."
<< Color::Default << '\n';
std::unique_ptr C = DeluxeContext::create("Deluxe");
//
// Create deluxe sensors.
//
LOG_INFO("Creating sensors.");
// All sensors are created without defining a normal generator function, but
// with the default value of the second argument. That, however, requires the
// data type to be explicitly defined. This is good for simulation only.
AgentHandle HRSensor = C->createSensor("HR Sensor");
AgentHandle BRSensor = C->createSensor("BR Sensor");
AgentHandle SpO2Sensor = C->createSensor("SpO2 Sensor");
AgentHandle BPSysSensor = C->createSensor("BPSys Sensor");
AgentHandle BodyTempSensor = C->createSensor("BodyTemp Sensor");
//
// Create functionalities.
//
LOG_INFO("Creating Functionalities for Agents.");
//
// Define confidence validators.
//
// Lower bounds are inclusive and upper bounds are exclusive.
Confidence HRConfidence(0, 501);
Confidence BRConfidence(0, 301);
Confidence SpO2Confidence(0, 101);
Confidence BPSysConfidence(0,501);
Confidence BodyTempConfidence(-60,
nextRepresentableFloatingPoint(50.0f));
//
// Define abstractions.
//
RangeAbstraction HRAbstraction(
{{{0, 40}, Emergency},
{{40, 51}, High},
{{51, 60}, Low},
{{60, 100}, No},
{{100, 110}, Low},
{{110, 129}, High},
{{129, 200}, Emergency}},
Emergency);
RangeAbstraction BRAbstraction({{{0, 9}, High},
{{9, 14}, No},
{{14, 20}, Low},
{{20, 29}, High},
{{29, 50}, Emergency}},
Emergency);
RangeAbstraction SpO2Abstraction({{{1, 85}, Emergency},
{{85, 90}, High},
{{90, 95}, Low},
{{95, 100}, No}},
Emergency);
RangeAbstraction BPSysAbstraction(
{{{0, 70}, Emergency},
{{70, 81}, High},
{{81, 101}, Low},
{{101, 149}, No},
{{149, 169}, Low},
{{169, 179}, High},
{{179, 200}, Emergency}},
Emergency);
RangeAbstraction BodyTempAbstraction(
- {{{0, 28}, Emergency},
- {{28, 32}, High},
- {{32, 35}, Low},
- {{35, 38}, No},
- {{38, 39.5}, High},
- {{39.5, 100}, Emergency}},
+ {{{0.f, 28.f}, Emergency},
+ {{28.f, 32.f}, High},
+ {{32.f, 35.f}, Low},
+ {{35.f, 38.f}, No},
+ {{38.f, 39.5f}, High},
+ {{39.5f, 100.f}, Emergency}},
Emergency);
//
// Create low-level deluxe agents with \c createLowLevelAgent.
//
LOG_INFO("Creating low-level agents.");
AgentHandle HRAgent =
createLowLevelAgent(C, "HR Agent", HRConfidence, HRAbstraction);
AgentHandle BRAgent =
createLowLevelAgent(C, "BR Agent", BRConfidence, BRAbstraction);
AgentHandle SpO2Agent =
createLowLevelAgent(C, "SpO2 Agent", SpO2Confidence, SpO2Abstraction);
AgentHandle BPSysAgent =
createLowLevelAgent(C, "BPSys Agent", BPSysConfidence, BPSysAbstraction);
AgentHandle BodyTempAgent = createLowLevelAgent(
C, "BodyTemp Agent", BodyTempConfidence, BodyTempAbstraction);
//
// Connect sensors to low-level agents.
//
LOG_INFO("Connect sensors to their corresponding low-level agents.");
C->connectSensor(HRAgent, 0, HRSensor, "HR Sensor Channel");
C->connectSensor(BRAgent, 0, BRSensor, "BR Sensor Channel");
C->connectSensor(SpO2Agent, 0, SpO2Sensor, "SpO2 Sensor Channel");
C->connectSensor(BPSysAgent, 0, BPSysSensor, "BPSys Sensor Channel");
C->connectSensor(BodyTempAgent, 0, BodyTempSensor, "BodyTemp Sensor Channel");
//
// Create a high-level deluxe agent.
//
LOG_INFO("Create high-level agent.");
// The new agent logs its input values and results in the the sum of them.
AgentHandle BodyAgent = C->createAgent(
"Body Agent",
DeluxeAgent::D(
[](std::pair HR, std::pair BR,
std::pair SpO2, std::pair BPSys,
std::pair BodyTemp) -> Optional {
LOG_INFO_STREAM << "\n*******\nBody Agent trigged with values:\n"
<< (HR.second ? "" : "")
<< " HR warning score: " << HR.first << "\n"
<< (BR.second ? "" : "")
<< " BR warning score: " << BR.first << "\n"
<< (SpO2.second ? "" : "")
<< " SpO2 warning score: " << SpO2.first << "\n"
<< (BPSys.second ? "" : "")
<< " BPSys warning score: " << BPSys.first << "\n"
<< (BodyTemp.second ? "" : "")
<< " BodyTemp warning score: " << BodyTemp.first
<< "\n******\n";
return {HR.first + BR.first + SpO2.first + BPSys.first +
BodyTemp.first};
}));
//
// Connect low-level agents to the high-level agent.
//
LOG_INFO("Connect low-level agents to the high-level agent.");
C->connectAgents(BodyAgent, 0, HRAgent, "HR Agent Channel");
C->connectAgents(BodyAgent, 1, BRAgent, "BR Agent Channel");
C->connectAgents(BodyAgent, 2, SpO2Agent, "SpO2 Agent Channel");
C->connectAgents(BodyAgent, 3, BPSysAgent, "BPSys Agent Channel");
C->connectAgents(BodyAgent, 4, BodyTempAgent, "BodyTemp Agent Channel");
//
// For simulation output, create a logger agent writing the output of the
// high-level agent into a CSV file.
//
LOG_INFO("Create a logger agent.");
// Create CSV writer.
std::ofstream ScoreCSV(ScoreCSVPath);
csv::CSVWriter ScoreWriter(ScoreCSV);
// The agent writes each new input value into a CSV file and produces nothing.
AgentHandle LoggerAgent = C->createAgent(
"Logger Agent",
DeluxeAgent::D(
[&ScoreWriter](std::pair Score) -> Optional {
if (Score.second) {
// The state of \p ScoreWriter is not checked, expecting good.
ScoreWriter << Score.first;
}
return {};
}));
//
// Connect the high-level agent to the logger agent.
//
LOG_INFO("Connect the high-level agent to the logger agent.");
C->connectAgents(LoggerAgent, 0, BodyAgent, "Body Agent Channel");
//
// Do simulation.
//
LOG_INFO("Setting up and performing simulation.");
//
// Initialize deluxe context for simulation.
//
C->initializeSimulation();
//
// Open CSV files and register them for their corresponding sensors.
//
// Type aliases for iterators.
using CSVInt = csv::CSVFlatIterator;
using CSVFloat = csv::CSVFlatIterator;
std::ifstream HRCSV(HRCSVPath);
C->registerSensorValues(HRSensor, CSVInt(HRCSV), CSVInt());
std::ifstream BRCSV(BRCSVPath);
C->registerSensorValues(BRSensor, CSVInt(BRCSV), CSVInt());
std::ifstream SpO2CSV(SpO2CSVPath);
C->registerSensorValues(SpO2Sensor, CSVInt(SpO2CSV), CSVInt());
std::ifstream BPSysCSV(BPSysCSVPath);
C->registerSensorValues(BPSysSensor, CSVInt(BPSysCSV), CSVInt());
std::ifstream BodyTempCSV(BodyTempCSVPath);
C->registerSensorValues(BodyTempSensor, CSVFloat(BodyTempCSV), CSVFloat());
//
// Simulate.
//
C->simulate(NumberOfSimulationCycles);
return 0;
}
diff --git a/include/rosa/agent/History.hpp b/include/rosa/agent/History.hpp
index b6d3877..1097ad0 100644
--- a/include/rosa/agent/History.hpp
+++ b/include/rosa/agent/History.hpp
@@ -1,292 +1,292 @@
//===-- rosa/agent/History.hpp ----------------------------------*- C++ -*-===//
//
// The RoSA Framework
//
//===----------------------------------------------------------------------===//
///
/// \file rosa/agent/History.hpp
///
/// \author David Juhasz (david.juhasz@tuwien.ac.at)
///
/// \date 2017
///
/// \brief Definition of *history* *functionality*.
///
//===----------------------------------------------------------------------===//
#ifndef ROSA_AGENT_HISTORY_HPP
#define ROSA_AGENT_HISTORY_HPP
#include "rosa/agent/Functionality.h"
#include "rosa/config/config.h"
#include "rosa/support/debug.hpp"
#include "rosa/support/type_helper.hpp"
#include
namespace rosa {
namespace agent {
/// Retention policies defining what a \c rosa::agent::History instance should
/// do when the number of recorded entries reached its capacity.
enum class HistoryPolicy {
SRWF, ///< Stop Recording When Full -- no new entry is recorded when full
FIFO ///< First In First Out -- overwrite the earliest entry with a new one
};
/// Implements *history* by recording and storing values.
///
/// \note Not thread-safe implementation, which should not be a problem as any
/// instance of \c rosa::agent::Functionality is an internal component of a
/// \c rosa::Agent, which is the basic unit of concurrency.
///
/// \tparam T type of values to store
/// \tparam N number of values to store at most
/// \tparam P retention policy to follow when capacity is reached
///
/// \invariant The size of the underlying \c std::array is `N + 1`:\code
/// max_size() == N + 1 && N == max_size() - 1
/// \endcode
template
class History : public Functionality, private std::array {
// Bring into scope inherited functions that are used.
using std::array::max_size;
using std::array::operator[];
/// The index of the first data element in the circular buffer.
size_t Data;
/// The index of the first empty slot in the circular buffer.
size_t Space;
public:
/// Creates an instances by initializing the indices for the circular buffer.
History(void) noexcept : Data(0), Space(0) {}
/// Destroys \p this object.
~History(void) = default;
/// Tells the retention policy applied to \p this object.
///
/// \return \c rosa::agent::History::P
static constexpr HistoryPolicy policyOfHistory(void) noexcept { return P; }
/// Tells how many entries may be recorded by \c this object.
///
/// \note The number of entries that are actually recorded may be smaller.
///
/// \return \c rosa::agent::History::N
static constexpr size_t lengthOfHistory(void) noexcept { return N; }
/// Tells how many entries are currently recorded by \p this object.
///
/// \return number of entries currently recorded by \p this object.
///
/// \post The returned value cannot be larger than the capacity of \p this
/// object:\code
/// 0 <= numberOfEntries() && numberOfEntries <= lengthOfHistory()
/// \endcode
size_t numberOfEntries(void) const noexcept {
return Data <= Space ? Space - Data : max_size() - Data + Space;
}
/// Tells if \p this object has not recorded anything yet.
///
/// \return if \p this object has no entries recorded
bool empty(void) const noexcept { return numberOfEntries() == 0; }
/// Gives a constant lvalue reference to an entry stored in \p this object.
///
/// \note The recorded entries are indexed starting from the latest one.
///
/// \param I the index at which the stored entry to take from
///
/// \pre \p I is a valid index:\code
/// 0 <= I && I <= numberOfEntries()
/// \endcode
const T &entry(const size_t I = 0) const noexcept {
ASSERT(0 <= I && I < numberOfEntries()); // Boundary check.
// Position counted back from the last recorded entry.
typename std::make_signed::type Pos = Space - (1 + I);
// Actual index wrapped around to the end of the buffer if negative.
return (*this)[Pos >= 0 ? Pos : max_size() + Pos];
}
private:
/// Tells if the circular buffer is full.
///
/// \return if the circular buffer is full.
bool full(void) const noexcept { return numberOfEntries() == N; }
/// Pushes a new entry into the circular buffer.
///
/// \note The earliest entry gets overwritten if the buffer is full.
///
/// \param V value to push into the buffer
void pushBack(const T &V) noexcept {
// Store value to the first empty slot and step Space index.
(*this)[Space] = V;
Space = (Space + 1) % max_size();
if (Data == Space) {
// Buffer was full, step Data index.
Data = (Data + 1) % max_size();
}
}
public:
/// Adds a new entry to \p this object and tells if the operation was
/// successful.
///
/// \note Success of the operation depends on the actual policy.
///
/// \param V value to store
///
/// \return if \p V was successfully stored
bool addEntry(const T &V) noexcept {
switch (P) {
default:
ROSA_CRITICAL("unkown HistoryPolicy");
case HistoryPolicy::SRWF:
if (full()) {
return false;
}
// \note Fall through to FIFO which unconditionally pushes the new entry.
case HistoryPolicy::FIFO:
// FIFO and SRWF not full.
pushBack(V);
return true;
}
}
/// Tells the trend set by the entries recorded by \p this object.
///
/// The number of steps to go back when calculating the trend is defined as
/// argument to the function.
///
/// \note The number of steps that can be made is limited by the number of
/// entries recorded by \p this object.
///
/// \note The function is made a template only to be able to use
/// \c std::enable_if.
///
/// \tparam X always use the default!
///
/// \param D number of steps to go back in *history*
///
/// \return trend set by analyzed entries
///
/// \pre Statically, \p this object stores signed arithmetic values:\code
/// std::is_arithmetic::value && std::is_signed::value
/// \endcode Dynamically, \p D is a valid number of steps to take:\code
/// 0 <= D && D < N
/// \endcode
template
typename std::enable_if<
std::is_arithmetic::value && std::is_signed::value, X>::type
trend(const size_t D = N - 1) const noexcept {
STATIC_ASSERT((std::is_same::value), "not default template arg");
ASSERT(0 <= D && D < N); // Boundary check.
if (numberOfEntries() < 2 || D < 1) {
// No entries for computing trend.
return {}; // Zero element of \p T
} else {
// Here at least two entries.
// \c S is the number of steps that can be done.
const size_t S = std::min(numberOfEntries() - 1, D);
size_t I = S;
// Compute trend with linear regression.
size_t SumIndices = 0;
T SumEntries = {};
T SumSquareEntries = {};
T SumProduct = {};
while (I > 0) {
// \note Indexing for the regression starts in the past.
const size_t Index = S - I;
const T Entry = entry(--I);
SumIndices += Index;
SumEntries += Entry;
SumSquareEntries += Entry * Entry;
SumProduct += Entry * Index;
}
return (SumProduct * S - SumEntries * SumIndices) /
(SumSquareEntries * S - SumEntries * SumEntries);
}
}
- /// Tells the average absolute difference between consequtive entries recorded
+ /// Tells the average absolute difference between consecutive entries recorded
/// by \p this object
/// The number of steps to go back when calculating the average is defined as
/// argument to the function.
///
/// \note The number of steps that can be made is limited by the number of
/// entries recorded by \p this object.
///
/// \note The function is made a template only to be able to use
/// \c std::enable_if.
///
/// \tparam X always use the default!
///
/// \param D number of steps to go back in *history*
///
/// \pre Statically, \p this object stores arithmetic values:\code
/// std::is_arithmetic::value
/// \endcode Dynamically, \p D is a valid number of steps to take:\code
/// 0 <= D && D < N
/// \endcode
template
- typename std::enable_if::value, unsigned_t>::type
+ typename std::enable_if::value, size_t>::type
averageAbsDiff(const size_t D = N - 1) const noexcept {
STATIC_ASSERT((std::is_same::value), "not default template arg");
ASSERT(0 <= D && D < N); // Boundary check.
if (numberOfEntries() < 2 || D < 1) {
// No difference to average.
return {}; // Zero element of \p T
} else {
// Here at least two entries.
// \c S is the number of steps that can be done.
const size_t S = std::min(numberOfEntries() - 1, D);
// Sum up differences as non-negative values only, hence using an
// unsigned variable for that.
- unsigned_t Diffs = {}; // Init to zero.
+ size_t Diffs = {}; // Init to zero.
// Count down entry indices and sum up all the absolute differences.
size_t I = S;
T Last = entry(I);
while (I > 0) {
T Next = entry(--I);
Diffs += Last < Next ? Next - Last : Last - Next;
Last = Next;
}
// Return the average of the summed differences.
return Diffs / S;
}
}
};
/// Adds a new entry to a \c rosa::agent::History instance.
///
/// \note The result of \c rosa::agent::History::addEntry is ignored.
///
/// \tparam T type of values stored in \p H
/// \tparam N number of values \p H is able to store
/// \tparam P retention policy followed by \p H when capacity is reached
///
/// \param H to add a new entry to
/// \param V value to add to \p H
///
/// \return \p H after adding \p V to it
template
History &operator<<(History &H, const T &V) noexcept {
H.addEntry(V);
return H;
}
} // End namespace agent
} // End namespace rosa
#endif // ROSA_AGENT_HISTORY_HPP
diff --git a/include/rosa/core/Invoker.hpp b/include/rosa/core/Invoker.hpp
index 32126ad..9f35ca3 100644
--- a/include/rosa/core/Invoker.hpp
+++ b/include/rosa/core/Invoker.hpp
@@ -1,256 +1,258 @@
//===-- rosa/core/Invoker.hpp -----------------------------------*- C++ -*-===//
//
// The RoSA Framework
//
//===----------------------------------------------------------------------===//
///
/// \file rosa/core/Invoker.hpp
///
/// \author David Juhasz (david.juhasz@tuwien.ac.at)
///
-/// \date 2017
+/// \date 2017-2019
///
/// \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.
///
+ /// \todo Enforce F does not potentially throw exception.
+ ///
/// \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;
+ 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;
+ 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 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.
+/// \c std::function.
template
-class InvokerImpl> final
+class InvokerImpl> final
: public Invoker {
/// Type alias for the stored function.
- using function_t = std::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(
+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 {
+Invoker::wrap(std::function &&F) noexcept {
return std::unique_ptr(
- new InvokerImpl>(std::move(F)));
+ 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/System.hpp b/include/rosa/core/System.hpp
index 7a5488d..b9869bc 100644
--- a/include/rosa/core/System.hpp
+++ b/include/rosa/core/System.hpp
@@ -1,240 +1,242 @@
//===-- rosa/core/System.hpp ------------------------------------*- C++ -*-===//
//
// The RoSA Framework
//
//===----------------------------------------------------------------------===//
///
/// \file rosa/core/System.hpp
///
/// \author David Juhasz (david.juhasz@tuwien.ac.at)
///
-/// \date 2017
+/// \date 2017-2019
///
/// \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.
///
+ /// \note The function is to be \c noexcept.
+ ///
/// \tparam T type derived from \c rosa::Unit
/// \tparam S type derived from \c rosa::System
template
- using UnitCreator = std::function;
+ 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()
/// \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
/// std::is_base_of::value && std::is_base_of::value
/// \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/deluxe/DeluxeAgent.hpp b/include/rosa/deluxe/DeluxeAgent.hpp
index 720576f..0e83a7c 100755
--- a/include/rosa/deluxe/DeluxeAgent.hpp
+++ b/include/rosa/deluxe/DeluxeAgent.hpp
@@ -1,680 +1,673 @@
//===-- rosa/deluxe/DeluxeAgent.hpp -----------------------------*- C++ -*-===//
//
// The RoSA Framework
//
//===----------------------------------------------------------------------===//
///
/// \file rosa/deluxe/DeluxeAgent.hpp
///
/// \author David Juhasz (david.juhasz@tuwien.ac.at)
///
-/// \date 2017
+/// \date 2017-2019
///
/// \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