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

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ ChangeDeviceState()

◆ DeleteProperty()

◆ GetChannelInfo()

◆ GetCurrentDeviceState()

◆ GetProperties()

◆ GetPropertiesAsString()

◆ GetPropertiesAsStringStartingWith()

◆ GetPropertiesStartingWith()

◆ GetProperty() [1/2]

◆ GetProperty() [2/2]

◆ GetPropertyAsString() [1/2]

◆ GetPropertyAsString() [2/2]

◆ GetPropertyKeys()

◆ PropertyExists()

◆ ReleaseDeviceControl()

◆ SetProperties()

◆ SetProperty()

◆ StealDeviceControl()

◆ SubscribeToDeviceStateChange()

◆ SubscribeToPropertyChange()

◆ SubscribeToPropertyChangeAsString()

◆ TakeDeviceControl()

◆ ToDeviceState()

◆ ToDeviceStateTransition()

◆ ToStr() [1/2]

◆ ToStr() [2/2]

◆ UnsubscribeFromDeviceStateChange()

◆ UnsubscribeFromPropertyChange()

◆ UnsubscribeFromPropertyChangeAsString()

◆ UpdateProperties()

◆ UpdateProperty()