Page MenuHomePhorge
Files F1497269

AppExecutionPolicy.h
No OneTemporary
Actions

Size
7 KB
Referenced Files
None
Subscribers
None

AppExecutionPolicy.h
View Options

//===-- rosa/app/AppExecutionPolicy.h ---------------------------*- C++ -*-===//
//
// The RoSA Framework
//
// Distributed under the terms and conditions of the Boost Software License 1.0.
// See accompanying file LICENSE.
//
// If you did not receive a copy of the license file, see
// http://www.boost.org/LICENSE_1_0.txt.
//
//===----------------------------------------------------------------------===//
///
/// \file rosa/app/AppExecutionPolicy.h
///
/// \author David Juhasz (david.juhasz@tuwien.ac.at)
///
/// \date 2019-2020
///
/// \brief Public interface of *execution policies* in the *application
/// interface*.
///
//===----------------------------------------------------------------------===//
#ifndef ROSA_APP_APPEXECUTIONPOLICY_H
#define ROSA_APP_APPEXECUTIONPOLICY_H
#include "rosa/core/AgentHandle.hpp"
#include <memory>
#include <ostream>
#include <set>
#include <vector>
namespace rosa {
namespace app {
// Forward declaration of AppSystem. Do not include the corresponding header
// in this file because of cyclic dependency.
class AppSystem;
/// *Execution policy* that controls how *agents* and *sensors* call their
/// processing functions.
///
/// An *execution policy* can be applied to a application *unit* only if \c
/// rosa::app::AppExecutionPolicy::canHandle() allows it. Each application
/// *unit* must have a compatible *execution policy* associated to it, and the
/// *unit* queries \c rosa::app::AppExecutionPolicy::shouldProcess() on each
/// triggering and calls its processing funtion only if it is allowed by the
/// *execution policy*.
///
/// \see rosa::app::AppExecutionPolicy::decimation()
/// \see rosa::app::AppExecutionPolicy::awaitAll()
/// \see rosa::app::AppExecutionPolicy::awaitAny()
///
/// \todo Extend the interface with query functions about what kind of
/// execution policy is behind the interface. This can be done in relation
/// to the existing factory functions; for example, if the actual object is
/// decimation and with what rate.
class AppExecutionPolicy {
protected:
/// Protected constructor, only implementations can instantiate the class.
AppExecutionPolicy(void) noexcept = default;
private:
/// No instance can be copy-constructed, move-constructed, copied, and moved.
///
///@{
AppExecutionPolicy(const AppExecutionPolicy &) = delete;
AppExecutionPolicy(AppExecutionPolicy &&) = delete;
AppExecutionPolicy &operator=(const AppExecutionPolicy &) = delete;
AppExecutionPolicy &operator=(AppExecutionPolicy &&) = delete;
///@}
public:
/// Virtual destructor for subclasses.
virtual ~AppExecutionPolicy(void) noexcept = default;
/// Creates an *execution policy* that allows execution with decimation of
/// triggering.
///
//// *Decimation* can handle both *agents* and *sensors*.
/// Processing functions are executed only on every \p D <sup>th</sup>
/// triggering. In the case of *sensors* in simulation, the simulation data
/// source is read on each triggering as it provides values with respect to
/// the highest execution frequency, but output is generated by the *sensor*
/// only on every \p D <sup>th</sup> triggering.
///
/// \note A rate of \c 0 is allowed as actual argument and is treated as rate
/// \c 1 (i.e., execute processing functions on each triggering).
///
/// \param D the rate of *decimation*
///
/// \return an *execution policy* implementing *decimation* with rate \p D
static std::unique_ptr<AppExecutionPolicy> decimation(const size_t D);
/// Creates an *execution policy* that allows execution only if all defined
/// *slave* positions has new input.
///
/// *Await all* can handle only *agents* and only if the particular *agent*
/// has at least as many *slave* positions as the largest position defined in
/// \p S. Processing functions are executed only if new input has been
/// received for all defined *slave* positions.
///
/// \param S set of *slave* positions to await input from
///
/// \return an *execution policy* implementing *awaiting all* input from set
/// \p S
static std::unique_ptr<AppExecutionPolicy>
awaitAll(const std::set<size_t> &S);
/// Creates an *execution policy* that allows execution if any of the defined
/// *slave* positions has new input.
///
/// *Await any* can handle only *agents* and only if the particular *agent*
/// has at least as many *slave* positions as the largest position defined in
/// \p S. Processing functions are executed if new input has been received for
/// any of the defined *slave* positions.
///
/// \param S set of *slave* positions to await input from
///
/// \return an *execution policy* implementing *awaiting any* input from set
/// \p S
static std::unique_ptr<AppExecutionPolicy>
awaitAny(const std::set<size_t> &S);
/// Tells if \p this object can handle the application *unit* referred by \p
/// H.
///
/// The *execution policy* implemented by \p this object is applicable to the
/// given application *unit* referred by \p H only if the function returns \c
/// true.
///
/// \param H reference to the *unit* to check
/// \param S the system owning the *unit* referred by \p H
///
/// \return if \p this object can handle the *unit* referred by \p H
virtual bool canHandle(const AgentHandle H, const AppSystem &S) const
noexcept = 0;
/// Tells if processing function should be executed on the current triggering.
///
/// The function is to be called on each triggering of the application *unit*.
/// Decision about execution of processing function is done by \p this object
/// according to the implemented *execution policy*.
///
/// \param InputChanged flags indicating whether new input has been received
/// at *slave* positions
///
/// \return if to execute processing function
virtual bool
shouldProcess(const std::vector<bool> &InputChanged) noexcept = 0;
/// Dumps \p this object into textual representation.
///
/// \return textual representation of \p this object
virtual std::string dump(void) const noexcept = 0;
protected:
/// Tells whether the *unit* referred by \p H is a \c
/// rosa::app::AppAgent.
///
/// \param H reference to the *unit* to check
/// \param S the system owning the *unit* referred by \p H
///
/// \return if the *unit* referred by \p H is a \c rosa::app::AppAgent
bool isAppAgent(const AgentHandle H, const AppSystem &S) const noexcept;
/// Tells the number of inputs handled by the *unit* referred by \p H.
///
/// If \p H refers to a \c rosa::app::AppAgent, the function returns the
/// number of inputs (i.e., *slave* positions) of the *agent*. Otherwise, the
/// function returns \c 0.
///
/// \param H reference to the *unit* to check
/// \param S the system owning the *unit* referred by \p H
///
/// \return the number of inputs handled by the *unit* referred by \p H
size_t numberOfAppAgentInputs(const AgentHandle H, const AppSystem &S) const
noexcept;
};
} // End namespace app
} // End namespace rosa
namespace std {
/// Converts a \c rosa::app::AppExecutionPolicy into \c std::string.
///
/// \param EP \c rosa::app::AppExecutionPolicy to convert
///
/// \return \c std::string representing \p EP
string to_string(const rosa::app::AppExecutionPolicy &EP);
/// Dumps a \c rosa::app::AppExecutionPolicy to a given \c std::ostream.
///
/// \param [in,out] OS output stream to dump to
/// \param EP \c rosa::app::AppExecutionPolicy to dump
///
/// \return \p OS after dumping \p EP to it
ostream &operator<<(ostream &OS, const rosa::app::AppExecutionPolicy &EP);
} // End namespace std
#endif // ROSA_APP_APPEXECUTIONPOLICY_H

File Metadata

Mime Type
text/x-c++
Expires
Sun, Mar 1, 9:31 PM (23 h, 20 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
281746
Default Alt Text
AppExecutionPolicy.h (7 KB)

Event Timeline