Source¶

class nmeasim::core::simulation::Source · Library API

Base class of the simulation modes: delta drift, track following and log replay.

#include <nmeasim/core/simulation/source.hpp>

Inherited by nmeasim::core::simulation::DeltaSource, nmeasim::core::simulation::ReplaySource, nmeasim::core::simulation::TrackSource

Declared in src/core/include/nmeasim/core/simulation/source.hpp (line 35)

A source owns its vessel state and changes it only when one of its members is called; it has no clock of its own. Simulated time advances by the dt given to advance, and the time_utc of the state follows the rules of each mode. An endless source (DeltaSource) keeps the defaults of the transport members; a finite one (TrackSource, ReplaySource) reports a duration, a position within it and finished(), and can seek.

Copying and moving are protected, so that only a derived class can be copied and a source held through a Source reference cannot be sliced.

See also

Summary¶

Public member functions

Name	Description
`~Source()`	Destroys the source and the state it owns.
`advance()`	Advances the source by `dt` of simulated time.
`current()`	Returns the most recently produced state.
`reset()`	Returns the source to its initial state and position zero.
`finished()`	Returns whether a finite source has nothing more to produce.
`duration()`	Returns the length of a finite source in simulated time.
`position()`	Returns the elapsed position within a finite source.
`seek()`	Moves a finite source to a position; endless sources ignore it.
`provides_sentences()`	Returns whether the source replays recorded sentences instead of producing a state for the encoders.
`take_sentences()`	Hands over the sentences that became due since the previous call.
`step_once()`	Advances a sentence-providing source by exactly one recorded sentence and moves its clock to that sentence's offset; other sources ignore it.
`set_destination()`	Sets or clears the destination that the autopilot sentences describe; sources that decode their state from recorded sentences ignore it.

Protected member functions

Name	Description
`Source()`	Creates the base of a source; only derived classes construct one.
`Source()`	Copies the base of a source; protected so that only derived classes copy, which prevents slicing.
`operator=()`	Copy-assigns the base of a source; protected so that only derived classes assign.
`Source()`	Moves the base of a source; protected so that only derived classes move, which prevents slicing.
`operator=()`	Move-assigns the base of a source; protected so that only derived classes assign.

Public member functions¶

~Source()¶

virtual ~Source() = default

Destroys the source and the state it owns.

Declared in src/core/include/nmeasim/core/simulation/source.hpp:38

advance()¶

virtual const model::VesselState& advance(std::chrono::milliseconds dt) = 0

Advances the source by dt of simulated time.

Parameters

Name	Type	Description
`dt`	`std::chrono::milliseconds`	Simulated time to advance by. Zero is allowed; a replay then still emits the entries due at its current offset.

Returns const model::VesselState&: The state at the new time, the same object current returns.

Preconditions

dt is not negative; time only moves backwards through seek or reset.

Declared in src/core/include/nmeasim/core/simulation/source.hpp:46

current()¶

virtual const model::VesselState& current() const noexcept = 0

Returns the most recently produced state.

Returns const model::VesselState&: The state the source owns. The reference stays valid for the lifetime of the source; the object it refers to changes with every call that moves the source.

Declared in src/core/include/nmeasim/core/simulation/source.hpp:52

reset()¶

virtual void reset() = 0

Returns the source to its initial state and position zero.

What survives a reset (for example a destination set by the host) is stated by each source.

Declared in src/core/include/nmeasim/core/simulation/source.hpp:58

finished()¶

virtual bool finished() const noexcept

Returns whether a finite source has nothing more to produce.

Returns bool: True once a source configured to stop at its end has reached it; always false for an endless source and for a looping one. The default returns false.

Declared in src/core/include/nmeasim/core/simulation/source.hpp:64

duration()¶

virtual std::optional<std::chrono::milliseconds> duration() const noexcept

Returns the length of a finite source in simulated time.

Returns std::optional<std::chrono::milliseconds>: The duration, zero for a source with nothing to play, or std::nullopt for an endless source. The default returns std::nullopt.

Declared in src/core/include/nmeasim/core/simulation/source.hpp:70

position()¶

virtual std::chrono::milliseconds position() const noexcept

Returns the elapsed position within a finite source.

Returns std::chrono::milliseconds: The position in [0, duration()]; it restarts from zero when a looping source wraps. The default, for endless sources, returns zero.

Declared in src/core/include/nmeasim/core/simulation/source.hpp:78

seek()¶

virtual void seek(std::chrono::milliseconds)

Moves a finite source to a position; endless sources ignore it.

The position argument, time since the start of the source, is clamped to [0, duration()]. The state reflects the new position immediately, without a call to advance. The default does nothing.

Declared in src/core/include/nmeasim/core/simulation/source.hpp:85

provides_sentences()¶

virtual bool provides_sentences() const noexcept

Returns whether the source replays recorded sentences instead of producing a state for the encoders.

Returns bool: True for a source whose sentences Simulation returns from take_sentences, leaving the sentence schedule idle. The default returns false.

Declared in src/core/include/nmeasim/core/simulation/source.hpp:92

take_sentences()¶

virtual std::vector<EmittedSentence> take_sentences()

Hands over the sentences that became due since the previous call.

Returns std::vector<EmittedSentence>: The sentences produced by advance, step_once or both since the last call, in the order they became due; the source keeps none of them. The default, for sources that do not provide sentences, returns an empty vector.

Declared in src/core/include/nmeasim/core/simulation/source.hpp:99

step_once()¶

virtual void step_once()

Advances a sentence-providing source by exactly one recorded sentence and moves its clock to that sentence's offset; other sources ignore it.

The sentence is collected by the next take_sentences. The default does nothing.

Declared in src/core/include/nmeasim/core/simulation/source.hpp:105

set_destination()¶

virtual void set_destination(std::optional<model::Destination>)

Sets or clears the destination that the autopilot sentences describe; sources that decode their state from recorded sentences ignore it.

A destination argument of std::nullopt clears it. The default does nothing.

Declared in src/core/include/nmeasim/core/simulation/source.hpp:112

Protected member functions¶

Source()¶

Source() = default

Creates the base of a source; only derived classes construct one.

Declared in src/core/include/nmeasim/core/simulation/source.hpp:116

Source()¶

Source(const Source&) = default

Copies the base of a source; protected so that only derived classes copy, which prevents slicing.

Declared in src/core/include/nmeasim/core/simulation/source.hpp:119

operator=()¶

Source& operator=(const Source&) = default

Copy-assigns the base of a source; protected so that only derived classes assign.

Returns Source&: This object.

Declared in src/core/include/nmeasim/core/simulation/source.hpp:123

Source()¶

Source(Source&&) = default

Moves the base of a source; protected so that only derived classes move, which prevents slicing.

Declared in src/core/include/nmeasim/core/simulation/source.hpp:126

operator=()¶

Source& operator=(Source&&) = default

Move-assigns the base of a source; protected so that only derived classes assign.

Returns Source&: This object.

Declared in src/core/include/nmeasim/core/simulation/source.hpp:130