$darkmode
Public Member Functions | Protected Attributes | List of all members
cloe::Model Class Referenceabstract

#include <model.hpp>

Inheritance diagram for cloe::Model:
[legend]
Collaboration diagram for cloe::Model:
[legend]

Public Member Functions

virtual ~Model () noexcept=default
 
virtual Duration resolution () const
 
virtual bool is_connected () const
 
virtual bool is_operational () const
 
virtual void connect ()
 
virtual void disconnect ()
 
virtual void enroll (Registrar &)
 
virtual void start (const Sync &)
 
virtual Duration process (const Sync &)=0
 
virtual void pause (const Sync &)
 
virtual void resume (const Sync &)
 
virtual void stop (const Sync &)
 
virtual void reset ()
 
virtual void abort ()
 
- Public Member Functions inherited from cloe::Entity
 Entity (const std::string &name)
 
 Entity (const std::string &name, const std::string &desc)
 
std::string name () const
 
void set_name (const std::string &name)
 
std::string description () const
 
void set_description (const std::string &desc)
 

Protected Attributes

bool connected_ {false}
 
bool operational_ {false}
 
- Protected Attributes inherited from cloe::Entity
std::string name_
 
std::string desc_
 

Additional Inherited Members

- Protected Member Functions inherited from cloe::Entity
virtual Logger logger () const
 

Detailed Description

The Model class serves as an interface which Controller and Simulator can inherit from.

The following flow diagram shows how the methods of a Model are called in a typical simulation. The nominal flow is rendered in solid lines, while irregular situations are rendered in dashed lines. 

                           ┌──────────────────────┐
                           │       Model()        │
                           └──────────────────────┘
                                      │
                                      ▼
                           ┌──────────────────────┐
 +------------------------ │      connect()       │
 |                         └──────────────────────┘
 |                                    │
 |                                    ▼
 |                         ┌──────────────────────┐
 |                         │  enroll(Registrar&)  │
 |                         └──────────────────────┘
 |                                    │
 |                                    ▼
 |                         ┌──────────────────────┐
 |                         │  start(const Sync&)  │ <-----------+
 |                         └──────────────────────┘             |
 |  +---------------+                 │                         |
 |  |  resume(...)  | ----------+     │                         |
 |  +---------------+           |     │                         |
 |          ^                   v     ▼                         |
 |          |              ┌──────────────────────┐             |
 |  +---------------+      │                      │ ◀──┐        |
 |  |   pause(...)  | <--- │                      │    │        |
 |  +---------------+      │ process(const Sync&) │    │        |
 |        |                │                      │    │        |
 |        |     +--------- │                      │ ───┘        |
 |        |     |          └──────────────────────┘             |
 |        |     |                     │                         |
 |        v     v                     ▼                         |
 |     +-----------+       ┌──────────────────────┐       +-----------+
 +---> |  abort()  | ----> │  stop(const Sync&)   │ ----> |  reset()  |
       +-----------+       └──────────────────────┘       +-----------+
             |                        │
             |                        ▼
             |             ┌──────────────────────┐
             +-----------> │     disconnect()     │
                           └──────────────────────┘
                                      │
                                      ▼
                           ┌──────────────────────┐
                           │      ~Model()        │
                           └──────────────────────┘

Note that not all of the methods of a Model are presented in the above diagram. For example, the methods resolution() and is_connected() are expected to be callable at all times. The edges present cover roughly 95% of all expected use-cases, but not all. For example, it is conceivable that a Model will be destructed before connect() is called.

Constructor & Destructor Documentation

◆ ~Model()

virtual cloe::Model::~Model ( )
virtualdefaultnoexcept

Destroy a model.

Destruction must handle everything that must be torn down after a disconnect or possibly even before a connect has occurred.

Member Function Documentation

◆ abort()

virtual void cloe::Model::abort ( )
inlinevirtual

Signal an abort to model processing.

This method is called asynchronously. It is highly recommended to make use of a std::atomic_bool for purposes of making the abortion request known to other parts of the model. This method is called when the user requests the simulation to be aborted, e.g., by sending the SIGINT signal.

An abort will be followed by a stop if the simulation was started.

The default implementation will throw an error. This will be caught and possibly ignored. Otherwise, the simulation will be killed.

See also
cloe/core/abort.hpp

Reimplemented in minimator::MinimatorSimulator, cloe::controller::basic::BasicController, cloe::controller::Virtue, cloe::Vehicle, cloe::ObjectSensorFilterMap, cloe::controller::GndTruthExtractor, cloe::Component, cloe::ObjectSensorFilter, vtd::VtdBinding, cloe::simulator::NopSimulator, demo::DemoStuck, demo::DemoPrinter, and cloe::controller::NopController.

◆ connect()

virtual void cloe::Model::connect ( )
inlinevirtual

Initiate a connection to the model, including any initialization.

  • It should block until the connection is successfully established.
  • It should throw an exception if an unrecoverable error occurs.
  • It should react to an abort() called on the model.
  • It may throw an error if already connected.

After a successful connection, the following methods shall be callable:

When implementing this method, e.g. via override or final, make sure to call this method:

void MySuperModel::connect() final { // Your connection code Model::connect(); }

Reimplemented in minimator::MinimatorSimulator, cloe::Vehicle, vtd::VtdBinding, and cloe::simulator::NopSimulator.

Here is the caller graph for this function:

◆ disconnect()

virtual void cloe::Model::disconnect ( )
inlinevirtual

Tear down the connection to the model.

  • It should block until the connection is successfully closed.
  • It should throw an exception if an unrecoverable error occurs.
  • It should not throw an exception if called when not connected.

After successful disconnection, it is not expected that the model should be able to connect again.

When implementing this method, e.g. via override or final, make sure to call this method:

void MySuperModel::disconnect() final { // Your disconnection code Model::disconnect(); }

Reimplemented in minimator::MinimatorSimulator, cloe::Vehicle, and vtd::VtdBinding.

Here is the caller graph for this function:

◆ enroll()

virtual void cloe::Model::enroll ( Registrar &  )
inlinevirtual

Register any events, actions, or handlers with the registrar.

  • This may exhibit different behavior when called in a disconnected state, in order to provide the possibility for verification of triggers in offline mode.
  • It may throw an exception.

Reimplemented in minimator::MinimatorSimulator, cloe::controller::basic::BasicController, cloe::controller::Virtue, vtd::VtdBinding, cloe::Vehicle, cloe::simulator::NopSimulator, and Speedometer.

◆ is_connected()

virtual bool cloe::Model::is_connected ( ) const
inlinevirtual

Return whether the model is successfully connected.

Here is the caller graph for this function:

◆ is_operational()

virtual bool cloe::Model::is_operational ( ) const
inlinevirtual

Return whether the model can continue processing.

Here is the caller graph for this function:

◆ pause()

virtual void cloe::Model::pause ( const Sync &  )
inlinevirtual

Perform any work for transitioning into a paused state.

The passed Sync interface should return the step and time that will be passed to the next resume and process calls.

  • It may throw an exception if the model does not support pausing. This could be the case if the model is connected to a HIL, for example.

◆ process()

virtual Duration cloe::Model::process ( const Sync &  )
pure virtual

Perform model processing given the simulation context.

In particular, the model may read and write information from and to data it has, in particular any vehicles.

  • Method is_operational() should return true.
  • It may throw an exception. Those derived from ModelError are more likely to be correctly handled, however. The simulation may handle it by a) removing or replacing the model, b) stopping the simulation, or c) ignoring the exception. In the last case, this method will be called again in the next simulation step. In any case, assume that the simulation will print a message to the logs or the console.
  • It should return the current simulation duration from the model's time domain, which is expected to be less or equal to sync.time().

Implemented in minimator::MinimatorSimulator, cloe::controller::basic::BasicController, vtd::VtdBinding, cloe::controller::Virtue, minimator::MinimatorVehicle, cloe::Vehicle, cloe::ObjectSensorFilterMap, cloe::Simulator, cloe::controller::GndTruthExtractor, cloe::Component, cloe::simulator::NopSimulator, cloe::ObjectSensorFilter, vtd::VtdLatLongActuator, cloe::LatLongActuator, cloe::VehicleStateModel, cloe::NopDriverRequest, demo::DemoStuck, demo::DemoPrinter, cloe::controller::NopController, Speedometer, cloe::Actuator< T >, cloe::Actuator< double >, cloe::Actuator< PedalRequest >, cloe::Actuator< SteeringRequest >, and cloe::Actuator< GearboxRequest >.

◆ reset()

virtual void cloe::Model::reset ( )
inlinevirtual

Reset the model state.

This is called when Cloe is asked to reset the whole simulation to time 0. This can be the case when the simulator or a controller asks us to recover from a temporary problem without repeating the whole simulation setup.

The default implementation will raise an error. So if your model is not able to re-initialize, the simulation will be aborted.

Reimplemented in minimator::MinimatorSimulator, vtd::VtdBinding, cloe::Vehicle, cloe::ObjectSensorFilterMap, cloe::controller::GndTruthExtractor, vtd::VtdVehicle, vtd::VtdExternalEgoModel, cloe::Component, cloe::ObjectSensorFilter, vtd::VtdLatLongActuator, cloe::LatLongActuator, cloe::simulator::NopSimulator, cloe::VehicleStateModel, cloe::NopDriverRequest, cloe::NopWheelSensor, cloe::NopObjectSensor, cloe::NopEgoSensor, cloe::NopPowertrainSensor, demo::DemoStuck, cloe::NopBrakeSensor, cloe::NopSteeringSensor, cloe::Actuator< T >, cloe::Actuator< double >, cloe::Actuator< PedalRequest >, cloe::Actuator< SteeringRequest >, cloe::Actuator< GearboxRequest >, demo::DemoPrinter, and cloe::controller::NopController.

◆ resolution()

Duration cloe::Model::resolution ( ) const
virtual

Return the time resolution of the model.

This is how much time each process call is expected to advance. Zero may be returned if the model does not have an intrinsic time resolution. (This would imply that calling process(const Sync&) will advance the models time to exactly Sync::time().

◆ resume()

virtual void cloe::Model::resume ( const Sync &  )
inlinevirtual

Perform any work when resuming from a paused state.

The passed Sync interface should return the step and time that will be passed to the next process call.

  • It may throw an exception if the model cannot resume. This could be the case if the paused timespan was too large so that the backend died.

◆ start()

virtual void cloe::Model::start ( const Sync &  )
inlinevirtual

Perform model setup for the simulation.

The passed Sync interface should return a step and time of zero.

Reimplemented in vtd::VtdBinding, cloe::controller::Virtue, and cloe::controller::GndTruthExtractor.

Here is the caller graph for this function:

◆ stop()

virtual void cloe::Model::stop ( const Sync &  )
inlinevirtual

Perform final work that may throw an exception.

This is called after the last process call when the simulation is through. It is possible after a call to stop, that a reset will be called, followed by a further start. Nominally, however, it will be followed by a disconnect.

Reimplemented in vtd::VtdBinding, and cloe::controller::GndTruthExtractor.

Here is the caller graph for this function:
The documentation for this class was generated from the following files: