fair::mq::PluginServices Class Reference

Facilitates communication between devices and plugins. More...

#include <fairmq/PluginServices.h>

Classes
struct	DeviceControlError
struct	InvalidStateError
struct	PropertyNotFoundError

Public Types
enum	DeviceState : int {   Ok, Error, Idle, InitializingDevice,   DeviceReady, InitializingTask, Ready, Running,   Paused, ResettingTask, ResettingDevice, Exiting }
	See https://github.com/FairRootGroup/FairRoot/blob/dev/fairmq/docs/Device.md#13-state-machine.
enum	DeviceStateTransition : int {   InitDevice, InitTask, Run, Pause,   Resume, Stop, ResetTask, ResetDevice,   End, ErrorFound }

Public Member Functions
	PluginServices (FairMQProgOptions &config, FairMQDevice &device)
	PluginServices (const PluginServices &)=delete
PluginServices	operator= (const PluginServices &)=delete
auto	GetCurrentDeviceState () const -> DeviceState
auto	TakeDeviceControl (const std::string &controller) -> void
	Become device controller. More...
auto	StealDeviceControl (const std::string &controller) -> void
	Become device controller by force. More...
auto	ReleaseDeviceControl (const std::string &controller) -> void
	Release device controller role. More...
auto	GetDeviceController () const -> boost::optional< std::string >
	Get current device controller.
auto	WaitForReleaseDeviceControl () -> void
	Block until control is released.
auto	ChangeDeviceState (const std::string &controller, const DeviceStateTransition next) -> void
	Request a device state transition. More...
auto	SubscribeToDeviceStateChange (const std::string &subscriber, std::function< void(DeviceState)> callback) -> void
	Subscribe with a callback to device state changes. More...
auto	UnsubscribeFromDeviceStateChange (const std::string &subscriber) -> void
	Unsubscribe from device state changes. More...
auto	PropertyExists (const std::string &key) const -> bool
template<typename T >
auto	SetProperty (const std::string &key, T val) -> void
	Set config property. More...
template<typename T >
auto	GetProperty (const std::string &key) const -> T
	Read config property. More...
auto	GetPropertyAsString (const std::string &key) const -> std::string
	Read config property as string. More...
auto	GetChannelInfo () const -> std::unordered_map< std::string, int >
auto	GetPropertyKeys () const -> std::vector< std::string >
	Discover the list of property keys. More...
template<typename T >
auto	SubscribeToPropertyChange (const std::string &subscriber, std::function< void(const std::string &key, T)> callback) const -> void
	Subscribe to property updates of type T. More...
template<typename T >
auto	UnsubscribeFromPropertyChange (const std::string &subscriber) -> void
	Unsubscribe from property updates of type T. More...
auto	SubscribeToPropertyChangeAsString (const std::string &subscriber, std::function< void(const std::string &key, std::string)> callback) const -> void
	Subscribe to property updates. More...
auto	UnsubscribeFromPropertyChangeAsString (const std::string &subscriber) -> void
	Unsubscribe from property updates that convert to string. More...
auto	CycleLogConsoleSeverityUp () -> void
auto	CycleLogConsoleSeverityDown () -> void
auto	CycleLogVerbosityUp () -> void
auto	CycleLogVerbosityDown () -> void

Static Public Member Functions
static auto	ToDeviceState (const std::string &state) -> DeviceState
	Convert string to DeviceState. More...
static auto	ToDeviceStateTransition (const std::string &transition) -> DeviceStateTransition
	Convert string to DeviceStateTransition. More...
static auto	ToStr (DeviceState state) -> std::string
	Convert DeviceState to string. More...
static auto	ToStr (DeviceStateTransition transition) -> std::string
	Convert DeviceStateTransition to string. More...

Static Public Attributes
static const std::unordered_map< std::string, DeviceState >	fkDeviceStateStrMap
static const std::unordered_map< DeviceState, std::string, tools::HashEnum< DeviceState > >	fkStrDeviceStateMap
static const std::unordered_map< std::string, DeviceStateTransition >	fkDeviceStateTransitionStrMap
static const std::unordered_map< DeviceStateTransition, std::string, tools::HashEnum< DeviceStateTransition > >	fkStrDeviceStateTransitionMap
static const std::unordered_map< FairMQDevice::State, DeviceState, tools::HashEnum< FairMQDevice::State > >	fkDeviceStateMap
static const std::unordered_map< DeviceStateTransition, FairMQDevice::Event, tools::HashEnum< DeviceStateTransition > >	fkDeviceStateTransitionMap

Friends
auto	operator<< (std::ostream &os, const DeviceState &state) -> std::ostream &
auto	operator<< (std::ostream &os, const DeviceStateTransition &transition) -> std::ostream &

Detailed Description

Facilitates communication between devices and plugins.

• Configuration interface
• Control interface

Member Function Documentation

ChangeDeviceState()

auto PluginServices::ChangeDeviceState	(	const std::string &	controller,
		const DeviceStateTransition	next
	)		-> void

Request a device state transition.

Parameters

controller	id
next	state transition

Exceptions

fair::mq::PluginServices::DeviceControlError

if control role is not currently owned by passed controller id.

The state transition may not happen immediately, but when the current state evaluates the pending transition event and terminates. In other words, the device states are scheduled cooperatively. If the device control role has not been taken yet, calling this function will take over control implicitely.

GetCurrentDeviceState()

auto fair::mq::PluginServices::GetCurrentDeviceState ( ) const -> DeviceState

inline

Returns

current device state

GetProperty()

template<typename T >

auto fair::mq::PluginServices::GetProperty ( const std::string &  key ) const -> T

inline

Read config property.

Parameters

key

Returns

config property value

TODO Currently, if a non-existing key is requested and a default constructed object is returned. This behaviour will be changed in the future to throw an exception in that case to provide a proper sentinel.

GetPropertyAsString()

auto fair::mq::PluginServices::GetPropertyAsString ( const std::string &  key ) const -> std::string

inline

Read config property as string.

Parameters

key

Returns

config property value converted to string

If a type is not supported, the user can provide support by overloading the ostream operator for this type

GetPropertyKeys()

auto fair::mq::PluginServices::GetPropertyKeys ( ) const -> std::vector<std::string>

inline

Discover the list of property keys.

Returns

list of property keys

ReleaseDeviceControl()

auto PluginServices::ReleaseDeviceControl

(

const std::string &

controller

)

-> void

Release device controller role.

Parameters

controller

id

Exceptions

fair::mq::PluginServices::DeviceControlError

if passed controller id is not the current device controller.

SetProperty()

template<typename T >

auto fair::mq::PluginServices::SetProperty ( const std::string &  key, T  val  ) -> void

inline

Set config property.

Parameters

key
val

Exceptions

fair::mq::PluginServices::InvalidStateError

if method is called in unsupported device states

Setting a config property will store the value in the FairMQ internal config store and notify any subscribers about the update. It is property dependent, if the call to this method will have an immediate, delayed or any effect at all.

StealDeviceControl()

auto PluginServices::StealDeviceControl

(

const std::string &

controller

)

-> void

Become device controller by force.

Parameters

controller

id

Take over device controller privileges by force. Does not trigger the ReleaseDeviceControl condition! This function is intended to implement override/emergency control functionality (e.g. device shutdown on SIGINT).

SubscribeToDeviceStateChange()

auto fair::mq::PluginServices::SubscribeToDeviceStateChange ( const std::string &  subscriber, std::function< void(DeviceState)>  callback  ) -> void

inline

Subscribe with a callback to device state changes.

Parameters

subscriber	id
callback	The callback will be called at the beginning of a new state. The callback is called from the thread the state is running in.

SubscribeToPropertyChange()

template<typename T >

auto fair::mq::PluginServices::SubscribeToPropertyChange ( const std::string &  subscriber, std::function< void(const std::string &key, T)>  callback  ) const -> void

inline

Subscribe to property updates of type T.

Parameters

subscriber
callback	function

Subscribe to property changes with a callback to monitor property changes in an event based fashion.

SubscribeToPropertyChangeAsString()

auto fair::mq::PluginServices::SubscribeToPropertyChangeAsString ( const std::string &  subscriber, std::function< void(const std::string &key, std::string)>  callback  ) const -> void

inline

Subscribe to property updates.

Parameters

subscriber
callback	function

Subscribe to property changes with a callback to monitor property changes in an event based fashion. Will convert the property to string.

TakeDeviceControl()

auto PluginServices::TakeDeviceControl

(

const std::string &

controller

)

-> void

Become device controller.

Parameters

controller

id

Exceptions

fair::mq::PluginServices::DeviceControlError

if there is already a device controller.

Only one plugin can succeed to take control over device state transitions at a time.

ToDeviceState()

static auto fair::mq::PluginServices::ToDeviceState ( const std::string &  state ) -> DeviceState

inlinestatic

Convert string to DeviceState.

Parameters

state

to convert

Returns

DeviceState enum entry

Exceptions

std::out_of_range

if a string cannot be resolved to a DeviceState

ToDeviceStateTransition()

static auto fair::mq::PluginServices::ToDeviceStateTransition ( const std::string &  transition ) -> DeviceStateTransition

inlinestatic

Convert string to DeviceStateTransition.

Parameters

transition

to convert

Returns

DeviceStateTransition enum entry

Exceptions

std::out_of_range

if a string cannot be resolved to a DeviceStateTransition

ToStr() [1/2]

static auto fair::mq::PluginServices::ToStr ( DeviceState  state ) -> std::string

inlinestatic

Convert DeviceState to string.

Parameters

state

to convert

Returns

string representation of DeviceState enum entry

ToStr() [2/2]

static auto fair::mq::PluginServices::ToStr ( DeviceStateTransition  transition ) -> std::string

inlinestatic

Convert DeviceStateTransition to string.

Parameters

transition

to convert

Returns

string representation of DeviceStateTransition enum entry

UnsubscribeFromDeviceStateChange()

auto fair::mq::PluginServices::UnsubscribeFromDeviceStateChange ( const std::string &  subscriber ) -> void

inline

Unsubscribe from device state changes.

Parameters

subscriber

id

UnsubscribeFromPropertyChange()

template<typename T >

auto fair::mq::PluginServices::UnsubscribeFromPropertyChange ( const std::string &  subscriber ) -> void

inline

Unsubscribe from property updates of type T.

Parameters

subscriber

UnsubscribeFromPropertyChangeAsString()

auto fair::mq::PluginServices::UnsubscribeFromPropertyChangeAsString ( const std::string &  subscriber ) -> void

inline

Unsubscribe from property updates that convert to string.

Parameters

subscriber

Member Data Documentation

fkDeviceStateMap

const std::unordered_map< FairMQDevice::State, PluginServices::DeviceState, fair::mq::tools::HashEnum< FairMQDevice::State > > PluginServices::fkDeviceStateMap

static

Initial value:

= {
    {FairMQDevice::OK,                  DeviceState::Ok},
    {FairMQDevice::Error,               DeviceState::Error},
    {FairMQDevice::IDLE,                DeviceState::Idle},
    {FairMQDevice::INITIALIZING_DEVICE, DeviceState::InitializingDevice},
    {FairMQDevice::DEVICE_READY,        DeviceState::DeviceReady},
    {FairMQDevice::INITIALIZING_TASK,   DeviceState::InitializingTask},
    {FairMQDevice::READY,               DeviceState::Ready},
    {FairMQDevice::RUNNING,             DeviceState::Running},
    {FairMQDevice::PAUSED,              DeviceState::Paused},
    {FairMQDevice::RESETTING_TASK,      DeviceState::ResettingTask},
    {FairMQDevice::RESETTING_DEVICE,    DeviceState::ResettingDevice},
    {FairMQDevice::EXITING,             DeviceState::Exiting}
}

fkDeviceStateStrMap

const std::unordered_map< std::string, PluginServices::DeviceState > PluginServices::fkDeviceStateStrMap

static

Initial value:

= {
    {"OK",                  DeviceState::Ok},
    {"ERROR",               DeviceState::Error},
    {"IDLE",                DeviceState::Idle},
    {"INITIALIZING DEVICE", DeviceState::InitializingDevice},
    {"DEVICE READY",        DeviceState::DeviceReady},
    {"INITIALIZING TASK",   DeviceState::InitializingTask},
    {"READY",               DeviceState::Ready},
    {"RUNNING",             DeviceState::Running},
    {"PAUSED",              DeviceState::Paused},
    {"RESETTING TASK",      DeviceState::ResettingTask},
    {"RESETTING DEVICE",    DeviceState::ResettingDevice},
    {"EXITING",             DeviceState::Exiting}
}

fkDeviceStateTransitionMap

const std::unordered_map< PluginServices::DeviceStateTransition, FairMQDevice::Event, tools::HashEnum< PluginServices::DeviceStateTransition > > PluginServices::fkDeviceStateTransitionMap

static

Initial value:

= {
    {DeviceStateTransition::InitDevice,  FairMQDevice::INIT_DEVICE},
    {DeviceStateTransition::InitTask,    FairMQDevice::INIT_TASK},
    {DeviceStateTransition::Run,         FairMQDevice::RUN},
    {DeviceStateTransition::Pause,       FairMQDevice::PAUSE},
    {DeviceStateTransition::Resume,      FairMQDevice::RUN},
    {DeviceStateTransition::Stop,        FairMQDevice::STOP},
    {DeviceStateTransition::ResetTask,   FairMQDevice::RESET_TASK},
    {DeviceStateTransition::ResetDevice, FairMQDevice::RESET_DEVICE},
    {DeviceStateTransition::End,         FairMQDevice::END},
    {DeviceStateTransition::ErrorFound,  FairMQDevice::ERROR_FOUND}
}

fkDeviceStateTransitionStrMap

const std::unordered_map< std::string, PluginServices::DeviceStateTransition > PluginServices::fkDeviceStateTransitionStrMap

static

Initial value:

= {
    {"INIT DEVICE",  DeviceStateTransition::InitDevice},
    {"INIT TASK",    DeviceStateTransition::InitTask},
    {"RUN",          DeviceStateTransition::Run},
    {"PAUSE",        DeviceStateTransition::Pause},
    {"RESUME",       DeviceStateTransition::Resume},
    {"STOP",         DeviceStateTransition::Stop},
    {"RESET TASK",   DeviceStateTransition::ResetTask},
    {"RESET DEVICE", DeviceStateTransition::ResetDevice},
    {"END",          DeviceStateTransition::End},
    {"ERROR FOUND",  DeviceStateTransition::ErrorFound},
}

fkStrDeviceStateMap

const std::unordered_map< PluginServices::DeviceState, std::string, tools::HashEnum< PluginServices::DeviceState > > PluginServices::fkStrDeviceStateMap

static

Initial value:

= {
    {DeviceState::Ok,                 "OK"},
    {DeviceState::Error,              "ERROR"},
    {DeviceState::Idle,               "IDLE"},
    {DeviceState::InitializingDevice, "INITIALIZING DEVICE"},
    {DeviceState::DeviceReady,        "DEVICE READY"},
    {DeviceState::InitializingTask,   "INITIALIZING TASK"},
    {DeviceState::Ready,              "READY"},
    {DeviceState::Running,            "RUNNING"},
    {DeviceState::Paused,             "PAUSED"},
    {DeviceState::ResettingTask,      "RESETTING TASK"},
    {DeviceState::ResettingDevice,    "RESETTING DEVICE"},
    {DeviceState::Exiting,            "EXITING"}
}

fkStrDeviceStateTransitionMap

const std::unordered_map< PluginServices::DeviceStateTransition, std::string, tools::HashEnum< PluginServices::DeviceStateTransition > > PluginServices::fkStrDeviceStateTransitionMap

static

Initial value:

= {
    {DeviceStateTransition::InitDevice,  "INIT DEVICE"},
    {DeviceStateTransition::InitTask,    "INIT TASK"},
    {DeviceStateTransition::Run,         "RUN"},
    {DeviceStateTransition::Pause,       "PAUSE"},
    {DeviceStateTransition::Resume,      "RESUME"},
    {DeviceStateTransition::Stop,        "STOP"},
    {DeviceStateTransition::ResetTask,   "RESET TASK"},
    {DeviceStateTransition::ResetDevice, "RESET DEVICE"},
    {DeviceStateTransition::End,         "END"},
    {DeviceStateTransition::ErrorFound,  "ERROR FOUND"},
}

---

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

• fairmq/PluginServices.h
• fairmq/PluginServices.cxx