Controls the execution of single data acquisition that ultimately result in a set of FITS keywords and/or FITS files. More...

#include <daqController.hpp>

Inheritance diagram for daq::DaqController:

Public Types
using	ContextSignal = boost::signals2::signal< void(DaqContext const &)>

Public Member Functions
	DaqController ()=default

virtual	~DaqController ()=default

virtual boost::future< State >	StartAsync ()=0
	Starts the data acquisition. More...

virtual boost::future< Status >	StopAsync (ErrorPolicy policy)=0
	Stops the data acquisition. More...

virtual boost::future< Status >	AbortAsync (ErrorPolicy policy)=0
	Aborts the data acquisition. More...

virtual boost::future< State >	ScheduleMergeAsync ()=0
	Schedules DAQ for merging by sending request to DPM. More...

virtual void	UpdateKeywords (fits::KeywordVector const &keywords)=0
	Updates (replace or add) list of keywords. More...

virtual boost::future< State >	AwaitAsync (std::vector< std::string > sources, std::chrono::milliseconds timeout)=0
	Awaits that data acquisition stops or aborts. More...

virtual State	GetState () const DAQ_NOEXCEPT=0

virtual std::shared_ptr< ObservableStatus >	GetStatus () DAQ_NOEXCEPT=0

virtual std::shared_ptr< ObservableStatus const >	GetStatus () const DAQ_NOEXCEPT=0

virtual std::shared_ptr< ObservableEventLog >	GetEventLog () DAQ_NOEXCEPT=0

virtual std::string const &	GetId () const DAQ_NOEXCEPT=0

virtual bool	GetErrorFlag () const DAQ_NOEXCEPT=0

virtual DaqContext const &	GetContext () const DAQ_NOEXCEPT=0

virtual boost::signals2::connection	ConnectContext (ContextSignal::slot_type const &slot)=0
	Connect observer that is invoked when context is modified. More...

Detailed Description

Controls the execution of single data acquisition that ultimately result in a set of FITS keywords and/or FITS files.

Important

Due to the dynamic nature of data acquisitions (mostly w.r.t. fatal errors from data soures and commands from user) the following assumptions are made:

Each data source completes only once.
- This means that any command that deals with potential completion (mainly the stop and await operations) must record the outcome (DpParts + Keywords) and mark the source state as completed.
- This ensures that no outcome is lost and that subsequent commands does not include completed sources.
Conflicting commands are resolved in the order they are received and w.r.t. to state.
- If data sources are awaited on, some of which has aleady completed, and DaqController is asked to abort, this means that the DAQ state is Aborting and even if the await operation completes successfully, the result will be discarded because user asked to abort.
- If user asks to stop and primary soures are awaited on, there's a race between which request to data source completes first.
  - Commands are only sent to sources that are in-progress (not completed/aborted/stopped).
  - Whichever reply is received first (from await or stop) will determine the result from that data souce.
Async operations must be able to deal with partial failures.
- This is required to allow user to retry operation.
Asynchronous errors are published and user response is requied.
- If e.g. the await operation fails partially it means user must intervene to decide if it should try to stop or abort the DAQ (in the future a DAQ-wide policy could be set to decide what to do automatically).

Usage

Starting

Start with StartAsync
Stopping

Manual option

Stop/abort with StopAsync or AbortAsync.

Automatic option

Automatically initiate stop if all primary sources are automatically stopped as indicated by ObservableStatus status update topic.

If asynchronous operations have been started, it is still possible to abort. This command will then supersede ongoing commands, and ongoing commands will be aborted at the next synchronization point (typically when reply is received).

It is not possible to retry or go backwards by executing StartAsync after StopAsync or AbortAsync. The reasoning behind this is to avoid the risk of duplicate data acquisition id being "in flight" at the same time..

It is possible to abort on the other hand, even though the data acquisition might not have been started yet.

For StartAsync, StopAsync, AbortAsync:

The error handling strategy is to not Set result until we have a result from each source either by reply or internal error when Sending/receiving (MAL issues e.g.).

This implies:

That way we can communicate the full result using the promise. On errors it contains the exception(s) on success the new state.
We can have a mixed result of partial success and partial failure, although the future will contain exception(s).
We let caller decide what to do (e.g. abort).
We use an error flag to indicate that error occurred, which is possible in any state.
We stay in the state that had the error to e.g. allow retries. So if an error occurred in Starting then DaqController remains in Starting with the error flag Set.

Pending decision decisions:

Whether to fail fast or be robust, or even whether to be configurable.
- This was addressed with the ErrorPolicy option when stopping/aborting.
Support aborting while there are still replies pending for startDaq? This would mean that one can be in state Starting and Stopping at the same time.
- This was addressed to ignore errors when forcibly aborting.
Who connects the clients + configure QoS? Since connect is done implicitly there's no need actually. Simply specify timeout should be sufficient. And that should be done by the caller.

Definition at line 214 of file daqController.hpp.

Member Typedef Documentation

◆ ContextSignal

using daq::DaqController::ContextSignal = boost::signals2::signal<void(DaqContext const&)>

Definition at line 315 of file daqController.hpp.

Constructor & Destructor Documentation

◆ DaqController()

daq::DaqController::DaqController ( )

default

◆ ~DaqController()

virtual daq::DaqController::~DaqController ( )

virtualdefault

Member Function Documentation

◆ AbortAsync()

virtual boost::future<Status> daq::DaqController::AbortAsync ( ErrorPolicy policy )

pure virtual

Aborts the data acquisition.

Parameters

policy Error policy determining if errors are tolerated or not.

It is possible to issue this request more than once, to e.g. retry a failed abort attempt.

Precondition: GetState() not in (State::Aborted, State::Stopped)

Postcondition: GetState() == State::Aborting if a data acquisition was ongoing otherwise GetState() == State::Aborted.

Implemented in daq::DpmDaqController, daq::OcmDaqController, and DaqControllerFake.

◆ AwaitAsync()

virtual boost::future<State> daq::DaqController::AwaitAsync	(	std::vector< std::string >	sources,
		std::chrono::milliseconds	timeout
	)

pure virtual

Awaits that data acquisition stops or aborts.

It is possible to await only only a subset of data sources by specifying their ids in sources.

Parameters

sources An optional vector of source-ids to await, if empty all primary sources are awaited on.

Returns: future set with std::invalid_argument if source-id is not recognized.; future set with boost::broken_promise if DaqController is destroyed before operation completes.

Implemented in DaqControllerFake, daq::DpmDaqController, and daq::OcmDaqController.

◆ ConnectContext()

virtual boost::signals2::connection daq::DaqController::ConnectContext ( ContextSignal::slot_type const & slot )

pure virtual

Connect observer that is invoked when context is modified.

Parameters

o	Observer callable invoked on context changes.

Returns: signal connection object that can be used to disconnect observer:

Implemented in DaqControllerFake, daq::DaqControllerMock, and daq::CommonDaqController.

◆ GetContext()

virtual DaqContext const& daq::DaqController::GetContext ( ) const

pure virtual

Implemented in DaqControllerFake, and daq::CommonDaqController.

◆ GetErrorFlag()

virtual bool daq::DaqController::GetErrorFlag ( ) const

pure virtual

Returns: Error flag.

Implemented in DaqControllerFake, and daq::CommonDaqController.

◆ GetEventLog()

virtual std::shared_ptr<ObservableEventLog> daq::DaqController::GetEventLog ( )

pure virtual

Returns: event log associated with this daq.

Implemented in DaqControllerFake, and daq::CommonDaqController.

◆ GetId()

virtual std::string const& daq::DaqController::GetId ( ) const

pure virtual

Returns: data acquisition identifier.

Implemented in DaqControllerFake, and daq::CommonDaqController.

◆ GetState()

virtual State daq::DaqController::GetState ( ) const

pure virtual

Returns: state of data acquisition.

Implemented in daq::DaqControllerMock, DaqControllerFake, daq::DpmDaqController, and daq::OcmDaqController.

◆ GetStatus() [1/2]

virtual std::shared_ptr<ObservableStatus const> daq::DaqController::GetStatus ( ) const

pure virtual

Implemented in DaqControllerFake, and daq::CommonDaqController.

◆ GetStatus() [2/2]

virtual std::shared_ptr<ObservableStatus> daq::DaqController::GetStatus ( )

pure virtual

Returns: status object associated with this daq.

Implemented in DaqControllerFake, and daq::CommonDaqController.

◆ ScheduleMergeAsync()

virtual boost::future<State> daq::DaqController::ScheduleMergeAsync ( )

pure virtual

Schedules DAQ for merging by sending request to DPM.

Returns

future containing exception:

std::logic_error if DAQ has already been scheduled
mal::TimeoutException if DPM is offline (timeout).
unspecified DPM fails

Implemented in DaqControllerFake, daq::DpmDaqController, and daq::OcmDaqController.

◆ StartAsync()

virtual boost::future<State> daq::DaqController::StartAsync ( )

pure virtual

Starts the data acquisition.

Returns: A future that will be Set once data acquisition has started or or fails.

Exceptions

std::exception-derived exception if internal error occurs.

Returns: Future that is ready once all sources are started or failed.

Precondition: GetState() == State::Notstarted

Postcondition: GetState() == State::Starting on success GetState() == State::Error on error

Implemented in DaqControllerFake, daq::DpmDaqController, and daq::OcmDaqController.

◆ StopAsync()

virtual boost::future<Status> daq::DaqController::StopAsync ( ErrorPolicy policy )

pure virtual

Stops the data acquisition.

Precondition: GetState() not in (State::Stopped or State::Aborted)

Postcondition: GetState() == State::Stopping

Implemented in daq::DpmDaqController, daq::OcmDaqController, and DaqControllerFake.

◆ UpdateKeywords()

virtual void daq::DaqController::UpdateKeywords ( fits::KeywordVector const & keywords )

pure virtual

Updates (replace or add) list of keywords.

Parameters

keywords Keywords to add.

Implemented in daq::DpmDaqController, daq::OcmDaqController, and DaqControllerFake.

The documentation for this class was generated from the following file:

common/libdaq/src/include/daq/daqController.hpp

Public Types

Public Member Functions

Detailed Description

Important

Usage

Manual option

Automatic option

Member Typedef Documentation

◆ ContextSignal

Constructor & Destructor Documentation

◆ DaqController()

◆ ~DaqController()

Member Function Documentation

◆ AbortAsync()

◆ AwaitAsync()

◆ ConnectContext()

◆ GetContext()

◆ GetErrorFlag()

◆ GetEventLog()

◆ GetId()

◆ GetState()

◆ GetStatus() [1/2]

◆ GetStatus() [2/2]

◆ ScheduleMergeAsync()

◆ StartAsync()

◆ StopAsync()

◆ UpdateKeywords()