diff --git a/docs/Design.rst b/docs/Design.rst new file mode 100644 index 0000000..4f07a0f --- /dev/null +++ b/docs/Design.rst @@ -0,0 +1,119 @@ +=============== +Design Overview +=============== + +Last updated: 2019-11-27 + +TODO: + +- Add cross references to relevant parts of the documentation and external links (e.g., relevant papers or source of info) + +.. contents:: + :local: + + +Principles +========== + +The main priorities for the design of the software implementation are + +#. providing a high-level, easy-to-use but safe interface for application developers; +#. allowing the same application code to be used for *simulation* and *deployment*; +#. realizing small-footprint software that can be deployed in resource-constrained embedded devices. + +The RoSA software framework, is implemented in C++. +The language allows defining high-level but lightweight interfaces with flexibility in the realization. +The framework heavily utilizes templates, template metaprogramming, and constant expressions to let the compiler generate optimized code. +We also encode dynamically-relevant static information into a custom format so that RoSA supports message passing with flexibility and minimal resource need --- without the dynamic overhead of C++ RTTI. + +Performing message passing and data manipulation is decoupled from the agent interface. +The implementation of the runtime system is easily switched behind the declarative definition of agent-based applications. +Running an application in different modes (e.g., simulation and deployment) is a matter of static configuration. + +Simulation is the execution of the application on a computer with sensor and actuator agents associated to input and output streams, respectively. +Those sensor and actuator agents may interface actual sensors and actuators with custom C++ code when deployed in an embedded device. + +Case studies have been dony in simulation; support for deployment requires further development effort to complete the corresponding runtime implementation. + +The framework is being coded in standard C++. +The only exceptions are some OS-specific code snippets within debugging and simulation facilities. +The software can readily be deployed to all devices that are supported by a modern C++ compiler. + +Software Modules +================ + +The software implementation consists of four main modules: + +`Support` + provides general debugging, logging, typing, and I/O facilities, which are used in other modules and application code. + +`Agent` + is a library of self-aware functionalities for defining agents in application code. + +`Core` + defines a minimal agent system with message passing capabilities and runtime system implementations. + +`Deluxe` + provides an interface that matches the RoSA Architecture and utilizes RoSA Core. + + +The RoSA Deluxe interface wraps the general agent interface of RoSA Core. +RoSA Deluxe agents are defined by functions that take their input messages as parameters and provide their output messages as return values. +The implementation takes care of handling messages --- minimizing boilerplate in application code --- and may perform static and dynamic checks to ensure operating conditions. + +Agents and Agent Systems +------------------------ + +RoSA Core defines the means for agents to receive and send messages. +Messages are statically-typed tuples of basic types. +An agent is defined as a list of message handler functions. +An incoming message is handled by the first handler that can take the message as actual parameter. +The handler may generate output messages via RoSA API calls. + +RoSA Deluxe agents build on RoSA Core agents and provide a higher abstraction level by hiding message passing. + +Each agent is owned by a *system*. +Systems can instantiate agents and provide the actual implementation for execution: channels --- for message passing --- and control --- for triggering data manipulation. + +RoSA Core allows message passing between arbitrary agents within a system. +The RoSA Deluxe interface enforces a hierarchical structure with master-slave relations. + + +A RoSA application is an agent system. +The Deluxe module allows implementing a system as a set of agent definitions and declarative description of their connections. + +Execution Model +--------------- + +How an application (i.e., agent system) is executed depends on the system implementation. +The implementation of the system --- channel and control facilities --- is decoupled from the definition of an application --- agents and their connections within a system. +RoSA Core allows swapping the system implementation for any application as a configuration option or by changing one line of application code. + +The current system implementation is based on Models of Computations (MoCs). +We use the untimed MoC and are prepared for the discrete-timed MoC when time aspects have to be represented. +The concepts of the agent-based approach are easily mapped to the formal MoCs. + +=================== =========== +Agent-based concept MoC concept +=================== =========== +Agent Process +Channel Signal +Message Event +=================== =========== + +A RoSA agent system --- mapping to a process network --- can be analysed in the formal model. + + +Building and Running Applications +--------------------------------- + +RoSA has a CMake build project, which allows using the framework in different development environments. +The build project defines compile-time options to disable or tune features statically (e.g., logging, debugging, and tracing facilities). +Disabling unnecessary features improves the efficiency of compiled framework code in particular uses. +A RoSA application and framework modules are linked into one executable, which allows exploiting link-time optimization possibilities (optimizing framework code for application need, removing unused framework code, etc.). + + +The RoSA runtime system is a thin layer between the self-aware application and the underlying system; still it fulfills important responsibilities. +The runtime system initializes the application by instantiating an agent system, performs message passing, and triggers data manipulation in agents. +I/O and monitoring features are also provided by RoSA. +The application code is not bloated with system-level bookkeeping and developers can focus on details of self-awareness. diff --git a/docs/index.rst b/docs/index.rst index e42d88a..cf61d5a 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,83 +1,86 @@ ================== The RoSA Framework ================== .. contents:: :local: Overview ======== The RoSA (Research on Self-Awareness) Framework is intended to be used as a tool for experimenting and evaluating new ways of implementing self-aware applications. This documentation was generated for RoSA version |release| on |today|. Documentation ============= .. toctree:: :hidden: - Changelog + Design Use Build Dev Issues Release Plan CommandGuide/index +:doc:`Design` + General overview of design principles and decisions. + :doc:`Use` Describes how to create your own software based on RoSA. :doc:`Build` Describes how to build RoSA. :doc:`Dev` Provides basic information for developers on how to contribute to RoSA. :doc:`Issues` Known issues and things to do with the current implementation of RoSA. :doc:`Release` Describes for maintainers how to make a new release of RoSA. :doc:`Plan` Discusses future work and possible ways to develop RoSA. :doc:`CommandGuide/index` Documentation for RoSA applications and tools. Changes ======= Refer to :doc:`Changelog`. .. _API_Documentation: API Documentation ================= For details of the provided interface, refer to our `API documentation`_. .. _API documentation: ../doxygen/html/index.html License ======= RoSA is distributed under the terms and conditions of the `Boost Software License 1.0 `_: .. literalinclude:: ../LICENSE :language: none .. note:: 3rd party externals in the directory `modules` are not part of the RoSA source base and are licensed separately. Indices and Tables ================== * :ref:`genindex` * :ref:`search`