# FairMQ: fair::mq::PluginServices Class Reference

fair::mq::PluginServices Class Reference

Facilitates communication between devices and plugins. More...

`#include <fairmq/PluginServices.h>`

## Classes

struct | DeviceControlError

## Public Types

using | DeviceState = fair::mq::State
using | DeviceStateTransition = fair::mq::Transition

## Public Member Functions

| PluginServices (ProgOptions &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) -> bool
| 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
| Checks a property with the given key exist in the configuration. More...
template<typename T >
auto | SetProperty (const std::string &key, T val) -> void
| Set config property. More...
void | SetProperties (const fair::mq::Properties &props)
| Set multiple config properties. More...
template<typename T >
bool | UpdateProperty (const std::string &key, T val)
| Updates an existing config property (or fails if it doesn't exist) More...
bool | UpdateProperties (const fair::mq::Properties &input)
| Updates multiple existing config properties (or fails of any of then do not exist, leaving property store unchanged) More...
void | DeleteProperty (const std::string &key)
| Deletes a property with the given key from the config store. More...
template<typename T >
auto | GetProperty (const std::string &key) const -> T
| Read config property, throw if no property with this key exists. More...
template<typename T >
T | GetProperty (const std::string &key, const T &ifNotFound) const
| Read config property, return provided value if no property with this key exists. More...
auto | GetPropertyAsString (const std::string &key) const -> std::string
| Read config property as string, throw if no property with this key exists. More...
auto | GetPropertyAsString (const std::string &key, const std::string &ifNotFound) const -> std::string
| Read config property, return provided value if no property with this key exists. More...
fair::mq::Properties | GetProperties (const std::string &q) const
| Read several config properties whose keys match the provided regular expression. More...
fair::mq::Properties | GetPropertiesStartingWith (const std::string &q) const
| Read several config properties whose keys start with the provided string. More...
std::map< std::string, std::string > | GetPropertiesAsString (const std::string &q) const
| Read several config properties as string whose keys match the provided regular expression. More...
std::map< std::string, std::string > | GetPropertiesAsStringStartingWith (const std::string &q) const
| Read several config properties as string whose keys start with the provided string. More...
auto | GetChannelInfo () const -> std::unordered_map< std::string, int >
| Retrieve current channel information. More...
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
| Increases console logging severity, or sets it to lowest if it is already highest.
auto | CycleLogConsoleSeverityDown () -> void
| Decreases console logging severity, or sets it to highest if it is already lowest.
auto | CycleLogVerbosityUp () -> void
| Increases logging verbosity, or sets it to lowest if it is already highest.
auto | CycleLogVerbosityDown () -> void
| Decreases logging verbosity, or sets it to highest if it is already lowest.

## 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...

## 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
| ) |  | -> bool

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.

## DeleteProperty()

void fair::mq::PluginServices::DeleteProperty | ( | const std::string & | key | ) |

inline

Deletes a property with the given key from the config store.

Parameters

  key |

## GetChannelInfo()

auto fair::mq::PluginServices::GetChannelInfo | ( |  | ) | const -> std::unordered_map<std::string, int>

inline

Retrieve current channel information.

Returns
  a map of <channel name, number of subchannels>

## GetCurrentDeviceState()

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

inline

Returns
  current device state

## GetProperties()

fair::mq::Properties fair::mq::PluginServices::GetProperties | ( | const std::string & | q | ) | const

inline

Read several config properties whose keys match the provided regular expression.

Parameters

  q | regex string to match for

Returns
  container with properties (fair::mq::Properties as an alias for std::map<std::string, Property>, where property is boost::any)

## GetPropertiesAsString()

std::map<std::string, std::string> fair::mq::PluginServices::GetPropertiesAsString | ( | const std::string & | q | ) | const

inline

Read several config properties as string whose keys match the provided regular expression.

Parameters

  q | regex string to match for

Returns
  container with properties (fair::mq::Properties as an alias for std::map<std::string, Property>, where property is boost::any)

## GetPropertiesAsStringStartingWith()

std::map<std::string, std::string> fair::mq::PluginServices::GetPropertiesAsStringStartingWith | ( | const std::string & | q | ) | const

inline

Read several config properties as string whose keys start with the provided string.

Parameters

  q | string to match for

Returns
  container with properties (fair::mq::Properties as an alias for std::map<std::string, Property>, where property is boost::any)

Typically more performant than GetPropertiesAsString with regex

## GetPropertiesStartingWith()

fair::mq::Properties fair::mq::PluginServices::GetPropertiesStartingWith | ( | const std::string & | q | ) | const

inline

Read several config properties whose keys start with the provided string.

Parameters

  q | string to match for

Returns
  container with properties (fair::mq::Properties as an alias for std::map<std::string, Property>, where property is boost::any)

Typically more performant than GetProperties with regex

## GetProperty() [1/2]

template<typename T >

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

inline

Read config property, throw if no property with this key exists.

Parameters

  key |

Returns
  config property

## GetProperty() [2/2]

template<typename T >

T fair::mq::PluginServices::GetProperty | ( | const std::string & | key,
|  | const T & | ifNotFound
| ) |  | const

inline

Read config property, return provided value if no property with this key exists.

Parameters

  key |
  ifNotFound | value to return if key is not found

Returns
  config property

## GetPropertyAsString() [1/2]

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

inline

Read config property as string, throw if no property with this key exists.

Parameters

  key |

Returns
  config property converted to string

Supports conversion to string for a fixed set of types, for custom/unsupported types add them via `fair::mq::PropertyHelper::AddType<MyType>("optional label")` the provided type must then be convertible to string via operator<<

## GetPropertyAsString() [2/2]

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

inline

Read config property, return provided value if no property with this key exists.

Parameters

  key |
  ifNotFound | value to return if key is not found

Returns
  config property converted to string

Supports conversion to string for a fixed set of types, for custom/unsupported types add them via `fair::mq::PropertyHelper::AddType<MyType>("optional label")` the provided type must then be convertible to string via operator<<

## GetPropertyKeys()

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

inline

Discover the list of property keys.

Returns
  list of property keys

## PropertyExists()

auto fair::mq::PluginServices::PropertyExists | ( | const std::string & | key | ) | const -> bool

inline

Checks a property with the given key exist in the configuration.

Parameters

  key |

Returns
  true if it exists, false otherwise

## 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.

## SetProperties()

void fair::mq::PluginServices::SetProperties | ( | const fair::mq::Properties & | props | ) |

inline

Set multiple config properties.

Parameters

  props | fair::mq::Properties as an alias for std::map<std::string, Property>, where property is boost::any

## SetProperty()

template<typename T >

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

inline

Set config property.

Parameters

  key |
  val | 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 |

## UpdateProperties()

bool fair::mq::PluginServices::UpdateProperties | ( | const fair::mq::Properties & | input | ) |

inline

Updates multiple existing config properties (or fails of any of then do not exist, leaving property store unchanged)

Parameters

  props | (fair::mq::Properties as an alias for std::map<std::string, Property>, where property is boost::any)

## UpdateProperty()

template<typename T >

bool fair::mq::PluginServices::UpdateProperty | ( | const std::string & | key,
|  | T | val
| ) |  |

inline

Updates an existing config property (or fails if it doesn't exist)

Parameters

  key |
  val |

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

- fairmq/PluginServices.h
- fairmq/PluginServices.cxx

privacy