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, std::shared_ptr< 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