C++ API¶

The karabo::core Namespace¶

namespace karabo::core¶

Namespace for package core

Enums

enum Capabilities¶

Values:

PROVIDES_SCENES = (1u << 0)¶

PROVIDES_MACROS = (1u << 1)¶

PROVIDES_INTERFACES = (1u << 2)¶

enum Interfaces¶

Values:

Motor = (1u << 0)¶

MultiAxisMotor = (1u << 1)¶

Trigger = (1u << 2)¶

Camera = (1u << 3)¶

Processor = (1u << 4)¶

DeviceInstantiator = (1u << 5)¶

enum ServerFlags¶

Values:

DEVELOPMENT = (1u << 0)¶

Functions

const std::string karabo::core::DEFAULT_CONFIG_MANAGER_ID("KaraboConfigurationManager")

Hash initStringToAutoStartHash(const std::string &initString)¶

Variables

const int kMaxCompleteInitializationAttempts = 2500¶

class BaseDevice¶

#include <Device.hh>

The BaseDevice class provides for methods which are template independent in the Device class.

Inherits from karabo::xms::SignalSlotable

Subclassed by karabo::core::Device<>, karabo::core::Device< FSM >

Public Functions

virtual void finalizeInternalInitialization(const karabo::net::Broker::Pointer &connection, bool consumeBroadcasts, const std::string &timeServerId) = 0¶

This method is called to finalize initialization of a device. It is needed to allow user code to hook in after the base device constructor, but before the device is fully initialized.

It will typically be called by the DeviceServer. The call is blocking and afterwards communication should happen only via slot calls.

Parameters

connection: The broker connection for the device.
consumeBroadcasts: If true, listen directly to broadcast messages (addressed to ‘*’), as usually expected. Whoever sets this to false has to ensure that broadcast messages reach the Device in some other way, otherwise the device will not work correctly.
timeServerId: The id of the time server to be used by the device - usually set by the DeviceServer.

virtual void slotTimeTick(unsigned long long id, unsigned long long sec, unsigned long long frac, unsigned long long period) = 0¶

A slot called by the device server if the external time ticks update to synchronize this device with the timing system.

Parameters

id: current train id
sec: current system seconds
frac: current fractional seconds
period: interval between subsequent ids in microseconds

virtual void onTimeUpdate(unsigned long long id, unsigned long long sec, unsigned long long frac, unsigned long long period)¶

If the device receives time-server updates via slotTimeTick, this hook will be called for every id in sequential order. The time stamps (sec + frac) of subsequent ids might be identical - though they are usually spaced by period. Can be overwritten in derived classes.

Parameters

id: train id
sec: unix seconds
frac: fractional seconds (i.e. attoseconds)
period: interval between ids in microseconds

Protected Functions

virtual void onTimeTick(unsigned long long id, unsigned long long sec, unsigned long long frac, unsigned long long period)¶

A hook which is called if the device receives external time-server update, i.e. if slotTimeTick on the device server is called. Can be overwritten by derived classes.

Parameters

id: train id
sec: unix seconds
frac: fractional seconds (i.e. attoseconds)
period: interval between ids in microseconds

class BaseFsm¶

#include <BaseFsm.hh>

Karabo’s basic statemachine from which all other state machines derive.

Inherits from karabo::xms::SignalSlotable

Subclassed by karabo::core::CameraFsm, karabo::core::OkErrorFsm, karabo::core::StartStopFsm

template <typename T>

class BaseWorker¶

#include <Worker.hh>

WorkerBase class contains one queue: request and can start auxiliary thread that will run on opposite end of the queue: Main thread Queue Auxiliary thread Methods push(…) > request > receive(…)

Public Functions

BaseWorker(const std::function<void()> &callbackint timeout = -1, int repetition = -1, )¶

Construct worker with callback and time and repetition parameters

Parameters

callback: this function will be called periodically
timeout: time in milliseconds auxiliary thread is waiting on the request queue; 0 means nowait mode; ,-1 means waiting forever
repetition: -1 means cycling forever; >0 means number of cycles.

BaseWorker &set(const std::function<void()> &callbackint timeout = -1, int repetition = -1, )¶

Set parameters defining the behavior of the worker

Parameters

callback: function to be called will boolean parameter signaling repetition counter expiration
timeout: timeout for receiving from queue
repetition: repetition counter

BaseWorker &setTimeout(int timeout = -1)¶

Set parameters defining the behavior of the worker

Parameters

timeout: timeout for receiving from queue

BaseWorker &setRepetition(int repetition = -1)¶

Set parameters defining the behavior of the worker

Parameters

repetition: repetition counter

BaseWorker &start()¶: Starts auxiliary thread that works on far ends of the queues Default settings are “waiting forever” and “repeat forever”

BaseWorker &stop()¶: Stop thread activity. If “request” queue still has some entries they will be received before thread exits. After requesting a stop the new entries can not be put (just ignored) into request queue.

BaseWorker &abort()¶: This function stops thread immediately despite the fact like nonempty queue.

void join()¶: It will block until the auxiliary thread is joined.

void push(const T &t)¶

Call this function from the main thread to put new data block to the request queue

Parameters

t: data of type T to put into the request queue

Private Functions

void run()¶: Receive data block of type T from request queue. The behavior is defined by two parameters: m_timeout and m_repetition. In case of successful receiving the m_callback function will be called.

class CameraFsm¶

#include <CameraFsm.hh>

A finite state machine designed to be used for camera-type devices.

A finite state machine designed to be used for camera-type devices. It uses an ERROR-NORMAL state machine (karabo::core::OkErrorFsm type). In the NORMAL region the following state transition table is used:

ON (AcquireEvent) -> (AcquireAction) ACQUIRING ACQUIRING (StopEvent) -> (StopAction) ON ACQUIRING (TriggerEvent) -> (TriggerAction) ACQUIRING

Inherits from karabo::core::BaseFsm

template <class FSM = NoFsm>

class Device¶

#include <Device.hh>

all Karabo devices derive from this class

The Device class is the base class for all Karabo devices. It provides for a standardized set of basic properties that all devices share and provides interaction with its configuration and properties.

Devices are defined by their expected parameters; a list of properties and commands that are known to the distributed system at static time. These parameters describe a devices Schema, which in turn describes the possible configurations of the device.

Devices may come in two flavors: one’s with a full-fledged, strict finite state machine (FSM), embedded into the device through templated inheritance, and those with a simple FSM, the noFSM, where states are updated within the device logic. The Device class defaults to the latter if no template parameter is given.

Inherits from karabo::core::BaseDevice, FSM

Public Functions

Device(const karabo::util::Hash &configuration)¶

Construct a device with a given configuration. The configuration Hash may contain any of the following entries:

serverId: a string representing the server this device is running on. If not given the device assumes to run in stand-alone mode.

deviceId: a string representing this device’s id, part of the unique identifier in the distributed system. If not given it defaults to none.

Parameters

configuration:

virtual ~Device()¶: The destructor will reset the DeviceClient attached to this device.

DeviceClient &remote()¶

This function allows to communicate to other (remote) devices. Any device contains also a controller for other devices (DeviceClient) which is returned by this function.

Return: DeviceClient instance

template <class ValueType>

void set(const std::string &key, const ValueType &value)¶

Updates the state/properties of the device. This function automatically notifies any observers in the distributed system.

Parameters

key: A valid parameter of the device (must be defined in the expectedParameters function)
value: The corresponding value (of corresponding data-type)

template <class ItemType>

void setVectorUpdate(const std::string &key, const std::vector<ItemType> &updates, VectorUpdate updateType, const karabo::util::Timestamp &timestamp)¶

Concurrency safe update of vector property

Does not work for Hash (i.e. table element) due to Hash equality just checking similarity. Removing might be unreliable for VECTOR_FLOAT or VECTOR_DOUBLE due to floating point equality issues.

Parameters

key: of the vector property to update
updates: items to remove from property vector (starting at the front) or to add (at the end)
updateType: indicates update type - applied individually to all items in ‘updates’
timestamp: timestamp to assign to updated vector property (e.g. getTimestamp())

template <class ValueType>

void set(const std::string &key, const ValueType &value, const karabo::util::Timestamp &timestamp)¶

Updates the state of the device. This function automatically notifies any observers in the distributed system.

Any updates are validated against the device schema and rejected if they are not appropriate for the current device state or are of wrong type. During validation alarm bounds are evaluated and alarms on properties will be raised if alarm conditions are met. Additionally, the distributed system is notified of these alarms.

Parameters

key: A valid parameter of the device (must be defined in the expectedParameters function)
value: The corresponding value (of corresponding data-type)
timestamp: The time of the value change

void writeChannel(const std::string &channelName, const karabo::util::Hash &data)¶

Writes a hash to the specified channel. The hash internally must follow exactly the data schema as defined in the expected parameters.

If ‘data’ contains an ‘NDArray’, consider to use the overload of this method that has the ‘safeNDArray’ flag. If that flag can be set to ‘true’, data copies can be avoided:

writeChannel(channelName, data, getActualTimestamp(), true);

Thread safety: The ‘writeChannel(..)’ methods and ‘signalEndOfStream(..)’ must not be called concurrently for the same ‘channelName’.

Parameters

channelName: The output channel name
data: Hash with the data

void writeChannel(const std::string &channelName, const karabo::util::Hash &data, const karabo::util::Timestamp &timestamp, bool safeNDArray = false)¶

Writes a hash to the specified channel. The hash internally must follow exactly the data schema as defined in the expected parameters.

Thread safety: The ‘writeChannel(..)’ methods and ‘signalEndOfStream(..)’ must not be called concurrently for the same ‘channelName’.

Parameters

channelName: The output channel name
data: Hash with the data
timestamp: A user provided timestamp (if e.g. retrieved from h/w)
safeNDArray: Boolean that should be set to ‘true’ if ‘data’ contains any ‘NDArray’ and their data is not changed after this ‘writeChannel’. Otherwise, data will be copied if needed, i.e. when the output channel has to queue or serves inner-process receivers.

void signalEndOfStream(const std::string &channelName)¶

Signals an end-of-stream event (EOS) on the output channel identified by channelName Thread safety: The ‘writeChannel(..)’ methods and ‘signalEndOfStream(..)’ must not be called concurrently for the same ‘channelName’.

Parameters

channelName: the name of the output channel.

void set(const karabo::util::Hash &hash)¶

Updates the state/properties of the device with all key/value pairs given in the hash.

Any updates are validated against the device schema and rejected if they are not appropriate for the current device state or are of wrong type. During validation alarm bounds are evaluated and alarms on properties will be raised if alarm conditions are met. Additionally, the distributed system is notified of these alarms. For those paths in ‘hash’ which do not already have time stamp attributes assigned as tested by Timestamp::hashAttributesContainTimeInformation(hash.getAttributes(<path>))), the actual timestamp is chosen.

NOTE: This function will automatically and efficiently (only one message) inform any observers.

Parameters

hash: Hash of updated internal parameters (must be in current full schema, e.g. since declared in the expectedParameters function)

void set(const karabo::util::Hash &hash, const karabo::util::Timestamp &timestamp)¶

Updates the state of the device with all key/value pairs given in the hash

Any updates are validated against the device schema and rejected if they are not appropriate for the current device state or are of wrong type. During validation alarm bounds are evaluated and alarms on properties will be raised if alarm conditions are met. Additionally, the distributed system is notified of these alarms.

NOTE: This function will automatically and efficiently (only one message) inform any observers.

Parameters

hash: Hash of updated internal parameters (must be in current full schema, e.g. since declared in the expectedParameters function)
timestamp: to indicate when the set occurred - but is ignored for paths in ‘hash’ that already have time stamp attributes as tested by Timestamp::hashAttributesContainTimeInformation(hash.getAttributes(<path>)))

template <class ValueType>

void setNoValidate(const std::string &key, const ValueType &value)¶

Updates the state of the device with all key/value pairs given in the hash. In contrast to the set function, no validation is performed.

Parameters

key: identifying the property to update
value: updated value

template <class ValueType>

void setNoValidate(const std::string &key, const ValueType &value, const karabo::util::Timestamp &timestamp)¶

Updates the state of the device with all key/value pairs given in the hash. In contrast to the set function, no validation is performed.

Parameters

key: identifying the property to update
value: updated value
timestamp: optional timestamp to indicate when the set occurred.

void setNoValidate(const karabo::util::Hash &hash)¶

Updates the state of the device with all key/value pairs given in the hash. In contrast to the set function, no validation is performed.

NOTE: This function will automatically and efficiently (only one message) inform any observers.

Parameters

config: Hash of updated internal parameters (must be declared in the expectedParameters function)

void setNoValidate(const karabo::util::Hash &hash, const karabo::util::Timestamp &timestamp)¶

Updates the state of the device with all key/value pairs given in the hash. In contrast to the set function, no validation is performed.

NOTE: This function will automatically and efficiently (only one message) inform any observers.

Parameters

config: Hash of updated internal parameters (must be declared in the expectedParameters function)
timestamp: optional timestamp to indicate when the set occurred.

template <class T>

T get(const std::string &key) const¶

Retrieves the current value of any device parameter (that was defined in the expectedParameters function)

Return

value of the requested parameter

Parameters

key: A valid parameter of the device (must be defined in the expectedParameters function)

template <class T>

T getAs(const std::string &key) const¶

Retrieves the current value of any device parameter (that was defined in the expectedParameters function) The value is casted on the fly into the desired type. NOTE: This function is considerably slower than the simple get() functionality

Return

value of the requested parameter

Parameters

key: A valid parameter of the device (must be defined in the expectedParameters function)

karabo::util::Schema getFullSchema() const¶

Retrieves all expected parameters of this device

Return: Schema object containing all expected parameters

void appendSchema(const karabo::util::Schema &schema, const bool = false)¶

Append a schema to the existing device schema

Parameters

schema: to be appended - may also contain existing elements to overwrite their attributes like min/max values/sizes, alarm ranges, etc. If it contains Input-/OutputChannels, they are (re-)created. If previously an InputChannel existed under the same key, its data/input/endOfStream handlers are kept for the recreated InputChannel.
unused: parameter, kept for backward compatibility.

void updateSchema(const karabo::util::Schema &schema, const bool = false)¶

Replace existing schema descriptions by static (hard coded in expectedParameters) part and add additional (dynamic) descriptions. Previous additions will be removed.

Parameters

schema: additional, dynamic schema - may also contain existing elements to overwrite their attributes like min/max values/sizes, alarm ranges, etc. If it contains Input-/OutputChannels, they are (re-)created (and previously added ones removed). If previously an InputChannel existed under the same key, its data/input/endOfStream handlers are kept for the recreated InputChannel.
unused: parameter, kept for backward compatibility.

template <class AliasType>

AliasType getAliasFromKey(const std::string &key) const¶

Converts a device parameter key into its aliased key (must be defined in the expectedParameters function)

Return

Aliased representation of the parameter

Parameters

key: A valid parameter of the device (must be defined in the expectedParameters function)

template <class AliasType>

std::string getKeyFromAlias(const AliasType &alias) const¶

Converts a device parameter alias into the original key (must be defined in the expectedParameters function)

Return

The original name of the parameter

Parameters

key: A valid parameter-alias of the device (must be defined in the expectedParameters function)

template <class T>

const bool aliasHasKey(const T &alias) const¶

Checks if the argument is a valid alias of some key, i.e. defined in the expectedParameters function

Return

true if it is an alias found in one of three containers of parameters: “reconfigurable”, “initial” or “monitored”, otherwise false

Parameters

alias: Arbitrary argument of arbitrary type

bool keyHasAlias(const std::string &key) const¶

Checks if some alias is defined for the given key

Return

true if the alias exists

Parameters

key: in expectedParameters mapping

karabo::util::Types::ReferenceType getValueType(const std::string &key) const¶

Checks the type of any device parameter (that was defined in the expectedParameters function)

Return

The enumerated internal reference type of the value

Parameters

key: A valid parameter of the device (must be defined in the expectedParameters function)

karabo::util::Hash getCurrentConfiguration(const std::string &tags = "") const¶

Retrieves the current configuration. If no argument is given, all parameters (those described in the expected parameters section) are returned. A subset of parameters can be retrieved by specifying one or more tags.

Return

A Hash containing the current value of the selected configuration

Parameters

tags: The tags (separated by comma) the parameter must carry to be retrieved

karabo::util::Hash getCurrentConfigurationSlice(const std::vector<std::string> &paths) const¶

Retrieves a slice of the current configuration.

Return

Hash with the current values and attributes (e.g. timestamp) of the selected configuration

Parameters

paths: of the configuration which should be returned (as declared in expectedParameters) (method throws ParameterExcepton if a non-existing path is given)

karabo::util::Hash filterByTags(const karabo::util::Hash &hash, const std::string &tags) const¶

Return a tag filtered version of the input Hash. Tags are as defined in the device schema

Return

a filtered version of the input Hash.

Parameters

hash: to filter
tags: to filter by

const std::string &getServerId() const¶

Return the serverId of the server this device is running on

Return

const karabo::util::State getState()¶

Return a State object holding the current unified state of the device.

Return

void updateState(const karabo::util::State &currentState)¶

Update the state of the device, using “actual timestamp”.

Will also update the instanceInfo describing this device instance (if new or old State are ERROR).

Parameters

currentState: the state to update to

void updateState(const karabo::util::State &currentState, const karabo::util::Hash &other)¶

Update the state of the device, using “actual timestamp”.

Will also update the instanceInfo describing this device instance (if new or old State are ERROR).

Parameters

currentState: the state to update to
other: a Hash to set other properties in the same state update message, time stamp attributes to its paths have precedence over the actual timestamp

void updateState(const karabo::util::State &currentState, const karabo::util::Timestamp &timestamp)¶

Update the state of the device, using given timestamp.

Will also update the instanceInfo describing this device instance (if new or old State are ERROR).

Parameters

currentState: the state to update to
timestamp: time stamp to assign to the state property and the properties in ‘other’ (if the latter do not have specified timestamp attributes)

void updateState(const karabo::util::State &currentState, karabo::util::Hash other, const karabo::util::Timestamp &timestamp)¶

Update the state of the device, using given timestamp.

Will also update the instanceInfo describing this device instance (if new or old State are ERROR).

Parameters

currentState: the state to update to
other: a Hash to set other properties in the same state update message, time stamp attributes to its paths have precedence over the given ‘timestamp’
timestamp: time stamp to assign to the state property and the properties in ‘other’ (if the latter do not have specified timestamp attributes)

KARABO_DEPRECATED void karabo::core::Device::exceptionFound(const std::string & shortMessage, const std::string & detailedMessage) const

You can override this function to handle default caught exceptions differently

Parameters

shortMessage: short error message
detailedMessage: detailed error message

void execute(const std::string &command) const¶

Execute a command on this device

Parameters

command:

template <class A1>

void execute(const std::string &command, const A1 &a1) const¶

Execute a command with one argument on this device

Parameters

command:
a1:

template <class A1, class A2>

void execute(const std::string &command, const A1 &a1, const A2 &a2) const¶

Execute a command with two arguments on this device

Parameters

command:
a1:
a2:

template <class A1, class A2, class A3>

void execute(const std::string &command, const A1 &a1, const A2 &a2, const A3 &a3) const¶

Execute a command with three arguments on this device

Parameters

command:
a1:
a2:
a3:

template <class A1, class A2, class A3, class A4>

void execute(const std::string &command, const A1 &a1, const A2 &a2, const A3 &a3, const A4 &a4) const¶

Execute a command with four arguments on this device

Parameters

command:
a1:
a2:
a3:
a4:

karabo::util::AlarmCondition getAlarmCondition() const¶

Get the current alarm condition the device is in

Return

void setAlarmCondition(const karabo::util::AlarmCondition &condition, bool needsAcknowledging = false, const std::string &description = std::string())¶

Set the global alarm condition

Parameters

condition: to set
needsAcknowledging: if this condition will require acknowledgment on the alarm service
description: an optional description of the condition. Consider including remarks on how to resolve

const karabo::util::AlarmCondition &getAlarmCondition(const std::string &key, const std::string &sep = ".") const¶

Get the alarm condition for a specific property

Return

the alarm condition of the property

Parameters

key: of the property to get the condition for
sep: optional separator to use in the key path

bool hasRollingStatistics(const std::string &path) const¶

Query if the property at path has rolling statistics enabled

Return

Parameters

path:

karabo::util::RollingWindowStatistics::ConstPointer getRollingStatistics(const std::string &path) const¶

Get a pointer to the rolling statistics for the property at path

Return

a pointer to the rolling statistics object keeping track of the statistics for the property identified by path.

Parameters

path:

void slotTimeTick(unsigned long long id, unsigned long long sec, unsigned long long frac, unsigned long long period)¶

A slot called by the device server if the external time ticks update to synchronize this device with the timing system.

Parameters

id: current train id
sec: current system seconds
frac: current fractional seconds
period: interval between subsequent ids in microseconds

void appendSchemaMaxSize(const std::string &path, unsigned int value, bool emitFlag = true)¶

Append Schema to change/set maximum size information for path - if paths does not exist, throw exception

This is similar to the more general appendSchema, but dedicated to a common use case.

Caveat: This does not recreate an output channel if its schema is changed

Parameters

path: indicates the parameter which should be a Vector- or TableElement
value: is the new maximum size of the parameter
emitFlag: indicates if others should be informed about this Schema update. If this method is called for a bunch of paths, it is recommended to set this to true only for the last call.

Public Static Functions

static void expectedParameters(karabo::util::Schema &expected)¶

The expected parameter section of the Device class, known at static time. The basic parameters described here are available for all devices, many of them being expert or admin visible only.

Parameters

expected: a Schema to which these parameters will be appended.

Protected Functions

karabo::util::Timestamp getActualTimestamp() const¶

Returns the actual timestamp. The Trainstamp part of Timestamp is extrapolated from the last values received via slotTimeTick (or zero if no time ticks received yet). To receive time ticks, the server of the device has to be connected to a time server.

Return: the actual timestamp

karabo::util::Timestamp getTimestamp(const karabo::util::Epochstamp &epoch) const¶

Returns the Timestamp for given Epochstamp. The Trainstamp part of Timestamp is extrapolated forward or backward from the last values received via slotTimeTick (or zero if no time ticks received yet). To receive time ticks, the server of the device has to be connected to a time server.

Return

the matching timestamp, consisting of epoch and the corresponding Trainstamp

Parameters

epoch: for that the time stamp is searched for

Private Functions

void setNoLock(const karabo::util::Hash &hash, const karabo::util::Timestamp &timestamp)¶: Internal method for set(Hash, Timestamp), requiring m_objectStateChangeMutex to be locked

void setNoValidateNoLock(const karabo::util::Hash &hash, const karabo::util::Timestamp &timestamp)¶: Internal version of setNoValidate(hash, timestamp) that requires m_objectStateChangeMutex to be locked

void finalizeInternalInitialization(const karabo::net::Broker::Pointer &connection, bool consumeBroadcasts, const std::string &timeServerId)¶

This function will typically be called by the DeviceServer. The call is blocking and afterwards communication should happen only via slot calls.

Parameters

connection: The broker connection for the device.
consumeBroadcasts: If false, do not listen directly to broadcast messages (addressed to ‘*’). Whoever sets this to false has to ensure that broadcast messages reach the Device in some other way.
timeServerId: The id of the time server to be used by the device - usually set by the DeviceServer.

void initChannels(const karabo::util::Schema &schema, const std::string &topLevel = "")¶

Called to setup pipeline channels, will recursively go through the given schema, assuming it to be at least a part of the schema of the device. Needs to be called with m_objectStateChangeMutex being locked.

Parameters
- schema: the schema to traverse
Parameters
- topLevel: std::string: empty or existing path of full
schema of the device

void prepareOutputChannel(const std::string &path)¶

Create OutputChannel for given path and take care to set handlers needed Needs to be called with m_objectStateChangeMutex being locked.

Parameters

path:

void prepareInputChannel(const std::string &path)¶

Create InputChannel for given path and take care to set handlers needed Needs to be called with m_objectStateChangeMutex being locked.

Parameters

path:

void slotCallGuard(const std::string &slotName, const std::string &callee)¶

This function is called by SignalSlotable to verify if a slot may be called from remote. The function only checks slots that are mentioned in the expectedParameter section (“DeviceSlots”) The following checks are performed:

Parameters

slotName: name of the slot
callee: the calling remote, can be unknown

1) Is this device locked by another device? If the lockedBy field is non-empty and does not match the callee’s instance id, the call will be rejected

2) Is the slot callable from the current state, i.e. is the current state specified as an allowed state for the slot.

void slotUpdateSchemaAttributes(const std::vector<karabo::util::Hash> &updates)¶

Updates attributes in the device’s runtime schema. reply is of the form Hash(“success” bool, “instanceId”, str, “updatedSchema”, Schema, “requestedUpdate”, vector<Hash>) where success indicates a successful update, instanceId the device that performed the update updatedSchema the new valid schema, regardless of success or not, and requestedUpdates the original update request, as received through onUpdateAttributes

Parameters

updates: updated attributes, expected to be of form Hash(“instanceId”, str, “updates”, vector<Hash>) where each entry in updates is of the form Hash(“path”, str, “attribute”, str, “value”, valueType)

void slotClearLock()¶: Clear any lock on this device

karabo::util::Hash getTimeInfo()¶: Internal method to retrieve time information of this device.

void slotGetTime(const karabo::util::Hash&)¶

Returns the actual time information of this device.

This slot reply is a Hash with the following keys:

time and its attributes provide an actual timestamp with train Id information.
timeServerId the id of the time server configured for the DeviceServer of this device; “None” when there’s no time server configured.
reference and its attributes provide the latest timestamp information received from the timeserver.

Parameters

info: an unused (at least for now) Hash parameter that has been added to fit the generic slot call (Hash in, Hash out) of the GUI server/client protocol.

void slotGetSystemInfo(const karabo::util::Hash&)¶

Returns the actual system information of this device.

This slot reply is a Hash with the following keys:

user the actual user running this device
broker the current connected broker node

Parameters

info: an unused (at least for now) Hash parameter that has been added to fit the generic slot call (Hash in, Hash out) of the GUI server/client protocol.

and all keys provided by slotGetTime.

Private Members

karabo::util::Validator m_validatorIntern¶: Validators to validate…

karabo::util::Validator m_validatorExtern¶: …internal updates via ‘Device::set’

std::shared_ptr<DeviceClient> m_deviceClient¶: …external updates via ‘Device::slotReconfigure’

class DeviceClient¶

#include <DeviceClient.hh>

This class can be used to (remotely) control devices of the distributed system Synchronous calls (i.e. get()) are in fact asynchronous under the hood.

The Karabo DeviceClient provides a high-level interface for common calls to (remote) devices in the distributed system. In principle functionality implemented in the DeviceClient can be fully implemented in the Device using low level SignalSlotable calls alone, but device developers are discouraged from this approach, especially if synchronous behavior is acceptable or even desired.

In the context of a Device the DeviceClient is available using the Device::remote() function; it then shares the SignalSlotable instance of the device, e.g. there is no instantiation overhead.

Inherits from std::enable_shared_from_this< DeviceClient >

Public Functions

DeviceClient(const std::string &instanceId = std::string(), bool implicitInit = true, const karabo::util::Hash &serviceDeviceIds = karabo::util::Hash())¶

Constructor which establishes an own connection to the communication system. This constructor is intended for stand-alone C++ device clients. Once we care about authentication, this has to be added here.

Parameters

instanceId: The id with which the client should participate in the system. If not unique or invalid, constructor will throw an exception. If empty (i.e. default), an id will be generated from host name and process id.
implicitInit: If true (default for backward compatibility - but NOT recommended!), the constructor will implicitly try to trigger a call to initialize() via the event loop. Since this can fail silently, it is strongly recommended to use implicitInit = false and call the initialize() method right after the constructor.
serviceDeviceIds: A hash with ids of core service devices; e.g, “dataLoggerManagerId” key and the value is the name of the DataLoggerManager the device client instance should use for data logging operations. Currently keys “dataLoggerManagerId” and “configurationManagerId” are supported.

DeviceClient(const std::shared_ptr<karabo::xms::SignalSlotable> &signalSlotable, bool implicitInit = true, const karabo::util::Hash &serviceDeviceIds = karabo::util::Hash())¶

Constructor using instantiated signalSlotable object (shared communication - take care that the signalSlotable is kept alive since the DeviceClient will only keep a weak pointer)

Parameters

signalSlotable: An instance of the SignalSlotable lass
implicitInit: If true (default for backward compatibility - but NOT recommended!), the constructor will implicitly try to trigger a call to initialize() via the event loop. Since this can fail silently, it is strongly recommended to use implicitInit = false and call the initialize() method right after the constructor.
serviceDeviceIds: A hash with ids of core service devices; e.g, “dataLoggerManagerId” key and the value is the name of the DataLoggerManager the device client instance should use for data logging operations. Currently keys “dataLoggerManagerId” and “configurationManagerId” are supported.

DeviceClient(const std::string &instanceId, const karabo::util::Hash &serviceDeviceIds)¶

Constructor aimed at cases where a specific DataLoggerManagerId is required. Requires an explicit call to DeviceClient::initialize() after the construction takes place.

Parameters

instanceId: The id with which the client should participate in the system. If not unique or invalid, constructor will throw an exception. If empty, an id will be generated from host name and process id.
serviceDeviceIds: A hash with ids of core service devices; e.g, “dataLoggerManagerId” key and the value is the name of the DataLoggerManager the device client instance should use for data logging operations. Currently keys “dataLoggerManagerId” and “configurationManagerId” are supported.

DeviceClient(const std::shared_ptr<karabo::xms::SignalSlotable> &signalSlotable, const karabo::util::Hash &serviceDeviceIds)¶

Constructor using instantiated signalSlotable object (shared communication - take care that the signalSlotable is kept alive since the DeviceClient will only keep a weak pointer) and aimed at cases where a specific DataLoggerManagerId is required. Requires an explicit call to DeviceClient::initialize() after the construction takes place.

Parameters

signalSlotable: An instance of the SignalSlotable lass
serviceDeviceIds: A hash with ids of core service devices; e.g, “dataLoggerManagerId” key and the value is the name of the DataLoggerManager the device client instance should use for data logging operations. Currently keys “dataLoggerManagerId” and “configurationManagerId” are supported.

void initialize()¶: Second constructor. It is strongly recommended to use the constructors with implicitInit = false and explicitely call initialize() after the construction.

const std::string &getInstanceId()¶: InstanceId of underlying communication object (i.e. SignalSlotable)

void setInternalTimeout(const unsigned int internalTimeout)¶

Sets the internal timeout for any request/response like communications

Parameters

internalTimeout: The default timeout in ms

int getInternalTimeout() const¶

Retrieves the currently set internal timeout

Return: default timeout in ms

void setAgeing(bool toggle)¶

Set ageing on or off (on by default)

Return

void setDeviceMonitorInterval(long int milliseconds)¶: Set interval to wait between subsequent (for the same instance) calls to handlers registered via registerDeviceMonitor. Changes received within that interval will be cached and, in case of several updates of the same property within the interval, only the most up-to-date value will be handled. If negative, switch off caching and call handler immediately.

std::pair<bool, std::string> exists(const std::string &instanceId)¶

Allows asking whether an instance is online in the current distributed system

Return

Parameters

boolean: indicating whether existing and hostname if exists

void enableInstanceTracking()¶

Enables tracking of new and departing device instances

The handlers registered with registerInstance[New|Gone|Updated]Monitor will be called accordingly. If the handler for instanceNew is registered before calling this method, it will be called for each device currently in the system.

NOTE: Use wisely! There is a performance cost to tracking all devices since it means subscribing to the heartbeats of all servers and devices in the system.

Hash getSystemInformation()¶

Returns the full information about the current (runtime) distributed system

Return: a Hash containing the full system description

Hash getSystemTopology()¶

Returns only the topology of the current system (no instance configurations or descriptions)

Return: Hash containing the topology of the runtime system

std::vector<std::string> getServers()¶

Retrieves all servers currently existing in the distributed system

Return: array of server ids

std::vector<std::string> getClasses(const std::string &deviceServer)¶

Retrieves all device classes (plugins) available on a given device server

Return

array of device classes

Parameters

deviceServer: device server id

std::vector<std::string> getDevices(const std::string &deviceServer)¶

Retrieves all devices (instances) available on a given device server

Return

array of device instanceIds

Parameters

deviceServer: device server id

std::vector<std::string> getDevices()¶

Retrieves all devices in the distributed system.

Return: array of device instanceIds

karabo::util::Schema getDeviceSchema(const std::string &instanceId)¶

Retrieves the full Schema (parameter description) of the given instance;

Return

full Schema

Parameters

instanceId: Device’s instance ID

karabo::util::Schema getDeviceSchemaNoWait(const std::string &instanceId)¶

Retrieves the full Schema (parameter description) of the given instance The call is non-blocking, if no Schema is currently available the return will be empty. However, the schema request will be sent and should lead to later arrival of a schema.

Return

full Schema

Parameters

instanceId: Device’s instance ID

karabo::util::Schema getActiveSchema(const std::string &instanceId)¶

Retrieves the currently active Schema (filtered by allowed states and allowed roles) of the given instance

Return

active Schema

Parameters

instanceId: Device’s instance ID

karabo::util::Schema getClassSchema(const std::string &serverId, const std::string &classId)¶

Retrieves a schema from static context of a loaded Device class plug-in. This schema represents a description of parameters possible to configure for instantiation. I.e. returns in fact a description of the constructor arguments to that device class.

Return

Schema describing parameters available at instantiation time

Parameters

serverId: instanceId of a deviceServer
classId: name of loaded class on the deviceServer (classId)

karabo::util::Schema getClassSchemaNoWait(const std::string &serverId, const std::string &classId)¶

Retrieves a schema from static context of a loaded Device class plug-in. This schema represents a description of parameters possible to configure for instantiation. This function can be used to pre-cache a schema for later usage. It returns an empty schema.

Return

an empty schem

Parameters

serverId: instanceId of a deviceServer
classId: name of loaded class on the deviceServer (classId)

std::vector<std::string> getProperties(const std::string &deviceId)¶

Retrieve the properties of a device at deviceId.

Return

a vector containing the property paths of the device

Parameters

deviceId: of the device to request information from

std::vector<std::string> getClassProperties(const std::string &serverId, const std::string &classId)¶

Retrieve the properties of a class loaded on a server

Return

vector containing the property paths of the class

Parameters

serverId: server to request information from
classId: of the class

std::vector<std::string> getCurrentlyExecutableCommands(const std::string &instanceId)¶

Retrieve a list of commands that may be currently executed on a device in the distributed system. Available commands are determined by device state and access rights.

Return

a vector containing the slot names of the commands that can be executed

Parameters

instanceId: of the device to ask for available commands

std::vector<std::string> getCurrentlySettableProperties(const std::string &instanceId)¶

Retrieve a list of properties that may be currently altered on a device in the distributed system. Available properties are determined by device state and access rights.

Return

a vector containing the slot names of the properties that can be altered.

Parameters

instanceId: of the device to ask for settable properties

Hash loadConfigurationFromFile(const std::string &filename)¶

Load a device configuration from a file

Return

a Hash containing the configuration

Parameters

filename:

std::pair<bool, std::string> instantiate(const std::string &serverInstanceId, const std::string &classId, const karabo::util::Hash &configuration = karabo::util::Hash(), int timeoutInSeconds = -1)¶

Attempt to instantiate a device of the specified class, on a remote server with a given initial configuration

Return

(ok, reply) pair where ok is true if no exception occurred and reply is the answer received from server

Parameters

serverInstanceId: of the server to instantiate the device on. Needs to have the device plugin available
classId: of the device to be instantiate
configuration: Hash which contains the initial device configuration. It must have one out of the two following forms: option 1:
- key “classId” pointing to a string, option 2:
- no classId specified: class id to be instantiated is taken from classId parameter option 3 (for backward compatibility - not recommended):
- a single key (e.g. “myClassId”) representing the classId
- the value for this key is a Hash with all the non-default properties
timeoutInSeconds: by default set to -1, which means block indefinitely, if a positive value an Exception is thrown if the device hasn’t been instantiated.

std::pair<bool, std::string> instantiate(const std::string &serverInstanceId, const karabo::util::Hash &configuration, int timeoutInSeconds = -1)¶

Instantiate a device on a remote server

Return

Parameters

serverInstanceId: of the server to instantiate the device on. Needs to have the device plugin available
configuration: Hash which contains the initial device configuration. The ‘classId’ attribute must be present.
timeoutInSeconds: by default set to -1, which means block indefinitely, if a positive value an Exception is thrown if the device hasn’t been instantiated.

Hash formatConfigToInstantiate(const std::string &classId, const karabo::util::Hash &configuration)¶

Utility method that takes care of adding classId to configuration of device to be instantiated by instantiate and instantiateNoWait. If configuration does not have ‘classId’ key, this is added, with the value of classId parameter. Otherwise the configuration ‘classId’ value is used. In the latter case, if the value of classId parameter mismatches the one of ‘classId’ attribute of configuration a warning is thrown.

Return

configuration ready to be sent to device server

Parameters

classId: of the device to be instantiated.
configuration: of the device to be instantiated.

void instantiateNoWait(const std::string &serverInstanceId, const std::string &classId, const karabo::util::Hash &configuration = karabo::util::Hash())¶

Instantiate a device on a remote server. In contrast to DeviceClient::instantiate, this function returns immediately.

Parameters

serverInstanceId: of the server to instantiate the device on. Needs to have the device plugin available
classId: of the device to be instantiate
configuration: Hash which contains the initial device configuration. It must have one out of the two following forms: option 1:
- key “classId” pointing to a string, option 2:
- no classId specified: class id to be instantiated is taken from classId parameter option 3 (for backward compatibility - not recommended):
- a single key (e.g. “myClassId”) representing the classId
- the value for this key is a Hash with all the non-default properties

void instantiateNoWait(const std::string &serverInstanceId, const karabo::util::Hash &configuration)¶

Instantiate a device on a remote server. In contrast to DeviceClient::instantiate, this function returns immediately.

Return

Parameters

serverInstanceId: of the server to instantiate the device on. Needs to have the device plugin available
configuration: Hash which contains the initial device configuration. The ‘classId’ attribute must be present.

std::pair<bool, std::string> killDevice(const std::string &deviceId, int timeoutInSeconds = -1)¶

Kill a device in the distributed system and wait until it is actually dead

Return

Parameters

deviceId: of the device to kill
timeoutInSeconds: timeoutInSeconds by default set to -1, which means block indefinitely, if a positive value an Exception is thrown if the device hasn’t been killed.

void killDeviceNoWait(const std::string &deviceId)¶

Kill a device in the distributed system and return immediately

Return

Parameters

deviceId: of the device to kill

std::pair<bool, std::string> killServer(const std::string &serverId, int timeoutInSeconds = -1)¶

Kill a device server in the distributed system and all its associated devices. Waits til the server is dead.

Return

Parameters

serverId: of the server to kill
timeoutInSeconds: timeoutInSeconds timeoutInSeconds by default set to -1, which means block indefinitely, if a positive value an Exception is thrown if the device server hasn’t been killed.

void killServerNoWait(const std::string &serverId)¶

Kill a device server in the distributed system and all its associated devices. Returns immediately.

Return

Parameters

serverId: of the server to kill

karabo::util::Hash get(const std::string &instanceId)¶

Return the configuration Hash of an instance. The configuration is internally cached, so it does not necessarily result in a query to the distributed system if the device configuration has not changed since the last query.

Return

a Hash holding the instance configuration

Parameters

instanceId: for which to return the configuration of

void get(const std::string &instanceId, karabo::util::Hash &hash)¶

Return the configuration Hash of an instance. The configuration is internally cached, so it does not necessarily result in a query to the distributed system if the device configuration has not changed since the last query.

Parameters

instanceId: for which to return the configuration of
hash: reference to write configuration into

karabo::util::Hash getConfigurationNoWait(const std::string &deviceId)¶

Return the cached configuration if it is still valid, otherwise query an updated version but return an empty Hash.

Return

a Hash holding the instance configuration

Parameters

deviceId: for which to return the configuration of

bool hasAttribute(const std::string &instanceId, const std::string &key, const std::string &attribute, const char keySep = util::Hash::k_defaultSep)¶

Check if an attribute exists for a property on a given instance

Return

a boolean indicating if the attribute is present

Parameters

instanceId: to check on
key: path to the property to check if it has a given attribute
attribute: to check for
keySep: path separator

template <class T>

T get(const std::string &instanceId, const std::string &key, const char keySep = util::Hash::k_defaultSep)¶

Return a property from a remote instance. The instance configuration is internally cached, so it does not necessarily result in a query to the distributed system if the device configuration has not changed since the last query.

Return

the current property value on the remote device TypeException if the templated type does not match the property type.

Parameters

instanceId: to retrieve the property from
key: identifying the property
keySep: path separator

template <class T>

void get(const std::string &instanceId, const std::string &key, T &value, const char keySep = util::Hash::k_defaultSep)¶

Return a property from a remote instance. The instance configuration is internally cached, so it does not necessarily result in a query to the distributed system if the device configuration has not changed since the last query.

Parameters

instanceId: to retrieve the property from
key: identifying the property
value: reference to write the property value to
keySep: path separator TypeException if the templated type does not match the property type.

template <class T>

T getAs(const std::string &instanceId, const std::string &key, const char keySep = util::Hash::k_defaultSep)¶

Return a property from a remote instance casted to the template type. The instance configuration is internally cached, so it does not necessarily result in a query to the distributed system if the device configuration has not changed since the last query.

Return

the current property value on the remote device TypeException if the property cannot be casted to the template type

Parameters

instanceId: to retrieve the property from
key: identifying the property
keySep: path separator

std::any getAsAny(const std::string &instanceId, const std::string &key, const char keySep = util::Hash::k_defaultSep)¶

Return a property from a remote instance as a std::any value. The instance configuration is internally cached, so it does not necessarily result in a query to the distributed system if the device configuration has not changed since the last query.

Return

the current property value on the remote device as std::any type

Parameters

instanceId: to retrieve the property from
key: identifying the property
keySep: path separator

bool cacheLoggerMap(bool toggle)¶

Toggles caching of the DataLogger map on (true) and off (false). If set to true the logger map is always kept up to date, which speeds up repeated calls to DeviceClient::getProperyHistory.

Return

true if operation was successful

Parameters

toggle:

std::vector<karabo::util::Hash> getFromPast(const std::string &deviceId, const std::string &key, const std::string &from, std::string to = "", int maxNumData = 0)¶

Returns the history of a device property for a given period of time

Return

a vector of Hashes holding the property’s history. Each entry consists of a Hash with a key “v” holding the value of the appropriate type. For each entry “v” Karabo train and timestamp attributes are set which can be retrieved using the karabo::util::Timestamp::fromHashAttributes method.

Parameters

deviceId: of the device holding the property
key: path to the property on the device
from: karabo::util::Epochstamp in Iso8601 format signifying the start of the time interval to get the history from
to: karabo::util::Epochstamp in Iso8601 format signifying the end of the time interval to get the history from. If left empty default to now
maxNumData: maximum number of data points to retrieve, starting from the start of the interval

std::vector<karabo::util::Hash> getPropertyHistory(const std::string &deviceId, const std::string &key, const std::string &from, std::string to = "", int maxNumData = 0)¶

Returns the history of a device property for a given period of time

Return

a vector of Hashes holding the property’s history. Each entry consists of a Hash with a key “v” holding the value of the appropriate type. For each entry “v” Karabo train and timestamp attributes are set which can be retrieved using the karabo::util::Timestamp::fromHashAttributes method.

Parameters

deviceId: of the device holding the property
key: path to the property on the device
from: karabo::util::Epochstamp in Iso8601 format signifying the start of the time interval to get the history from
to: karabo::util::Epochstamp in Iso8601 format signifying the end of the time interval to get the history from. If left empty default to now
maxNumData: maximum number of data points to retrieve, starting from the start of the interval

std::string getDataLogReader(const std::string &deviceId)¶

Returns instanceId of data log reader for data of given device. Could be empty.

Return

Parameters

deviceId:

std::pair<karabo::util::Hash, karabo::util::Schema> getConfigurationFromPast(const std::string &deviceId, const std::string &timepoint)¶

Returns the device configuration and corresponding schema for a given point in time. Information for the nearest matching logged time is returned.

Return

a pair of the configuration Hash and corresponding device Schema

Parameters

deviceId: of the device to return the configuration for
timepoint: to return information for. Should be an iso8601 formatted string.

karabo::util::Hash listConfigurationFromName(const std::string &deviceId, const std::string &namePart = "")¶

Returns the configurations saved for a device under names that contain a given name part.

Return

a hash with the operation execution status and the list of configuration(s) and schema(s) in case of success. For the operation execution status, the returned hash has the keys “success” with a boolean value that indicates whether the the operation was successful and a key “reason” with a string value that will contain the reason for failure or will be empty in the case of success. The returned hash will also have a key “configs” whose value will be a vector of hashes with data about the configs that match the name part. If no configuration is saved for the device under a name that contains the namePart, the “configs” vector will be empty. Each hash in the “configs” vector contains the keys “name”, “timepoint”, “description”, “priority” and “user”. The configuration itself and its corresponding schema are not returned by this method.

Parameters

deviceId: of the device whose named configuration(s) and schema(s) should be returned.
namePart: of the device configuration(s) and schema(s) to be returned. An empty namePart means returns all the named configuration(s) and schema(s)

karabo::util::Hash getConfigurationFromName(const std::string &deviceId, const std::string &name)¶

Returns the configuration and schema saved for a device under a given name.

Return

a hash with the operation execution status and the device configuration and schema in case of success. For the operation execution status, the returned hash has the keys “success” with a boolean value that indicates whether the the operation was successful and a key “reason” with a string value that will contain the reason for failure or will be empty in the case of success. The returned hash will also have a key “config” whose value will be a hash with the keys “name”, “timepoint”, “description”, “priority”, “user”, “config” and “schema” when a device configuration with the given name is found or an empty hash in case of failure or when no device configuration with the given name exists.

Parameters

deviceId: of the device whose named configuration and schema should be returned.
name: of the device configuration and schema to be returned.

karabo::util::Hash getLastConfiguration(const std::string &deviceId, int priority = 1)¶

Returns the most recently saved configuration for a device that has a given priority.

Return

a hash with the operation execution status and the device configuration and schema in case of success. For the operation execution status, the returned hash has the keys “success” with a boolean value that indicates whether the the operation was successful and a key “reason” with a string value that will contain the reason for failure or will be empty in the case of success. The returned hash will also have a key “config” whose value will be a hash with the keys “name”, “timepoint”, “description”, “priority”, “user”, “config” and “schema” when a device configuration with the given priority is found or an empty hash in case of failure or when no device configuration with the given priority exists.

Parameters

deviceId: of the device whose named configuration and schema should be returned.
priority: of the device configuration and schema to be returned.

std::pair<bool, std::string> saveConfigurationFromName(const std::string &name, const std::vector<std::string> &deviceIds, const std::string &description = std::string(), int priority = 1, const std::string &user = ".")¶

Saves a collection of current device configurations (and the corresponding schemas) in the configuration database under a common name, user, priority and description.

Return

a pair with a success flag (true when the operation succeeds) in the first position and a reason failture description (empty in case of success) in the second position.

Parameters

name: to be assigned to the saved collection of device configurations (with schemas).
deviceIds: the devices whose current configurations (and schemas) are to be saved.
description: the description for the collection of saved configurations.
priority: the priority of the configurations saved (value between 1 and 3). An invalid value leads to an operation failure.
user: the user that requested the operation (“.” means anonymous).

void registerInstanceChangeMonitor(const InstanceChangeThrottler::InstanceChangeHandler &callBackFunction, unsigned int throttlerIntervalMs = 500u, unsigned int maxChangesPerCycle = 100u)¶

Register a throttled callback handler to be triggered when a new device instance appears, updates its instance info record or goes away in the distributed system. The throtter that dispatches the instance changes events to the handler uses a given interval between its running cycles.

Parameters

callBackFunction: Function to be invoked with information about the instances changes events.
throttlerInterval: Interval, in milliseconds, between successive cycles of the throttle.
maxChangesPerCycle: Maximum number of instance changes to be dispatched per cycle of the throttler
- upon reaching this limit the throttler immediately dispatches the changes, despite the elapsed time from the last cycle.

void flushThrottledInstanceChanges()¶: Flushes, asap, the throttled instance changes that are waiting to be dispatched.

void registerInstanceNewMonitor(const InstanceNewHandler &callBackFunction)¶

Register a callback handler to be triggered if a new instance appears in the distributed system.

Parameters

callBackFunction: which will receive the instanceInfo Hash

void registerInstanceUpdatedMonitor(const InstanceUpdatedHandler &callBackFunction)¶

Register a callback handler to be triggered if an instance receives a state update from the distributed system

Parameters

callBackFunction: which will receive the instanceInfo Hash

void registerInstanceGoneMonitor(const InstanceGoneHandler &callBackFunction)¶

Register a callback handler to be triggered if an instance disappears from the distributed system

Parameters

callBackFunction: receiving the instanceId and instanceInfo Hash

void registerSchemaUpdatedMonitor(const SchemaUpdatedHandler &callBackFunction)¶

Register a callback handler to be triggered if an instance receives a schema update from the distributed system Example:

Note

Currently, registering only a schema update monitor with an instance of a DeviceClient is not enough to have the registered call-back activated. A workaround for this is to also register a property monitor with the same instance of DeviceClient that has been used to register the schema update monitor.

Parameters

callBackFunction: receiving the instanceId and updated Schema

DeviceClient dc = std::shared_ptr<DeviceClient>(new DeviceClient()); dc->registerSchemaUpdateMonitor(fnSchemaUpdateHandler); dc->registerPropertyMonitor(“deviceId”, “property_to_monitor”, fnCallback);

void registerClassSchemaMonitor(const ClassSchemaHandler &callBackFunction)¶

Register a callback handler to be triggered if a new class appears on a device server

Parameters

callBackFunction: receiving the server id, class id and new class Schema

template <class ValueType>

bool registerPropertyMonitor(const std::string &instanceId, const std::string &key, const std::function<void(const std::string&, const std::string&, const ValueType&, const karabo::util::Timestamp&)> &callbackFunction)¶

Register a callback function to be triggered when a given property on a device in the distributed system updates

Return

true if the operation was successful

Parameters

instanceId: of the device to be monitored
key: path to the property to be monitored
callbackFunction: handling the update notification. It receives the device id, path, value and timestamp of the updated property

template <class ValueType, class UserDataType>

bool registerPropertyMonitor(const std::string &instanceId, const std::string &key, const std::function<void(const std::string&, const std::string&, const ValueType&, const karabo::util::Timestamp&, const std::any&)> &callbackFunction, const UserDataType &userData, )¶

Register a callback function to be triggered when a given property on a device in the distributed system updates. Additional user data may be passed to the callback

Return

true if the operation was successful

Parameters

instanceId: of the device to be monitored
key: path to the property to be monitored
callbackFunction: handling the update notification. It receives the device id, path, value and timestamp of the updated property as well as std::any userData.
userData: to be passed to the callback as std::any

void unregisterPropertyMonitor(const std::string &instanceId, const std::string &key)¶

Unregister a property monitor

Parameters

instanceId: to unregister the monitor from
key: path to the property to unregister from.

void registerDeviceMonitor(const std::string &instanceId, const std::function<void(const std::string&, const karabo::util::Hash&)> &callbackFunction)¶

Register a callback function to be triggered when a a device in the distributed system updates.

Parameters

instanceId: of the device to register to
callbackFunction: handling the update. It will receive the device instance id and the updated device configuration Hash

void registerDeviceForMonitoring(const std::string &deviceId)¶

Registers a device to have its configurations changes monitored.

Note

In order to receive notifications about configuration changes for any of the monitored devices, one needs to register handlers by calling registerDeviceMonitor (updates one by one - even if updates are throttled) or with registerDevicesMonitor (bulk updates).

Parameters

deviceId: of the device to be added to the set of monitored devices.

void registerDevicesMonitor(const DevicesChangedHandler &devicesChangedHandler)¶

Registers a handler for configuration changes for any of the monitored devices.

Note

* To register a device to be monitored, a call to registerDeviceForMonitoring must be made.

Throttling of device updates must be enabled via a call to setDeviceMonitorInterval with an argument greater than 0.

Parameters

devicesChangesHandler: callback function for configuration changes events for any monitored device.

void unregisterDeviceFromMonitoring(const std::string &deviceId)¶

Unregisters a device from configuration changes monitoring.

Parameters

deviceId: of the device to be removed from the set of monitored devices.

template <class UserDataType>

void registerDeviceMonitor(const std::string &instanceId, const std::function<void(const std::string&, const karabo::util::Hash&, const std::any&)> &callbackFunction, const UserDataType &userData, )¶

Register a callback function to be triggered when a a device in the distributed system updates. Additional user data may be passed to the callback

Parameters

instanceId: of the device to register to
callbackFunction: handling the update. It will receive the device instance id and the updated device configuration Hash as well as std::any userData.
userData: to be passed to the callback as std::any

void unregisterDeviceMonitor(const std::string &instanceId)¶

Unregister a device monitor.

Parameters

instanceId: to unregister the monitor from

bool registerChannelMonitor(const std::string &channelName, const InputChannelHandlers &handlers, const karabo::util::Hash &inputChannelCfg = karabo::util::Hash())¶

Register handlers to be called whenever the defined output channel receives data or end-of-stream (EOS). Internally, an InputChannel is created and configured using the cfg Hash and its connection status can be monitored via the ‘statusTracker’ of the handlers argument

Return

false if channel is already registered

Parameters

channelName: identifies the channel as a concatenation of the id of its devices, a colon (:) and the name of the output channel (e.g. A/COOL/DEVICE:output)
handlers: container for various handlers (handlers can be empty function pointers):
- dataHandler std::function<void (const karabo::util::Hash&, const MetaData&)> to be called whenever data arrives
- inputHandler std::function<void (const InputChannel::Pointer&)> to be called whenever data arrives
- eosHandler std::function<void (const InputChannel::Pointer&)> called for EOS
- statusTracker std::function<void(karabo::net::ConnectionStatus)> called whenever the connection status of the underlying InputChannel changes
inputChannelCfg: configures via InputChanel::create(..) - use default except you know what your are doing. For the expert: “connectedOutputChannels” will be overwritten

bool registerChannelMonitor(const std::string &instanceId, const std::string &channel, const karabo::xms::SignalSlotable::DataHandler &dataHandler, const karabo::util::Hash &inputChannelCfg = karabo::util::Hash(), const karabo::xms::SignalSlotable::InputHandler &eosHandler = karabo::xms::SignalSlotable::InputHandler(), const karabo::xms::SignalSlotable::InputHandler &inputHandler = karabo::xms::SignalSlotable::InputHandler())¶

Register handlers to be called whenever the defined output channel receives data or end-of-stream (EOS).

DEPRECATED - use interface with ‘InputChannelHandlers’ argument!

Return

false if channel is already registered

Parameters

instanceId: of the device having the output channel
channel: is name of the output channel
dataHandler: std::function<void (const karabo::util::Hash&, const MetaData&) to be called whenever data arrives
inputChannelCfg: configures via InputChanel::create(..) - use default except you know what your are doing for the expert: “connectedOutputChannels” will be overwritten
eosHandler: std::function<void (const InputChannel::Pointer&)> called for EOS if given
inputHandler: std::function<void (const InputChannel::Pointer&)> to be called whenever data arrives

bool registerChannelMonitor(const std::string &channelName, const karabo::xms::SignalSlotable::DataHandler &dataHandler, const karabo::util::Hash &inputChannelCfg = karabo::util::Hash(), const karabo::xms::SignalSlotable::InputHandler &eosHandler = karabo::xms::SignalSlotable::InputHandler(), const karabo::xms::SignalSlotable::InputHandler &inputHandler = karabo::xms::SignalSlotable::InputHandler())¶

Register handlers to be called whenever the defined output channel receives data or end-of-stream (EOS).

DEPRECATED - use interface with ‘InputChannelHandlers’ argument!

Return

false if channel is already registered

Parameters

channelName: identifies the channel as a concatenation of the id of its devices, a colon (:) and the name of the output channel (e.g. A/COOL/DEVICE:output)
dataHandler: std::function<void (const karabo::util::Hash&, const MetaData&) to be called whenever data arrives
inputChannelCfg: configures via InputChanel::create(..) - use default except you know what your are doing for the expert: “connectedOutputChannels” will be overwritten
eosHandler: std::function<void (const InputChannel::Pointer&)> called for EOS if given
inputHandler: std::function<void (const InputChannel::Pointer&)> to be called whenever data arrives

bool unregisterChannelMonitor(const std::string &instanceId, const std::string &channel)¶

Unregister monitoring of output channel

Return

false if channel was not registered

Parameters

instanceId: of the device having the output channel
channel: is name of the output channel

bool unregisterChannelMonitor(const std::string &channelName)¶

Unregister monitoring of output channel

Return

false if channel was not registered

Parameters

channelName: identifies the channel as a concatenation of the id of its devices, a colon (:) and the name of the output channel (e.g. A/COOL/DEVICE:output)

template <class T>

void setAttribute(const std::string &deviceId, const std::string &key, const std::string &attributeKey, const T &attributeValue, int timeoutInSeconds = -1)¶

Sets an attribute of a device.

Parameters

deviceId: The id of the device
key: The parameter key (can be nested using “.” as separator)
attributeKey: The attribute key
attributeValue: The attribute value
timeoutInSeconds: Timeout in seconds, as this call is synchronous

template <class T>

void set(const std::string &instanceId, const std::string &key, const T &value, int timeoutInSeconds = -1, const char keySep = util::Hash::k_defaultSep)¶

Set a remote property in the distributed system

Parameters

instanceId: of the device to set the property on
key: path to the property to set
value: to set
timeoutInSeconds: maximum timeout until set operation fails, set to -1 to wait forever
keySep: path separator

template <class T>

void setNoWait(const std::string &instanceId, const std::string &key, const T &value, const char keySep = util::Hash::k_defaultSep)¶

Set a remote property in the distributed system as a fire-and-forget operation. Warning: there is no guarantee and indication if the set succeeded!

Parameters

instanceId: of the device to set the property on
key: path to the property to set
value: to set
keySep: path separator

void set(const std::string &instanceId, const karabo::util::Hash &values, int timeoutInSeconds = -1)¶

Bulk-set remote properties in the distributed system

Parameters

instanceId: of the device to set the property on
values: a Hash containing the to be set value in a path structure indicating which properties to set
timeoutInSeconds: maximum timeout until set operation fails, set to -1 to wait forever

void setNoWait(const std::string &instanceId, const karabo::util::Hash &values)¶

Bulk-set remote properties in the distributed system as a fire-and-forget operation. Warning: there is no guarantee and indication if the set succeeded!

Parameters

instanceId: of the device to set the property on
values: a Hash containing the to be set value in a path structure indicating which properties to set

void executeNoWait(const std::string &deviceId, const std::string &command)¶

Executes a function on a device (an exposed via its Schema) and immediately returns (fire & forget)

Parameters

deviceId: The deviceId
command: Name of the command

template <typename… Args>

void execute(const std::string &deviceId, const std::string &command, int timeoutInSeconds = 3, const Args&... slotArgs)¶

Executes a function on a device synchronously (waits until the function finished)

Template Parameters

Args: Variadic template for the slot args (no arg is a particular case).

Parameters

deviceId: The devideId
command: The command
timeoutInSeconds: Timeout

template <typename R1, typename… Args>

R1 execute1(const std::string &deviceId, const std::string &slotName, int timeoutInSeconds = 3, const Args&... slotArgs)¶

Synchronously executes a slot that returns a single element response.

Return

A value of R1 type

Template Parameters

R1: Type of the response.
Args: Variadic template for the slot arguments.

Parameters

deviceId: Id of the device whose slot should be executed.
slotName: Name of the slot to execute.
timeoutInSeconds: Timeout for the slot execution.
slotArgs: Slot arguments.

template <typename R1, typename R2, typename… Args>

std::tuple<R1, R2> execute2(const std::string &deviceId, const std::string &slotName, int timeoutInSeconds = 3, const Args&... slotArgs)¶

Synchronously executes a slot that returns a two element tuple as a response.

Note

a tuple, instead of a pair, is used as the return value for uniformity with the other executeN methods.

Return

std::tuple<R1, R2> with the results of the slot execution.

Template Parameters

R1: Type of first element of the resulting pair.
R2: Type of second element of the resulting pair.
Args: Variadic template for the slot arguments.

Parameters

deviceId: Id of the device whose slot should be executed.
slotName: Name of the slot to execute.
timeoutInSeconds: Timeout for the slot execution.
slotArgs: Slot arguments.

template <typename R1, typename R2, typename R3, typename… Args>

std::tuple<R1, R2, R3> execute3(const std::string &deviceId, const std::string &slotName, int timeoutInSeconds = 3, const Args&... slotArgs)¶

Synchronously executes a slot that returns a three element tuple as a response.

Return

std::tuple<R1, R2, R3> Tuple with the results of the slot execution.

Template Parameters

R1: Type of first element of the resulting tuple.
R2: Type of second element of the resulting tuple.
R3: Type of third element of the resulting tuple.
Args: Variadic template for the slot arguments.

Parameters

deviceId: Id of the device whose slot should be executed.
slotName: Name of the slot to execute.
timeoutInSeconds: Timeout for the slot execution.
slotArgs: Slot arguments.

template <typename R1, typename R2, typename R3, typename R4, typename… Args>

std::tuple<R1, R2, R3, R4> execute4(const std::string &deviceId, const std::string &slotName, int timeoutInSeconds = 3, const Args&... slotArgs)¶

Synchronously executes a slot that returns a four element tuple as a response.

Return

std::tuple<R1, R2, R3, R4> Tuple with the results of the slot execution.

Template Parameters

R1: Type of first element of the resulting tuple.
R2: Type of second element of the resulting tuple.
R3: Type of third element of the resulting tuple.
R4: Type of fourth element of the resulting tuple.
Args: Variadic template for the slot arguments.

Parameters

deviceId: Id of the device whose slot should be executed.
slotName: Name of the slot to execute.
timeoutInSeconds: Timeout for the slot execution.
slotArgs: Slot arguments.

karabo::util::Hash getOutputChannelSchema(const std::string &deviceId, const std::string &outputChannelName)¶

Request the data schema for an output channel as a Hash containing relevant information

Return

a Hash containing the output channel’s data schema

Parameters

deviceId:
outputChannelName:

std::vector<std::string> getOutputChannelNames(const std::string &deviceId)¶

Get the list of all output channel names of the remote device.

Return

vector containing output channel names

Parameters

deviceId:

karabo::core::Lock lock(const std::string &deviceId, bool recursive = false, int timeout = -1)¶

Request locking of device at deviceId. Throws a karabo::util::LockException in case the lock cannot be acquired in the given timeout

Return

a Lock object, holding the lock to deviceId.

Parameters

deviceId: the device to be locked
recursive: if true, recursive locks on this device are allowed
timeout: timeout during which we try to acquire the lock. Set to -1 to wait try indefinitely, 0 to only try once, otherwise give integer seconds to wait.

Protected Types

typedef std::map<std::string, int> InstanceUsage¶: Map of devices that we are connected to with timer stating their age since last access. Before C++14 not an unordered_map since we want to erase while looping over it

Protected Functions

karabo::util::Hash prepareTopologyEntry(const std::string &path, const karabo::util::Hash &instanceInfo) const¶

Prepare a topology entry for the runtime system description

Parameters

path: the path created with prepareTopologyPath using instanceId and instanceInfo
instanceInfo: The instanceInfo Hash received from the broadcast

void mortalize(const std::string &deviceId)¶

Unmark deviceId from staying connected all the time without ageing.

Also clears a zombie (marked by negative age) from m_instanceUsage and thus locks m_instanceUsageMutex. That means, unlike immortalize(..) and isImortal(..), mortalize(..) must not be called under protection of m_instanceUsageMutex.

bool eraseFromRuntimeSystemDescription(const std::string &path)¶: returns true if path could be removed

util::Hash getSectionFromRuntimeDescription(const std::string &section) const¶: Get section (e.g. “device”) from runtime description. Returns empty Hash if section does not exist.

std::string findInstanceSafe(const std::string &instanceId) const¶: Find full path of ‘instanceId’ in m_runtimeSystemDescription, empty if path does not exist.

Protected Attributes

karabo::util::Hash m_runtimeSystemDescription¶

server + <serverId> type host version status deviceClasses + classes + <classId> + description SCHEMA configuration HASH description SCHEMA configuration HASH

device + <deviceId> type host version status classId serverId + fullSchema => SCHEMA configuration => HASH activeSchema + <stateName> => SCHEMA

DevicesChangedHandler m_devicesChangesHandler¶: Handler for all monitored devices configuration updates during last interval.

boost::asio::steady_timer m_signalsChangedTimer¶: defines whether aging is running or not

std::mutex m_loggerMapMutex¶: map of collected signalChanged

Private Types

typedef std::map<std::string, std::set<std::string>> SignalChangedMap¶: keys are instance IDs, values are a sets of properties that changed

Private Functions

std::string findInstance(const std::string &instanceId) const¶: As findInstanceSafe, but to be called under protection of m_runtimeSystemDescriptionMutex.

void doSendSignalsChanged(const SignalChangedMap &signalChangedMap)¶: Actually process data in ‘signalChangedMap’ - try/catch should be outside.

bool connectNeeded(const std::string &instanceId)¶: Marks ‘instanceId’ as used. Returns true if explicit “connect” call should still be done for it.

void initServiceDeviceIds(const karabo::util::Hash &serviceDeviceIds)¶

Internal helper method to initialize the service device ids members of the DeviceClient instance.

Parameters

serviceDeviceIds: A hash with ids of core service devices; e.g, “dataLoggerManagerId” key and the value is the name of the DataLoggerManager the device client instance should use for data logging operations. Currently keys “dataLoggerManagerId” and “configurationManagerId” are supported. If a supported key is missing, the default ID for the service device type is used.

std::vector<std::pair<std::string, karabo::util::Hash>> findAndEraseDevicesAsGone(const std::string &serverId)¶

Helper for _slotInstanceGone for servers

Finds all devices that belong to given server, removes them from m_runtimeSystemDescription and returns pairs of their deviceIds and instanceInfo. Requires protection of m_runtimeSystemDescriptionMutex.

void treatInstanceAsGone(const std::string &instanceId, const karabo::util::Hash &instanceInfo)¶

Helper for _slotInstanceGone

Does all needed action

despite of removal from m_runtimeSystemDescription
and despite of special treatment of devices on the server if instance is a server

struct InputChannelHandlers¶

#include <DeviceClient.hh>

Container of handlers for InputChannel, to be passed to

bool registerChannelMonitor(const std::string& channelName, const InputChannelHandlers& handlers, const karabo::util::Hash& inputChannelCfg = karabo::util::Hash());

See documentation of that method for meaning of various handlers.

Public Functions

InputChannelHandlers(const karabo::xms::SignalSlotable::DataHandler &data, const karabo::xms::SignalSlotable::InputHandler &eos = karabo::xms::SignalSlotable::InputHandler(), const std::function<void(karabo::net::ConnectionStatus)> &status = std::function<void(karabo::net::ConnectionStatus)>())¶: Construct with all handlers except input handler (could be specified afterwards)

InputChannelHandlers(const karabo::xms::SignalSlotable::InputHandler &input, const karabo::xms::SignalSlotable::InputHandler &eos = karabo::xms::SignalSlotable::InputHandler(), const std::function<void(karabo::net::ConnectionStatus)> &status = std::function<void(karabo::net::ConnectionStatus)>())¶: Construct with all handlers except data handler (could be specified afterwards)

class DeviceServer¶

#include <DeviceServer.hh>

The DeviceServer class hosts device instances.

The DeviceServer class hosts device instances. It monitors the system for new class plugins appearing and notifies the distributed system of these and their static information.

The device server uses an ok-error FSM, which knows the ERROR and NORMAL karabo::util::State states.

Inherits from karabo::xms::SignalSlotable

Public Functions

DeviceServer(const karabo::util::Hash &config)¶

The constructor expects a configuration Hash. The following configuration options are supported:

serverId: a string giving the server’s id
autostart: a vector of Hashes containing configurations for device that are to be automatically started by the server
scanPlugins: a boolean indicating if this server should scan for additional plugins
visibility: an integer indicating device server visibility in the distributed system
debugMode: a boolean indicating if the server should run in debugMode
connection: a Hash containing the connection information for a karabo::net::Broker
pluginDirectory: a path to the plugin directory for this device server
heartbeatInterval: interval in seconds at which this server sends heartbeats to the distributed system
nThreads: number of threads to use in this device server
Parameters

bool isRunning() const¶

Check if the device server is running

Return

Public Static Functions

void expectedParameters(karabo::util::Schema &expected)¶

Static properties of the device server

Parameters

to: inject these properties to

Private Functions

std::tuple<std::string, std::string, util::Hash> prepareInstantiate(const util::Hash &configuration)¶: Helper to create input passed to instantiate. Returns a tuple of the deviceId, the classId and the configuration.

void instantiate(const std::string &deviceId, const std::string &classId, const util::Hash &config, const SignalSlotable::AsyncReply &asyncReply)¶: Helper for instantiateDevices - e.g. provides the (async) reply for slotStartDevice.

void slotTimeTick(unsigned long long id, unsigned long long sec, unsigned long long frac, unsigned long long period)¶

A slot called by the time-server to synchronize this device with the timing system.

Parameters

id: current train id
sec: current system seconds
frac: current fractional seconds
period: interval between subsequent ids in microseconds

void timeTick(const boost::system::error_code ec, unsigned long long newId)¶

Helper function for internal time ticker deadline timer to provide internal clock that calls ‘onTimeUpdate’ for every id even if slotTimeTick is called less often.

Parameters

ec: error code indicating whether deadline timer was cancelled
id: current train id

class InstanceChangeThrottler¶

#include <InstanceChangeThrottler.hh>

Receives instance new, update and gone messages and dispatches them to an interested part in “cycles” spaced by a given interval. Also takes care of removing redundant message sequences.

The second level hashes are the values of the root hash. Their keys are the types of the instances whose changes are on the third level hashes. The keys are the contents of the InstanceInfo.Type field in the instance change data. Typical values for second level keys would be “device”, “server” and “macro”.

Note: The hash is composed of three level of hashes. The root hash has the types of the instances changes as its keys . The possible values for this first level keys are “new”, “gone” and “update”. The three keys will always be present in the root hash, even when a particular cycle has no change of the given type to dispatch.

The third level hashes are the values of the second level hashes. Their keys will be the instanceIds in the instance change data. Those keys can be either a deviceId, a serverId or any other kind of Id, depending on the type of the instance. The the third level hashes will be the ones resulting from calling the InstanceChangeEntryEncoder function passed as an argument to the Throttler with the InstanceId and InstanceInfo in the instance change data. For “new” and “update” changes the third level hash will be an empty hash with the input InstanceInfo fields as attributes. For “gone” changes the third level hash will not be empty and will have the same lay-out as the input InstanceInfo hash.

Inherits from std::enable_shared_from_this< InstanceChangeThrottler >

Public Functions

void submitInstanceNew(const std::string &instanceId, const karabo::util::Hash &instanceInfo)¶

Submits an instance new change for dispatching by the throttler.

Parameters

instanceId: The id of the instance the new change refers to.
instanceInfo: Information about the instance the new change refers to.

void submitInstanceUpdate(const std::string &instanceId, const karabo::util::Hash &instanceInfo)¶

Submits an instance update change for dispatching by the throttler.

Parameters

instanceId: The id of the instance the update change refers to.
instanceInfo: Information about the instance the update change refers to.

void submitInstanceGone(const std::string &instanceId, const karabo::util::Hash &instanceInfo)¶

Submits an instance gone change for dispatching by the throttler.

Parameters

instanceId: The id of the instance the gone change refers to.
instanceInfo: Information about the instance the gone change refers to.

unsigned int cycleIntervalMs() const¶: The interval, in milliseconds, between cycles of the throttler.

unsigned int maxChangesPerCycle() const¶: The maximum number of instance changes entries to be dispatched per throttler cycle. If this limit is reached before the throttler interval elapses, a cycle is started immediately to dispatch the changes to the registered handler.

std::string getInstChangeTypeStr(InstChangeType changeType) const¶: Returns the string representation of a given InstChangeType value.

void flush()¶

Flushes the throttler by making it dispatch the instance changes it has stored asap.

Note: this is a wrapper for the private flushThrottler(bool) method.

Public Static Functions

std::shared_ptr<InstanceChangeThrottler> createThrottler(const InstanceChangeHandler &instChangeHandler, unsigned int cycleIntervalMs = 500u, unsigned int maxChangesPerCycle = 100)¶

InstanceChangeThrottler factory.

Return

A shared pointer to an InstanceChangeThrottler.

Note

The Throttler only has a private constructor; every instantiation of a Throttler must come from this factory method. It takes care of initializing the newly instantiated Throttler.

Note

instChangeEntryEncoder has been added to allow the Throttler to call DeviceClient::prepareTopologyEntry without directly knowing DeviceClient.

Parameters

instChangeHandler: The handler for instance change events dispatched by the Throttler.
cycleIntervalMs: The interval in milliseconds between throttler cycles.
maxChangesPerCycle: The maximum number of instance changes entries to be dispatched per throttler cycle. If this limit is reached before the throttler interval elapses, a cycle is started immediately to dispatch the changes to the handler.

Private Functions

Hash instNewUpdateEncoder(const std::string &instanceId, const karabo::util::Hash &instanceInfo) const¶

Encodes the instanceInfo hash into the format that the Throttler uses internally for changes of type NEW and UPDATE.

Return

a hash whose only key is the instanceId, with the keys/values in instanceInfo as attributes and an empty hash as the only value.

Parameters

instanceId: the id of the instance the change is about.
instanceInfo: the instanceInfo hash as used by the karabo GUI.

karabo::util::Hash instGoneEncoder(const std::string &instanceId, const karabo::util::Hash &instanceInfo) const¶

Encodes the instanceInfo hash into the format that the Throttler uses internally for changes of type GONE.

Return

a hash whose only key is the instanceId and whose only value is the instanceInfo hash.

Parameters

instanceId: the id of the instance the change is about.
instanceInfo: the instanceInfo hash as used by the karabo GUI.

void addChange(InstChangeType changeType, const std::string &instanceId, const karabo::util::Hash &instanceInfo)¶

Adds an instance change to m_instChanges.

As part of the addition, performs some optimizations to the set of events already in the hash. It can happen that the new change actually “cancels” a set of changes that had been previously added. An example: an ‘instance gone’ event can “cancel” all the ‘instance new’ and ‘instance update’ events related to the same instance; in this scenario, the ‘addition’ of the gone event would actually consist of the removal of the other events related to the same instance.

Parameters

changeType:
instanceId:
instanceInfo:

void runThrottlerCycleAsync(const boost::system::error_code &e)¶

Throttler cycle execution. For each cycle, the throttler dispatches the instances changes hash.

Parameters

e: Error code passed by the boost::asio::deadline_timer ticking mechanism.

void kickNextThrottlerCycleAsync()¶: Schedules the next throttler event dispatching cycle.

void flushThrottler(bool kickNextCycle = true)¶

Flushes the throttler by running its dispatching loop immediately.

Note

Assumes that the mutex for acessing instanceChange data is acquired by a caller (either the direct caller or another caller down the activation stack).

Parameters

if: true, the next throttler cycle is scheduled after the flush completes.

Private Members

karabo::util::Hash m_instChanges¶

A Hash with all the instances changes to be dispatched by the Throttler in its next cycle.

Description for the Hash format can be found in the class documentation.

class Lock¶

Public Functions

Lock(std::weak_ptr<karabo::xms::SignalSlotable> sigSlot, const std::string &deviceId, bool recursive = false)¶

Create a lock on a device. Throws a karabo::util::LockException if the lock cannot be acquired

Parameters

sigSlot: a SignalSlotable instance to use for locking the remote device
deviceId: the deviceId of the device to lock
recursive: allow recursive locking if true

Lock(const Lock &other)¶

Copy construction is disabled

Parameters

other:

Lock(Lock &&other)¶

Move construction will invalidate the lock being moved.

Parameters

other:

~Lock()¶: The destructor unlocks the device the lock is held on if the lock is valid. It is called explictly if the lock was stolen and will then throw a karabo::util::LockException

void lock(bool recursive = false) const¶

Reacquire a lock if this lock was previously unlocked

Parameters

recursive: allow recursive locking if true

void unlock() const¶: Unlock this lock

bool valid() const¶: Returns if this lock is currently valid. Note that the locked device will be queried through the distributed system when asking for lock validity.

Private Functions

void lock_impl(bool recursive) const¶

Perform locking. Calling this function leads to the following remote calls:

1) check if we are allowed to lock: the lockedBy field on the remote device is either empty, or if recursive == true contains the lock requestor’s device id

2) request locking, e.g. set the lockedBy field. This can still fail if another device locked in between

3) check if we are the lock holder: lockedBy should now contain our device id

Parameters

recursive: allow recursive locking if true

void unlock_impl() const¶: Simply calls the clearLock slot on the locked device if we are the lock-holder

class NoFsm¶

#include <NoFsm.hh>

Use this class if you do not use an fixed state machine but rather a simple state machine with in device state updates.

Subclassed by karabo::core::Device<>

class OkErrorFsm¶

#include <OkErrorFsm.hh>

A simple finite state machine knowing either NORMAL or ERROR States.

NORMAL (ErrorFoundEvent) -> (ErrorFoundAction) ERROR ERROR (ResetEvent) -> (ResetAction) NORMAL

Inherits from karabo::core::BaseFsm

struct QueueWorker¶: Inherits from karabo::core::BaseWorker< karabo::util::Hash::Pointer >

class Runner¶

#include <Runner.hh>

The Runner class starts device-servers in the distributed system.

The Runner class instantiates device-servers in the distributed system. It parses command line arguments to deduce configuration.

Public Static Functions

DeviceServer::Pointer instantiate(int argc, const char **argv)¶

Instantiates a device server taking command line arguments into account

Users of this function must check the returned pointer for validity. The pointer may be empty in case the help option is given.

Return

Pointer to device server instance (may be empty)

Parameters

argc: Number of commandline arguments
argv: String array of commandline options

class StartStopFsm¶

#include <StartStopFsm.hh>

A finite state machine designed to be used binary state (start - stop) devices.

A finite state machine designed to be used for binary state (start - stop) devices. It uses an ERROR-NORMAL top state machine (karabo::core::OkErrorFsm type). In the NORMAL region the following state transition table is used:

STOPPED (StartEvent) -> (StartAction) STARTED STARTED (StopEvent) -> (StopAction) STOPPED

Inherits from karabo::core::BaseFsm

class StartStopInterface¶

#include <StartStopInterface.hh>

suggested interface to work on top of a karabo::core::StartStopFsm

Inherits from karabo::xms::SignalSlotable

struct Worker¶

#include <Worker.hh>

A worker that passes any data received in its queue to a callback function working asynchronously working in a separate thread.

Inherits from karabo::core::BaseWorker< bool >

Public Functions

Worker(const std::function<void()> &callbackint delay = -1, int repetitions = -1, )¶

Instantiate a worker with a callback function to work on data. See Worker::WorkerBase for options

Parameters

callback:
delay:
repetitions:

The karabo::devices Namespace¶

namespace karabo::devices¶

Namespace for package core

Typedefs

using karabo::devices::BeginTemporarySessionHandler = typedef std::function<void(const BeginTemporarySessionResult&)>

using karabo::devices::ExpirationHandler = typedef std::function<void(const ExpiredTemporarySessionInfo&)>: Handler for expired temporary session events.

using karabo::devices::EminentExpirationHandler = typedef std::function<void(const EminentExpirationInfo&)>: Handler for “temporary session about to expire” events.

using karabo::devices::AsyncHandler = typedef std::function<void()>

using karabo::devices::InfluxResponseHandler = typedef std::function<void(const karabo::net::HttpResponse&)>

Enums

enum RejectionType¶

Values:

TOO_MANY_ELEMENTS = 0¶

VALUE_STRING_SIZE¶

PROPERTY_WRITE_RATE¶

SCHEMA_WRITE_RATE¶

FAR_AHEAD_TIME¶

Functions

template <class T>
void addToSetOrCreate(Hash &h, const std::string &key, const T &object)¶: Helper function used below: Add object to set<T> at key’s position in h - if no such key exists, create one

static void trim_vector_elements(std::vector<std::string> &v)¶

Variables

constexpr karabo::util::Schema::AccessLevel MAX_LOGIN_ACCESS_LEVEL = karabo::util::Schema::AccessLevel::ADMIN¶

constexpr karabo::util::Schema::AccessLevel MAX_TEMPORARY_SESSION_ACCESS_LEVEL = karabo::util::Schema::AccessLevel::ADMIN¶

constexpr unsigned int CHECK_TEMPSESSION_EXPIRATION_INTERVAL_SECS = 5U¶

const unsigned int defVectorMaxSize = 100¶

struct BeginTemporarySessionResult¶: Inherits from karabo::net::OneTimeTokenAuthorizeResult

class DataLogger¶

#include <DataLogger.hh>

A DataLogger device is assigned devices in the distributed system and logs their slow control data.

DataLoggers are managed by the karabo::devices::DataLoggerManager.

Each is able to log any number of devices. This list can be specified at instantiation, but can also dynamically changed by the slots slotTagDeviceToBeDiscontinued and slotAddDevicesToBeLogged. When the logger is ready to log data, its state changes from INIT to NORMAL.

Inherits from karabo::core::Device<>

Subclassed by karabo::devices::FileDataLogger, karabo::devices::InfluxDataLogger

Protected Functions

void initializeLoggerSpecific()¶: Do some actions here that may require asynchronous logic … and, finally, startConnection() should be called This function may be overridden by derived classes but at the end the ‘startConnection’ function should be called as a last step of initialization

bool removeFrom(const std::string &str, const std::string &vectorProp)¶

Helper to remove an element from a vector<string> element - needs protection by m_perDeviceDataMutex. Note that if the same element is in the vector more than once, only the first one is removed.

Return

whether could be removed

Parameters

str: the element to remove
vectorProp: the key of the vector<string> element

bool appendTo(const std::string &str, const std::string &vectorProp)¶

Helper to add an element to a vector<string> element - needs protection by m_perDeviceDataMutex. Note that if the same element is already in, it will not be added again.

Return

whether it was added (i.e. false if ‘str’ was already in the vectorProperty

Parameters

str: the element to add
vectorProp: the key of the vector<string> element

void preDestruction()¶: Override preDestruction from Device class

Private Functions

void slotTagDeviceToBeDiscontinued(const std::string &reason, const std::string &deviceId)¶

FIXME: Update text This tags a device to be discontinued, three cases have to be distinguished

(a) Regular shut-down of the device (wasValidUpToNow = true, reason = ‘D’) (b) Silent death of the device (wasValidUpToNow = true, reason = ‘D’) (c) Start-up of this (DataLogger) device whilst the device was alive (wasValidUpToNow = false, reason = ‘L’)

This slot will be called by the DataLoggerManager

void handleConfigConnected(const DeviceData::Pointer &data, const std::shared_ptr<std::atomic<unsigned int>> &counter)¶: Helper for connecting to both signalChanged and signalStateChanged.

void updateTableAndFlush(const std::shared_ptr<SignalSlotable::AsyncReply> &aReplyPtr)¶

Flush data in file hierarchy or to the database tables

Parameters

aReplyPtr: if pointer to an AsyncReply that (if non-empty) has to be called without argument when done

virtual void flushImpl(const std::shared_ptr<SignalSlotable::AsyncReply> &aReplyPtr) = 0¶: “Flush” data accumulated in the internal cache to the external storage (file, database,…)

bool allowLock() const¶

This device may not be locked

Return: false

class DataLoggerManager¶

#include <DataLoggerManager.hh>

The DataLoggerManager manages device loggers in the distributed system.

In the Karabo distributed system two types of data archiving exist:

run associated archival of scientific data through the DAQ system
constant device state and slow control logging using the data logger services

This device manages the data loggers used in the second logging scenario. It is the central configuration point to set via its expected parameters the

flushInterval: at which loggers flush their data to disk
maximumFileSize: of log files after which a new log file chunk is created
directory: the directory into which loggers should write their data
serverList: a list of device servers which each runs one logger. Each device in the distributed system is assigned to one logger. They are added to the loggers on these servers in a round robin fashion, allowing for load balancing. Assignment is made permanent in a loggermap.xml file that is regularly written to disk. This allows to distribute the servers in the serverList to be distributed among several hosts and still have fixed places for reading the data back.

Inherits from karabo::core::Device<>

Private Functions

std::pair<bool, std::string> checkSummary()¶: Assemble summary from m_checkStatus and clear for next use. The boolean returned tells whether the status requires operator attention.

void printLoggerData() const¶: Print internal cash of logger status. Needs to be protected by m_strand.

void forceDeviceToBeLogged(const std::string &deviceId)¶

If deviceId’s logging status is fishy, re-add to its logger. Needs to be protected by m_strand.

Parameters

deviceId: the fishy device

void slotGetLoggerMap()¶: Request the current mapping of loggers to servers. The reply contains a Hash where the the logger id is the key and the server id the value.

std::string loggerServerId(const std::string &deviceId, bool addIfNotYetInMap)¶

Get id of server that should run logger for given device that should be logged

Return

the server id - can be empty if addIfNotYetInMap == false

Parameters

deviceId: the device that should be logged
addIfNotYetInMap: whether to create a server/logger relation in the logger map in case it does not yet exist for deviceId

std::string serverIdToLoggerId(const std::string &serverId) const¶: Get id of DataLogger running on server with id ‘serverId’

std::string loggerIdToServerId(const std::string &loggerId) const¶: Get id of server that should run logger with id ‘loggerId’

bool allowLock() const¶

This device may not be locked

Return: false

void evaluateBlockedOnStrand(const karabo::util::Hash &oldList, const karabo::util::Hash &newList)¶

Evaluate old and new configuration in order to possibly start/stop archiving for some devices/device classes.

Parameters

oldList: old configuration for blocked devices/classes
newList: new configuration for blocked devices/classes

std::vector<karabo::util::Hash> makeLoggersTable()¶: create a vector of hashes that can be loaded in a table from the Hash with the mapping device -> logger

Private Members

karabo::util::Hash m_checkStatus¶: 1st level keys: entries in m_serverList, 2nd level: “state”, “backlog”, “beingAdded” and “devices”

std::unordered_map<std::string, std::set<std::string>> m_knownClasses¶: Keep track of all important stuff during check.

karabo::net::Strand::Pointer m_strand¶: to be accessed on the strand

const std::string m_blockListFile¶: Hash with ‘deviceIds’ and ‘classIds’ entries.

class DataLogReader¶

#include <DataLogReader.hh>

DataLogReader devices read archived information from the Karabo data loggers.

DataLogReader devices read archived information from the Karabo data loggers. They are managed by karabo::devices::DataLoggerManager devices. Calls to them should usually not happen directly, but rather through a karabo::core::DeviceClient and it’s karabo::core::DeviceClient::getPropertyHistory and karabo::core::DeviceClient::getConfigurationFromPast methods.

Inherits from karabo::core::Device<>

Subclassed by karabo::devices::FileLogReader, karabo::devices::InfluxLogReader

Protected Functions

void slotGetPropertyHistory(const std::string &deviceId, const std::string &property, const karabo::util::Hash &params)¶

Use this slot to get the history of a given property The slot replies a vector of Hashes where each entry consists of a Hash with a key “v” holding the value of the property at timepoint signified in “v“‘s attributes using a format compatible with karabo::util::Timestamp::fromHashAttributes

Parameters

deviceId: for which to get the history for
property: path to the property for which to get the history from
params: Hash containing optional limitations for the query:
- from: iso8601 timestamp indicating the start of the interval to get history from
- to: iso8601 timestamp indicating the end of the interval to get history from
- maxNumData: maximum number of data points to retrieve starting from start

void slotGetConfigurationFromPast(const std::string &deviceId, const std::string &timepoint)¶

Request the configuration Hash and schema of a device at a given point at time. Depending on the device status and on the availability of logged data, the configuration and schema returned will be:

If the device was online and logging data at the given timepoint, the configuration and the schema will be the ones that were active at the timepoint;
If the device was offline at the given timepoint, but there is data logged for it before the timepoint, the last active configuration and schema before that timepoint will be returned;
If the device was offline at the given timepoint and there’s no data logged before the timepoint, an empty configuration and an empty schema will be returned.

The slot replies with a tuple of 4 values. The first two are the Hash and Schema objects containing the configuration Hash and the corresponding device schema for timepoint. The third is a boolean whose true value indicates the device was online and actively logging data at the timepoint. The fourth value is the string form of the timepoint for the configuration returned and will be the latest timestamp among the timestamps of the properties in the configuration returned.

Parameters

deviceId: of the device to get the configuration from
timepoint: in iso8601 format for which to get the information

An important note: if no configuration is found for the device at the timepoint (or before the timepoint), the third value in the reply will be false and the fourth will be the string form of the Epoch (01/01/1970 at 00:00:00).

void onOk()¶: helper functions to handle state transition in derived classes: onOk: sets the State to ON

const string onException(const std::string &message)¶

helper functions to handle state transition in derived classes: onException: sets the State to ERROR, logs the exception trace to status and to the Karabo Logs

Return

the exception trace

Parameters

message: a string to be prepended to the trace

struct DeviceData¶

Inherits from std::enable_shared_from_this< DeviceData >

Subclassed by karabo::devices::FileDeviceData, karabo::devices::InfluxDeviceData

Public Functions

virtual void handleChanged(const karabo::util::Hash &config, const std::string &user) = 0¶

Called when configuration updates arrive for logging

Parameters

config: a Hash with the updates and their timestamps
the: user responsible for this update - if any

virtual void handleSchemaUpdated(const karabo::util::Schema &schema, const karabo::util::Timestamp &stamp) = 0¶

Called when a Schema update arrive for logging

Parameters

schema: - the new one
stamp: - the timestamp to be assigned for that update

void getPathsForConfiguration(const karabo::util::Hash &configuration, const karabo::util::Schema &schema, std::vector<std::string> &paths) const¶

Retrieves the paths of the leaf nodes in a given configuration. The paths are returned in ascending order of their corresponding nodes timestamps.

Note

karabo::devices::DataLogReader depends on the configuration items being properly sorted in time to retrieve configuration changes.

Parameters

configuration: A configuration with the nodes corresponding to the paths.
schema: The schema for the configuration hash.
paths: The paths of the leaf nodes in the configuration, sorted by nodes timestamps.

class FileDataLogger¶

Inherits from karabo::devices::DataLogger

Private Functions

void flushImpl(const std::shared_ptr<SignalSlotable::AsyncReply> &aReplyPtr)¶: “Flush” data accumulated in the internal cache to the external storage (file, database,…)

struct FileDeviceData¶

Inherits from karabo::devices::DeviceData

Public Functions

void handleChanged(const karabo::util::Hash &config, const std::string &user)¶

Called when configuration updates arrive for logging

Parameters

config: a Hash with the updates and their timestamps
the: user responsible for this update - if any

bool updatePropsToIndex()¶: Helper function to update data.m_idxprops, returns whether data.m_idxprops changed.

void ensureFileClosed()¶: Helper to ensure archive file is closed. Must only be called from functions posted on ‘data.m_strand’.

std::pair<bool, size_t> ensureFileOpen()¶

Helper to ensure archive file (m_configStream) is open. Must only be called from functions posted on ‘data.m_strand’.

Return

pair of * whether it is a new file (in contrast to a re-opened existing one)

current file position, size_t(-1) tells that file could not be opened (permissions?)

void handleSchemaUpdated(const karabo::util::Schema &schema, const karabo::util::Timestamp &stamp)¶

Called when a Schema update arrive for logging

Parameters

schema: - the new one
stamp: - the timestamp to be assigned for that update

struct FileLoggerIndex¶: #include <FileLogReader.hh>
A compound for representing indexes in text file logged data.

class FileLogReader¶

#include <FileLogReader.hh>

A reader for data logs stored in text files by the class karabo::devices::FileDataLogger.

Inherits from karabo::devices::DataLogReader

Private Functions

void readToHash(karabo::util::Hash &hashOut, const std::string &path, const karabo::util::Timestamp &timestamp, const std::string &type, const std::string &value) const¶: Internal helper: Place ‘value’ interpreted as ‘type’ (and with given ‘timestamp’) into ‘hashOut’ at ‘path’.

std::pair<bool, FileLoggerIndex> findLoggerIndexTimepoint(const std::string &deviceId, const std::string &timepoint)¶

Retrieves, from the logger index, the event of type “device became online” that is closest, but not after a given timepoint. The retrieved logger index event can be used as a starting point for sweeping the device log for the last known given configuration at that timepoint.

Return

a pair whose ‘first’ is a boolean that indicates whether configuration was active at the timepoint (true) or whether it is a configuration from the most recent activation of the device prior to the timepoint because the device was not active logging at the timepoint. The pair’s ‘second’ value is the logger index of the given device that is the closest “device became online” event that is not after the given timepoint.

Parameters

deviceId: the device whose logger index event should be retrieved.
timepoint: the timepoint that will be used as the reference to find the logger index event.

FileLoggerIndex findNearestLoggerIndex(const std::string &deviceId, const karabo::util::Epochstamp &timepoint, const bool before)¶: Find logger closest index from archive_index.txt file that is before/after (according to ‘before’) ‘timepoint’. If there is none before (after) but that is asked for, take the one just after (before).

size_t findPositionOfEpochstamp(std::ifstream &f, double stamp, size_t left, size_t right, bool preferBefore)¶: Find index of that MetaData::Record in ‘f’ (between indices ‘left’ and ‘right’) that matches the Epochstamp ‘stamp’. In case no exact match (within 1 ms) is found, ‘preferBefore’ decides whether the index with a smaller or larger time stamp is returned.

void extractTailOfArchiveIndex(const std::string &tail, FileLoggerIndex &entry) const¶: Helper to extract DataLoggerIndex values out of the tail of a line in archive_index.txt. The tail is everything after event, timestampAsIso8061 and timestampAsDouble. The entry has to be partly filled (m_event and m_epoch) and partly serves as output (m_train, m_position, m_user and m_fileindex). Works for lines written to archive_index.txt by >= 1.5

class GuiServerDevice¶

#include <GuiServerDevice.hh>

The GuiServerDevice mediates between GUI clients and the distributed system.

The GuiServerDevice acts as a mediator between the distributed system and GUI clients, which connect to it through (tcp) channels. The device centrally manages updates from the distributed system and pushes them to the clients. Conversly, it handles requests by clients and passes them on to devices in the distributed system.

Inherits from karabo::core::Device<>

Private Functions

void initUsersActionsLog()¶

Initializes the user actions log.

The log contains entries describing the writing actions the GUI Server performed upon request of a user. It is separated from the remaining device server logs.

void logUserAction(const WeakChannelPointer &channel, const std::string &entryText)¶

Adds an entry with a given text to the user actions log.

Parameters

channel: The TCP Channel connecting the GUI Server to the GUI Client that originated the action execution request.
entryText: A description of the action (and possibly its parameters)

void loggerMapConnectedHandler()¶: Wrapping requestNoWait

void postReconfigure()¶: Called if configuration changed from outside.

void startDeviceInstantiation()¶: Starts the deadline timer which throttles device instantiation.

void startNetworkMonitor()¶: Starts the deadline timer which triggers network stats collection

void startMonitorConnectionQueues(const karabo::util::Hash &currentSuspects)¶

Starts the deadline timer which monitors connection queues

Parameters

currentSuspects: Hash with pending message counts - keys are bad client addresses

void collectNetworkStats(const boost::system::error_code &error)¶: Perform network stats collection

void deferredDisconnect(WeakChannelPointer channel)¶

writes a message to the specified channel with the given priority

Parameters

channel:
message:
prio: Deferred disconnect handler.

void safeAllClientsWrite(const karabo::util::Hash &message, int prio = LOSSLESS)¶

writes message to all channels connected to the gui-server device

Parameters

message:
prio:

void sendLoginErrorAndDisconnect(const karabo::net::Channel::Pointer &channel, const std::string &userId, const std::string &cliVersion, const std::string &errorMsg)¶

Sends a login error message to the client currently connected and closes the connection after a time interval elapses.

Parameters

channel: the channel the client to be notified and disconnected is connected.
userId: the id of the user whose login attempt failed.
cliVersion: the version of the GUI client attempting to login.
errorMsg: the error message to be sent to the client.

void onError(const karabo::net::ErrorCode &e, WeakChannelPointer channel)¶

an error specified by ErrorCode e occurred on the given channel. After an error the GUI-server will attempt to disconnect this channel.

Parameters

e:
channel:

bool violatesReadOnly(const std::string &type, const karabo::util::Hash &info)¶

validate the incoming type and info hash if a readOnly command is requested to be executed

Return

bool whether the request violates read-only restrictions

Parameters

type:
info:

bool isProjectLoadingReplyType(const std::string &replyType)¶

Checks whether a given reply type requested by a GUI Client is for a request involved in the Load Project operation.

Return

bool is the reply type involved in the Load Project operation?

Parameters

replyType: the string that specifies the reply type.

bool violatesClientConfiguration(const std::string &type, WeakChannelPointer channel)¶

validates the client configuration

currently only validating the type versus the client version.

Return

bool whether the request violates client validation

Parameters

type:
channel:

void onGuiError(const karabo::util::Hash &hash)¶

an error further specified by hash occurred on a connection to a GUI client. The GUI-server will attempt to forward the error to the debug channel of the GUI client.

Parameters

hash:

void onConnect(const karabo::net::ErrorCode &e, karabo::net::Channel::Pointer channel)¶

connects a client on to the GUI server on channel. The channel is registered with two priority handlers: remove oldest and loss-less. The onRead and onError handlers are registered to handle incoming data and faults on the channel. Both upon successful completion and exceptions in the process the acceptor socket of the GUI-server is re-registered so that new client connections may be established.

Parameters

e: holds an error code if any error occurs when calling this slot
channel:

void registerConnect(const karabo::util::Version &version, const karabo::net::Channel::Pointer &channel, const std::string &userId = "", const std::string &oneTimeToken = "")¶

Creates an internal ChannelData structure mapped to the TCP Channel in charge of the connection between the GUI Client and the GUI Server. Also updates the number of connected clients property of the GUI Server.

Called after a successful user authorization based on a one-time token (when the GUI Server requires user authentication).

For GUI Servers that don’t require user authentication / authorization, it’s called right after the message of “type” “login” is received by the server and the client’s version is verified as one being supported by the server. The client’s version verification is also performed by a GUI Server that requires authentication (right before the token validation).

Note

The access level is not being saved in the internal ChannelData structure because all the access level enforcement is currently client side only. If any enforcement is required on the server side, the access level information must be stored in ChannelData and updated whenever the user downgrades his/her access level on the GUI client.

Parameters

version: the version of the connected GUI client
channel: the TCP channel for the connection being registered
userId: the ID of the user logged in the connected GUI Client
oneTimeToken: the one-time token resulting from the user authentication previously triggered by GUI client - the token is used by the GUI Server to validate the authentication and to authorize the user (send the user’s login access level back to the GUI Client).

void onWaitForLogin(const karabo::net::ErrorCode &e, const karabo::net::Channel::Pointer &channel, karabo::util::Hash &info)¶

Handler for login messages expected to be sent by a GUI Client right after it establishes a TCP connection to the GUI Server.

Keeps discarding and logging warnings for any message whose “type” is not “login”. When such an unexpected message is received, the GUI server binds this handler again to the TCP channel.

When a message of “type” of “login” is received, its handling is delegated to onLogin(const karabo::net::ErrorCode&, const karabo::net::Channel::Pointer&, karabo::util::Hash&)

Parameters

e: holds an error code if the eventloop cancels this task or the channel is closed
channel: the TCP channel for the recently established connection with a GUI client
info: a Hash containing the message “type” and, for “login” messages, some info related to the login process, like the version of the connected GUI client and some user related info, like the userID or the oneTimeToken the GUI Client received upon successfully authenticating the user logging in.

void onLogin(const karabo::net::Channel::Pointer &channel, const karabo::util::Hash &info)¶

Handles a login request of a user on a GUI client. If the login credentials are valid, the current system topology is sent to the client.

Note

for clients >= 2.20 a login message with no OneTimeToken is interpreted by an authenticated GUI Server as a request for a read-only session. The GUI Server will respond to such messages with Access Level OBSERVER and the read-only flag set to true. For login messages with OneTimeToken the read-only flag will be always set to false and the Access Level will be the one returned by the Karabo Authentication Server.

Parameters

channel: the TCP channel between the GUI client and the GUI server
info: Hash with information needed to validate the login request.

void onTokenAuthorizeResult(const WeakChannelPointer &channel, const std::string &userId, const karabo::util::Version &cliVersion, const std::string &oneTimeToken, const karabo::net::OneTimeTokenAuthorizeResult &authResult)¶

Handles the result of the authorize one-time token operation performed as part of a GUI client login on behalf of an authenticated user.

Parameters

channel: the communication channel established with the GUI client logging in.
userId: the ID of the user on whose behalf the login is being made.
cliVersion: the version of the GUI client logging in.
oneTimeToken: the one-time token sent by the GUI client logging in.
authResult: the result of the one-time token authorization operation to be handled.

void onTemporarySessionExpiration(const ExpiredTemporarySessionInfo &info)¶

Handles a temporary session expired event communicated by the internal instance of the GuiServerTemporarySessionManager.

The expiration is handled by sending a message of type “onTemporarySessionExpired” to the client associated with the expired token. The message carries a Hash with paths “expiredToken” and “expirationTime”.

Parameters

info: data about the expired temporary session.

void onEndTemporarySessionNotice(const EminentExpirationInfo &info)¶

Handles a “temporary session about to expire” event.

The eminent temporary session end is handled by sending a message of type “onEndTemporarySessionNotice” to the client associated with the about to expire token. The message carries a Hash with paths “toExpireToken” and “secondsToExpiration”.

Parameters

info: data about the temporary session about to expire.

void onRead(const karabo::net::ErrorCode &e, WeakChannelPointer channel, karabo::util::Hash &info, const bool readOnly)¶

handles incoming data in the Hash info from channel. The further actions are determined by the contents of the type property in info. Valid types and there mapping to methods are given in the following table:

`onRead` allowed types¶
type	resulting method call
reconfigure	onReconfigure
execute	onExecute
getDeviceConfiguration	onGetDeviceConfiguration
getDeviceSchema	onGetDeviceSchema
getClassSchema	onGetClassSchema
initDevice	onInitDevice
killServer	onKillServer
killDevice	onKillDevice
startMonitoringDevice	onStartMonitoringDevice
stopMonitoringDevice	onStopMonitoringDevice
getPropertyHistory	onGetPropertyHistory
getConfigurationFromPast	onGetConfigurationFromPast
subscribeNetwork	onSubscribeNetwork
requestNetwork	onRequestNetwork
error	onGuiError
acknowledgeAlarm	onAcknowledgeAlarm
requestAlarms	onRequestAlarms
updateAttributes	onUpdateAttributes
projectUpdateAttribute	onProjectUpdateAttribute
projectBeginUserSession	onProjectBeginUserSession
projectEndUserSession	onProjectEndUserSession
projectSaveItems	onProjectSaveItems
projectLoadItems	onProjectLoadItems
projectListProjectManagers	onProjectListProjectManagers
projectListItems	onProjectListItems
projectListProjectsWithDevice	onProjectListProjectsWithDevice
projectListDomains	onProjectListDomains
requestGeneric	onRequestGeneric
subscribeLogs	<no action anymore>
setLogPriority	onSetLogPriority
beginTemporarySession	onBeginTemporarySession
endTemporarySession	onEndTemporarySession

Both upon successful completion of the request or in case of an exception the onRead function is bound to the channel again, maintaining the connection of the client to the gui-server.

Parameters

e: holds an error code if the eventloop cancel this task or the channel is closed
channel:
info:
readOnly:

void setTimeout(karabo::xms::SignalSlotable::Requestor &requestor, const karabo::util::Hash &input, const std::string &instanceKey)¶

Sets the appropriate timeout to a Requestor

If input has a “timeout” key, set the maximum value of that and the gui server timeout on the requestor, except if input.get<std::string>(instanceKey) is one instance of the classes in “ignoreTimeoutClasses”.

void forwardReconfigureReply(bool success, WeakChannelPointer channel, const karabo::util::Hash &input)¶

Callback helper for onReconfigure

Parameters

success: whether call succeeded
channel: who requested the call
input: will be copied to the key input of the reply message

void forwardHashReply(bool success, WeakChannelPointer channel, const karabo::util::Hash &info, const karabo::util::Hash &reply)¶

Callback helper for generic actions called by the gui server.

Parameters

success: whether call succeeded
channel: who requested the call
info: the input info Hash
reply: the reply from the remote device or an empty Hash on failure

void onRequestGeneric(WeakChannelPointer channel, const karabo::util::Hash &info)¶

Request a generic action internally. Generic interface to call slots that take a single Hash as argument and reply with a single Hash.

Parameters

channel: from which the request originates
info: is a Hash that should contain the slot information.
- type: requestGeneric
- instanceId: the instanceId to be called
- slot: the slot name of the instance
- empty: if this property is provided, the input Hash is not bounced back
- replyType (optional): the value of the key type in the reply to the client
- timeout (optional) [s]: account for the slot call a specified timeout in seconds!
- args: The Hash containing the parameters for the slot call

The forwardHashReply method is used to relay information to the gui client.

Returns:

In the default case, the return Hash is composed as follows::

success: boolean to indicate if the generic request was successful
reason: information on the error if not succesful otherwise empty
type: if specified in the input Hash, the replyType is used otherwise requestGeneric
request: the full input Hash information, including args
reply: The reply Hash of the instanceId

.. note: If the info Hash from the client provides an empty property, an empty Hash is sent back to the client instead of the input Hash.

void onReconfigure(WeakChannelPointer channel, const karabo::util::Hash &info)¶

Calls the Device::onReconfigure slot on the device specified in info.

The info should have the following entries:

string at deviceId defines the target device
Hash at configuration is the configuration update to apply
bool at reply: if given and true, success or failure will be reported back to channel by a message of type reconfigureReply that contains
- input: the Hash given here as info
- success: bool whether reconfiguration succeeded
- failureReason: string with failure reason
optional int at timeout: if a reply should be reported back, defines seconds of timeout. In case timeout is missing, timeout errors will report success as true but provides a failureReason mentioning the timeout

Parameters

channel: to potentially send “reconfigureReply”
info:

void onBeginTemporarySession(WeakChannelPointer channel, const karabo::util::Hash &info)¶

Handles a message of type “beginTemporarySession” by starting a temporary session on top of the current user-authenticated session (if there’s one). The session begining is an asynchronous operation whose completion (either successful or not) will be handled by the onBeginTemporarySessionResult method.

Parameters

channel: the TCP channel connecting to the client that requested the begining of the temporary session.
info: a Hash which is supposed to contain an “temporarySessionToken” whose value is a one-time token that must be successfuly authorized for the temporary session to be started.

void onBeginTemporarySessionResult(WeakChannelPointer channel, karabo::util::Schema::AccessLevel levelBeforeTemporarySession, const BeginTemporarySessionResult &result)¶

Handles the result of an “beginTemporarySession” request sent by a connected client.

Parameters

channel: the TCP channel connecting to the client that requested the temporary session that will be used to send a message of type “onBeginTemporarySession” with the begin operation results back to the client.
levelBeforeTemporarySession: sent by the client as part of the begin temporary session request to be sent back when the temporary session ends.
result: the results of the begin temporary session operation that will be sent back to the client.

void onEndTemporarySession(WeakChannelPointer channel, const karabo::util::Hash &info)¶

Handles a message of type “endTemporarySession” by ending the current temporary session (if there’s one). The end of the session is performed synchronously (there’s no I/O involved) and its results are transmitted back to the client through a message of type “onEndTemporarySession”.

Note

the hash with the results of the ending operation sent back to the requesting client has the fields “success”, “reason” and “temporarySessionToken” (an echo of the token provided in the request).

Parameters

channel: the TCP channel connecting to the client that requested the end of the temporary session. Will be used to send the response back to the client.
info: a Hash which is supposed to contain an “temporarySessionToken” whose value is a one-time token that must match the one associated to the temporary session being terminated.

void forwardExecuteReply(bool success, WeakChannelPointer channel, const karabo::util::Hash &input)¶

Callback helper for onExecute

Parameters

success: whether call succeeded
channel: who requested the call
input: will be copied to the key input of the reply message

void onExecute(WeakChannelPointer channel, const karabo::util::Hash &info)¶

Calls a command slot on a specified device.

The info should have the following entries:

string at deviceId defines the target device
string at command is the slot to call
bool at reply: if given and true, success or failure will be reported back to channel by a message of type executeReply that contains
- input: the Hash given here as info
- success: bool whether execution succeeded
- failureReason: string with failure reason
optional int at timeout: if a reply should be reported back, defines seconds of timeout. In case timeout is missing, timeout errors will report success as true but provides a failureReason mentioning the timeout
Parameters
- channel:
- info:

void onInitDevice(WeakChannelPointer channel, const karabo::util::Hash &info)¶

Enqueues a future device instantiation. The relevant information will be stored in m_pendingDeviceInstantiations and initSingleDevice will take care of the actual instantiation when it is called by the instantiation timer.

Parameters

channel:
info:

void initSingleDevice(const boost::system::error_code &error)¶

Instructs the server at serverId to try initializing the device at deviceId as given in info. The reply from the device server is registered to the initReply callback.

NOTE: This should only be called by m_deviceInitTimer

Parameters

error:

void initReply(WeakChannelPointer channel, const std::string &givenDeviceId, const karabo::util::Hash &givenConfig, bool success, const std::string &message, bool isFailureHandler)¶

is the callback for the onInitDevice method. It is called upon reply from the device server handling the initialization request. The reply is passed to the calling channel in form of a hash message with type=initReply, deviceId, success and message fields.

Parameters

channel:
givenDeviceId:
givenConfig:
success:
message:

void onGetDeviceConfiguration(WeakChannelPointer channel, const karabo::util::Hash &info)¶

requests the current device configuration for deviceId specified in info and sends it back in a hash message on channel. The message contains the following fields: type=deviceConfiguration, deviceId and configuration. The configuration is retrieved using the device client interface.

Parameters

channel:
info:

void onKillServer(WeakChannelPointer channel, const karabo::util::Hash &info)¶

instructs the server specified by serverId in info to shutdown.

Parameters

info:

void onKillDevice(WeakChannelPointer channel, const karabo::util::Hash &info)¶

instructs the device specified by deviceId in info to shutdown.

Parameters

info:

void onStartMonitoringDevice(WeakChannelPointer channel, const karabo::util::Hash &info)¶

Registers a monitor on the device specified by deviceId in info Upon changes of device properties they will be forwarded to channel from a handler for changes in configurations of monitored devices that is kept internally by the gui-server.

Only one channel per client is maintained for passing monitoring information and only one monitor is registered by the gui-server for any number of clients monitoring deviceId.

After successful registration the current device configuration is returned by calling onGetDeviceConfiguration for channel.

Parameters

channel:
info:

void onStopMonitoringDevice(WeakChannelPointer channel, const karabo::util::Hash &info)¶

De-registers the client connected by channel from the device specified by deviceId in info. If this is the last channel monitoring deviceId the device is removed from the set of devices monitored by the device-client.

Parameters

channel:
info:

void onGetClassSchema(WeakChannelPointer channel, const karabo::util::Hash &info)¶

requests a class schema for the classId on the server specified by serverId in info. This is done through the device client. A hash reply is sent out over channel containing type=classSchema, serverId, classId and schema.

Parameters

channel:
info:

void onGetDeviceSchema(WeakChannelPointer channel, const karabo::util::Hash &info)¶

requests a device schema for the device specified by deviceId in info. This is done through the device client. A hash reply is sent out over channel containing type=deviceSchema, deviceId, and schema.

Parameters

channel:
info:

void onGetPropertyHistory(WeakChannelPointer channel, const karabo::util::Hash &info)¶

requests the history for a property on deviceId in the time range t0 and t1 as specified in info. Additional the maximum number of data points may be specified in maxNumData. The request is asynchronously sent to the device logger logging information for deviceId. The reply from the logger is then forwarded to the client on channel using the propertyHistory history callback.

Parameters

channel:
info:

void propertyHistory(WeakChannelPointer channel, bool success, const std::string &deviceId, const std::string &property, const std::vector<karabo::util::Hash> &data)¶

Callback for onGetPropertyHistory. It forwards the history reply in data for the property on deviceId to the client connected on channel. The hash reply is of the format type=propertyHistory, deviceId, property, success, data and failureReason which states the failure reason if any.

Parameters

channel:
success: whether the request succeeded
deviceId:
property:
data:

void onGetConfigurationFromPast(WeakChannelPointer channel, const karabo::util::Hash &info)¶: Request configuration for a device at point in time time as specified in info. The info hash can as well have a preview boolean which is send back to the client. The request is asynchronously sent to the device logger logging information for deviceId. The reply from the logger is then forwarded to the client on channel using the configurationFromPast history callback in case of success or configurationFromPastError for failures.

void configurationFromPast(WeakChannelPointer channel, const std::string &deviceId, const std::string &time, const bool &preview, const karabo::util::Hash &config, const karabo::util::Schema&, const bool configAtTimepoint, const std::string &configTimepoint)¶: Success callback for onGetDeviceConfiguration

void configurationFromPastError(WeakChannelPointer channel, const std::string &deviceId, const std::string &time)¶: Failure callback for onGetDeviceConfiguration

std::string getDataReaderId(const std::string &deviceId) const¶

Helper for history retrieval functions

Return

id of DataLogReader device to ask for history

Parameters

deviceId: of the device whose history is searched for

void onSubscribeNetwork(WeakChannelPointer channel, const karabo::util::Hash &info)¶

registers the client connected on channel to a pipe-lined processing channel identified by channelName in info in case subscribe is true. In case the pipe-lined processing channel is already connected to the gui-server no futher action is taken. Otherwise, a new connection is opened, set to copy and dropping behaviour in case the gui-server is busy, and with a maximum update frequency as defined by the delayOnInput property of the gui server. Network data from the pipe-lined processing connection is handled by the onNetworkData callback.

In this way only one connection to a given pipe-lined processing channel is maintained, even if multiple gui-clients listen to it. The gui-server thus acts as a kind of hub for pipe-lined processing onto gui-clients.

If subscribe is set to false, the connection is removed from the list of registered connections, but is kept open.

Parameters

channel:
info:

void onSubscribeLogs(WeakChannelPointer channel, const karabo::util::Hash &info)¶

Kept to reply back that log subscription not supported anymore after 2.16.X

Parameters

channel:
info:

void onSetLogPriority(WeakChannelPointer channel, const karabo::util::Hash &info)¶

sets the Log priority on a server. The info hash should contain a priority string and a instanceId string.

Parameters

channel:
info:

void forwardSetLogReply(bool success, WeakChannelPointer channel, const karabo::util::Hash &input)¶

Callback helper for onSetLogPriority

Parameters

success: whether call succeeded
channel: who requested the call
input: will be copied to the key input of the reply message

void onRequestNetwork(WeakChannelPointer channel, const karabo::util::Hash &info)¶

Receives a message from the GUI client that it processed network data from an output channel with name channelName in the info Hash.

Parameters

channel:
info:

void onNetworkData(const std::string &channelName, const karabo::util::Hash &data, const karabo::xms::InputChannel::MetaData &meta)¶

handles data from the pipe-lined processing channels the gui-server is subscribed to and forwards it to the relevant client channels, which have connected via onSubscribeNetwork. The incoming data is forwarded to all channels connected to this pipe-lined processing channel using the following hash message format: type=networkData, name is the channel name and data holding the data.

Parameters

channelName: name of the InputChannel that provides these data
data: the data coming from channelName
meta: corresponding meta data

void sendSystemTopology(WeakChannelPointer channel)¶

sends the current system topology to the client connected on channel. The hash reply contains type=systemTopology and the systemTopology.

Parameters

channel:

void instanceNewHandler(const karabo::util::Hash &topologyEntry)¶

sends the current system topology to the client connected on channel. The hash reply contains type=systemVersion and the systemVersion.

Parameters

channel:

void instanceChangeHandler(const karabo::util::Hash &instChangeData)¶

Handles events related to instances: new instance, instance updated, instance gone.

: Its signature matches karabo::core::InstanceChangeThrottler::InstanceChangeHandler).

void devicesChangedHandler(const karabo::util::Hash &what)¶

Acts upon incoming configuration updates from one or more devices. It is called back by a monitor registered on the device client. The reconfiguration contained in the what hash is forwarded to any channels connected to the monitor by onStartMonitoringDevice.

The message type of the hash sent out is type=”deviceConfigurations”. The hash has a second first level key, named “configurations”, whose value is a hash with the deviceIds as keys and the configuration changes for the corresponding deviceId as values.

Parameters

what: A hash containing all the configuration changes that happened to one or more monitored devices since the last update. Each node under the key “configurations” has the ‘deviceId’ as key and the changed configurations as a value of type Hash.

void slotGetClientSessions(const karabo::util::Hash &options)¶

Retrieve information about the current client sessions of the GUI server.

The reply is a hash with a single key, “clientSessions”, whose value is a vector of hashes with one hash per existing client connection. The hash for each connection has the following keys:

. "clientVersion": string with the version of the connected
  client;

. "sessionStartTime": UTC timestamp of session start time as
  an ISO8601 string;

. "sessionToken": one-time token for the client session.
  Will be empty if the GUI Server is not in authenticated
  mode;

. "temporarySessionStartTime": UTC timestamps of temporary
  session start time as an ISO8601 string. If there's no
  active temporary session on top of the client session, an
  empty string is returned;

. "temporarySessionToken": one-time token for the temporary
  session (an empty string if there's no active temporary
  session).

Parameters

options: Hash with a single key “onlyWithTempSession” and a boolean value that when “true” makes the slot include only client sessions with active temporary sessions in the reply.

void slotProjectUpdate(const karabo::util::Hash &info, const std::string &instanceId)¶

Called from projectManagers to notify about updated Projects

Parameters

info: the info hash containing the information about the updated projects
instanceId: the instance id of the project manager device

void slotDumpToLog()¶

Slot to dump complete debug info to log file

Same info as received from ‘slotDumpDebugInfo’ with empty input Hash

void slotNotify(const karabo::util::Hash &info)¶

Slot to send a notification message to all clients connected - replies empty Hash

Parameters

info: a Hash with following keys
- ”message”: a string containing the notification type
- ”contentType”: a string defining the type of notification as the GUI client understands it
  - ”banner” means message will go to the GUI banner. Therefore it will be stored in the “bannerMessage” property of the GuiServerDevice and sent to any client that connects.
  - other types will likely just be shown in a pop-up window of the client

void slotBroadcast(const karabo::util::Hash &info)¶

Slot to send a Hash to the GUI clients connected - replies empty Hash

WARNING: No checks are performed on this slot. This slot can possibly disconnect all clients. Do not use it unless you understand the risks.

Parameters

info: a Hash with at least the following keys.
- ”message”: a Hash that will be sent to the client(s). It should contain a “type” string.
- ”clientAddress”: a string containing the GUI client address as coded in the slotDumpDebugInfo results. If the value for this key is an empty string, all clients will be notified.

void requestScene(const karabo::util::Hash &info)¶

Slot to provide scene

Parameters

info: Hash with key “name” that provides string identifying which scene

karabo::util::Hash getDebugInfo(const karabo::util::Hash &info)¶: Helper for ‘slotDumpToLog’ and ‘slotDumpDebugInfo’

void slotDisconnectClient(const std::string &client)¶

Slot to force disconnection of client. Reply is whether specified client found.

Parameters

client: string to identify client, as can be received via slotDumpDebugInfo(Hash(“clients”, 0))

void updateNewInstanceAttributes(const std::string &deviceId)¶

Called from instanceNewHandler to handle schema attribute updates which were received at initialization time. The slotUpdateSchemaAttributes slot is invoked if any updates are pending.

Parameters

deviceId: the instance id of the new device

void slotAlarmSignalsUpdate(const std::string &alarmServiceId, const std::string &type, const karabo::util::Hash &updateRows)¶

A slot called by alarm service devices if they want to notify of an alarm update updateType is a string of any of the following: init, update, delete, acknowledgeable, deviceKilled, refuseAcknowledgement

Parameters

alarmServiceId: the instance id of the service device
type: the type of the update: can be alarmUpdate, alarmInit
updateRows: the rows which should be updated. This is a Hash of Hashes, were the unique row indices, as managed by the alarm service are keys, and the values are Hashes of the form updateType->entry

entry is a Hash with the following entries:

timeOfFirstOccurrence -> string: timestamp of first occurrence of alarm trainOfFirstOccurrence -> unsigned long long: train id of first occurrence of alarm timeOfOccurrence -> string: timestamp of most resent occurrence of alarm trainOfOccurrence -> unsigned long long: train id of most resent occurrence of alarm needsAcknowledging -> bool: does the alarm require acknowledging acknowledgeable -> bool: can the alarm be acknowledged deviceId -> string: deviceId of device that raised the alarm property -> string: property the alarm refers to id -> the unique row id

it send the following Hash to the client (lossless)

Hash h(“type”, type, “instanceId”, alarmServiceId, “rows”, updateRows);

void onAcknowledgeAlarm(WeakChannelPointer channel, const karabo::util::Hash &info)¶

Called if the client wants to acknowledge an alarm, by sending a message of type “acknowledgeAlarm”

Parameters

channel: the channel the client is connected to
info: the message from the client. Should contain the unique row ids of the alarms to acknowledge. It is a Hash of Hashes of the same form as described for slotAlarmSignalsUpdate, where the keys give the unique row indices

void onRequestAlarms(WeakChannelPointer channel, const karabo::util::Hash &info, const bool replyToAllClients = false)¶

Called if a client sends a message of type “requestAlarms”

Parameters

channel: the channel the calling client is connected to
info: message passed from the client. It is a Hash that needs to contain a string field “alarmInstanceId”, which either contains a specifiy alarm service’s instance id, or an empty string. In the latter case a request for current alarms is forwarded to all known alarm services, otherwise to the specific one. Replies from the alarm services trigger calling “onRequestedAlarmsReply” asynchroniously.
replyToAllClients: If true, reply to all clients instead of only the requesting client.

void onRequestedAlarmsReply(WeakChannelPointer channel, const karabo::util::Hash &reply, const bool replyToAllClients)¶

Callback executed upon reply from an alarm service to “onRequestAlarms”. instanceId -> string: instance id of the replying alarm service alarms -> Nested Hash of form given in “slotAlarmSignalsUpdate”

Parameters

channel: the client channel the request came from, bound by “onRequestAlarms”
reply: reply from the alarm service, expected to contain fields
replyToAllClients: If true, reply to all clients

It sends out a Hash of form: Hash h(“type”, “alarmInit”, “instanceId”, reply.get<std::string>(“instanceId”), “rows”, reply.get<Hash>(“alarms”));

void onUpdateAttributes(WeakChannelPointer channel, const karabo::util::Hash &info)¶

Executed when the gui requests an update to schema attributes via the updateAttributes signal.

Parameters

channel: gui channel that requested the update
info: updated attributes, expected to be of form Hash(“instanceId”, str, “updates”, vector<Hash>) where each entry in updates is of the form Hash(“path”, str, “attribute”, str, “value”, valueType)

void onRequestedAttributeUpdate(WeakChannelPointer channel, const karabo::util::Hash &reply)¶

Callback for onUpdateAttributes

Parameters

channel: gui channel that requested the update
reply: reply from the device that performed the attribute update. Is of form Hash(“success” bool, “instanceId”, str, “updatedSchema”, Schema, “requestedUpdate”, vector<Hash>) where success indicates a successful update, instanceId the device that performed the update updatedSchema the new valid schema, regardless of success or not, and requestedUpdates the original update request, as received through onUpdateAttributes

void typeAndInstanceFromTopology(const karabo::util::Hash &topologyEntry, std::string &type, std::string &instanceId)¶

Returns the instance type and instance id from a topology entry

Parameters

topologyEntry: a Hash of the topology format
type: string which will afterwards contain type
instanceId: string which will be filled with the instance id

bool allowLock() const¶

This device may not be locked

Return: false

void registerPotentialProjectManager(const karabo::util::Hash &topologyEntry)¶

Checks if an instance at instanceId is a ProjectManager. If so, register it to the list of known project services

Parameters

topologyEntry: the topology Hash, from which the class of instanceId will be deduced

std::vector<std::string> getKnownProjectManagers() const¶

Return a list of project services known to this GUI server

Return

void onProjectBeginUserSession(WeakChannelPointer channel, const karabo::util::Hash &info)¶

Initialize a configuration database session for a user. The token should continue to be passed to subsequent database interactions to identify this session.

Parameters

channel: from which the request originates
info: is a Hash that should contain:
- projectManager: project manager device to forward request to
- token: token of the database user For the reply written to channel see the documentation of karabo.bound_devices.ProjectManager

void onProjectEndUserSession(WeakChannelPointer channel, const karabo::util::Hash &info)¶

End a configuration database session for a user.

Parameters

channel: from which the request originates
info: is a Hash that should contain:
- projectManager: project manager device to forward request to
- token: token of the database user For the reply written to channel see the documentation of karabo.bound_devices.ProjectManager

void onProjectSaveItems(WeakChannelPointer channel, const karabo::util::Hash &info)¶

Save items to the project database

Parameters

channel: from which the request originates
info: is a Hash that should contain:
- projectManager: project manager device to forward request to
- token: token of the database user - identifies the session
- items: a vector of Hashes where each Hash is of the form:
  - xml: xml of the item
  - uuid: uuid of the item
  - overwrite: Boolean indicating behavior in case of revision conflict
  - domain: to write this item to. For the reply written to channel see the documentation of karabo.bound_devices.ProjectManager

void onProjectLoadItems(WeakChannelPointer channel, const karabo::util::Hash &info)¶

Load items from project database

Parameters

channel: from which the request originates
info: is a Hash that should contain:
- projectManager: project manager device to forward request to
- token: token of the database user - identifies the session
- items: a vector of Hashes where each Hash is of the form:
  - uuid: uuid of the item
  - revision (optional): revision to load. If not given the newest revision will be returned
  - domain: to load this item from. For the reply written to channel see the documentation of karabo.bound_devices.ProjectManager

void onProjectListProjectManagers(WeakChannelPointer channel, const karabo::util::Hash &info)¶

Request the list of project manager devices known to the GUI server Will write to the calling channel a Hash where “type” = projectListProjectManagers and “reply” is a vector of strings containing the project manager device ids. For the reply written to channel see the documentation of karabo.bound_devices.ProjectManager

Parameters

channel: from which the request originates
info: is given for compatability with all other calls but not further evaluated.

void onProjectListItems(WeakChannelPointer channel, const karabo::util::Hash &info)¶

Request a list of the items present in a domain. Optionally, an item type filter can be specified

Parameters

channel: from which the request originates
info: is a Hash that should contain:
- projectManager: project manager device to forward request to
- token: token of the database user - identifies the session
- domain: domain to list items from
- item_types: a vector of strings indicating the itemtypes to filter for. For the reply written to channel see the documentation of karabo.bound_devices.ProjectManager

void onProjectListDomains(WeakChannelPointer channel, const karabo::util::Hash &info)¶

Request a list of the domains in the database.

Parameters

channel: from which the request originates
info: is a Hash that should contain:
- projectManager: project manager device to forward request to
- token: token of the database user - identifies the session For the reply written to channel see the documentation of karabo.bound_devices.ProjectManager

void onProjectUpdateAttribute(WeakChannelPointer channel, const karabo::util::Hash &info)¶

Update item attributes in the project database

Parameters

channel: from which the request originates
info: is a Hash that should contain:
- projectManager: project manager device to forward request to
- token: token of the database user - identifies the session
- items: a vector of Hashes where each Hash is of the form:
  - domain: to load this item from
  - uuid: uuid of the item
  - item_type: indicate type of item which attribute should be changed
  - attr_name: name of attribute which should be changed
  - attr_value: value of attribute which should be changed For the reply written to channel see the documentation of karabo.bound_devices.ProjectManager

void forwardReply(WeakChannelPointer channel, const std::string &replyType, const karabo::util::Hash &reply)¶

Forward a reply from a remote slot call to a requesting GUI channel.

Parameters

channel: to forward reply to
replyType: type of reply
reply: the reply to forward

bool checkProjectManagerId(WeakChannelPointer channel, const std::string &deviceId, const std::string &type, const std::string &reason)¶

Check if a given project manager identified by id is known in the distributed system

Return

true if the project manager id exists in the distributed system

Parameters

channel: to forward a failure message to if not
deviceId: of the project manager device
type: of the request

std::string getChannelAddress(const karabo::net::Channel::Pointer &channel) const¶: Utility for getting a “name” from client connections.

void tryToUpdateNewInstanceAttributes(const std::string &deviceId, const int callerMask)¶: Possibly update schema attributes on device

void onUpdateNewInstanceAttributesHandler(const std::string &deviceId, const karabo::util::Hash &response)¶: Response handler for updating schema attributes on device

bool skipExecutionTimeout(const std::string &deviceId)¶

Helper Function to identify whether a device belongs to the timeout violation list TODO: remove this once “fast slot reply policy” is enforced

returns true if a .timeout() should be skipped on execution requestor

void recalculateTimingOutDevices(const karabo::util::Hash &topologyEntry, const std::vector<std::string> &timingOutClasses, bool clearSet)¶: Helper Function to recalculate the list of timeout violating devices from the list of offending classes TODO: remove this once “fast slot reply policy” is enforced

Private Static Attributes

const std::string m_errorDetailsDelim¶: In reported failure reasons, this delimiter comes between short message and details like a trace.

class GuiServerTemporarySessionManager¶

#include <GuiServerTemporarySessionManager.hh>

Manages temporary sessions on top of user-authenticated GUI Sessions.

Takes care of authorizing one-time temporary session tokens to start temporary sessions and of communicating temporary sessions about to expire or already expired.

Inherits from std::enable_shared_from_this< GuiServerTemporarySessionManager >

Public Functions

GuiServerTemporarySessionManager(const std::string &topic, const std::string &authServerUrl, unsigned int temporarySessionDurationSeconds, unsigned int temporarySessionEndNoticeSeconds, EminentExpirationHandler onEminentExpiration, ExpirationHandler onExpiration)¶

Construct a new Gui Server Temporary Session Manager object.

Parameters

topic: the Karabo topic against which temporary session tokens will be authorized.
authServerUrl: the URL of the authentication server to use for authorizing one-time temporary session tokens.
temporarySessionDurationSeconds: the duration, in seconds, to be enforced for temporary sessions.
temporarySessionEndNoticeSeconds: the time in advance, in seconds, to communicate about an eminent end of temporary session event.
onEminentExpiration: handler for temporary sessions about to expire.
onExpiration: handler for expired temporary sessions.

void beginTemporarySession(const std::string &temporarySessionToken, const BeginTemporarySessionHandler &onBeginTemporarySession)¶

Assynchronously starts a new temporary session for a given one-time temporary session token.

Note

Calls the registered BeginTemporarySessionHandler with the results of the beginTemporarySession operation.

Parameters

temporarySessionToken: the one-time temporary session token to be authorized and bound to the started temporary session.
onBeginTemporarySession: handler for begin temporary session events (either successful or failed).

EndTemporarySessionResult endTemporarySession(const std::string &temporarySessionToken)¶

Synchronously terminates a temporary session referenced by a given temporary session token.

Return

a structure with the endTemporarySession operation results.

Note

an error due to a beginTemporarySession token not found isn’t necessarily an error from the GUI client point of view. In the unlikely scenario of an endTemporarySession request that reaches the GUI server while the expiration check that will detect the expiration of the same token is already running, the end temporary session request will “fail” with a “token not found” message. It is up to the GUI client to decide what to do in such cases - maybe keep track of an “over the wire” end temporary session request token and ignore any error related to it if an expiration notification is received for that token between the request dispatch and the arrival of its reponse.

Parameters

temporarySessionToken: the one-time temporary session token bound to the session to be terminated.

Private Functions

void checkTemporarySessionsExpirations(const boost::system::error_code &error)¶

Checks the currently active temporary sessions removing the expired ones after invoking the registered expiration handlers for each of them.

Parameters

error: an error code sent by boost::asio that if different from 0 indicates that the timer pulse that should invoke this check at some future point has been cancelled.

void onTokenAuthorizeResult(const std::string &temporarySessionToken, const BeginTemporarySessionHandler &onBeginTemporarySession, const karabo::net::OneTimeTokenAuthorizeResult &authResult)¶

Handles the result of a temporary session token authorization request, updating the internal state of the manager and communicating the outcome of the begin temporary session request to the external requestor.

Parameters

temporarySessionToken: the one-time temporary session token whose authorization was requested.
onBeginTemporarySession: handler for begin temporary session events (either successful or failed).
authResult: the result of the authorization of the temporary session token provided by the external caller of the begin temporary session operation.

void scheduleNextExpirationsCheck()¶

Schedules the next expiration check if there’s any esalation to be checked.

Note: this method must be called with the m_tempSessionsMutex locked.

class IndexBuilderService¶

#include <FileLogReader.hh>

A singleton class for building logger indices from logger files. It calls karabo-idxbuild with a list of command line arguments.

Inherits from std::enable_shared_from_this< IndexBuilderService >

Public Functions

void buildIndexFor(const std::string &commandLineArguments)¶

Build an index by calling karabo-idxbuild with the supplied command line arguments

Parameters

commandLineArguments:

Public Static Functions

static Pointer getInstance()¶

Return a pointer to a singleton instance of IndexBuilderService. If no instance exists one is created.

Return

Private Functions

bool allowLock() const¶

This device may not be locked

Return: false

class InfluxDataLogger¶

Inherits from karabo::devices::DataLogger

Public Functions

void preDestruction()¶: Override preDestruction from Device class

Protected Functions

void initializeLoggerSpecific()¶: Do some actions here that may require asynchronous logic … and, finally, startConnection() should be called This function may be overridden by derived classes but at the end the ‘startConnection’ function should be called as a last step of initialization

void flushImpl(const std::shared_ptr<SignalSlotable::AsyncReply> &aReplyPtr)¶: “Flush” data accumulated in the internal cache to the external storage (file, database,…)

struct InfluxDeviceData¶

Inherits from karabo::devices::DeviceData

Public Functions

void handleChanged(const karabo::util::Hash &config, const std::string &user)¶

Called when configuration updates arrive for logging

Parameters

config: a Hash with the updates and their timestamps
the: user responsible for this update - if any

void login(const karabo::util::Hash &configuration, const std::vector<std::string> &sortedPaths)¶

Helper to store logging start event

Parameters

configuration: full device configuration received when logging starts
sortedPaths: full paths of configuration, sorted by increasing timestamp

void handleSchemaUpdated(const karabo::util::Schema &schema, const karabo::util::Timestamp &stamp)¶

Called when a Schema update arrive for logging

Parameters

schema: - the new one
stamp: - the timestamp to be assigned for that update

unsigned int newPropLogRate(const std::string &propPath, karabo::util::Epochstamp currentStamp, std::size_t currentSize)¶

Calculates what the value of the property logging rate of the device will be when the logging of a value with a given size and a given timestamp is taken into account.

Return

The updated value of the property logging rate, in bytes/sec, taking the logging of the value into account.

Parameters

prop: The path of the property whose current logging rate will be evaluated.
currentStamp: The current property update timestamp.
currentSize: The size for the new data to be logged - this is used along with the other records in the current log rating window to calculate the new value for the property logging rate.

unsigned int newSchemaLogRate(std::size_t schemaSize)¶

Calculates what the value of the schema logging rate of the device will be when the logging of a schema with a given size is taken into account. As schemas currently don’t have associated time information, the current system time is used for all the timing references.

Return

The updated value of the schema logging rate, in bytes/sec, taking the logging of the schema into account.

Parameters

schemaSize: The size for the new schema to be logged - this is used along with the other records in the current log rating window to calculate the new value for the schema logging rate.

bool logNewSchema(const std::string &schemaDigest, const std::vector<char> &schemaArchive)¶

Logs a new schema into the corresponding device’s __SCHEMA measurement. It is assumed that the verification of the uniquiness of the device schema has already been verified based on its digest.

Return

true If the new schema has been successfuly submitted for logging.

Return

false If the logging of the new schema has not been submitted for logging. Currently, this happens if logging the new schema would be above the allowed schema logging rate threshold for a device.

Parameters

schemaDigest: The digest (assumed unique) of the new schema to be saved.
schemaArchive: The serialised schema to be saved

void logRejectedData(const std::vector<RejectedData> &rejects, unsigned long long ts)¶

Logs the given set of rejected data in the BAD__DATA measurement and to the Karabo log. To avoid spanning of the Karabo log, log is emmitted for each device only once in a period of 30 secs.

Parameters

rejects: The rejected data to be logged.
ts: An epoch with the precision expected in the InfluxDb.

void logRejectedDatum(const RejectedData &rejects)¶

Logs the given rejected data record in the BAD__DATA measurement and to the Karabo log. To avoid spanning of the Karabo log, log is emmitted for each device only once in a period of 30 secs.

Parameters

rejects: The rejected data to be logged.

struct LoggingRecord¶

#include <InfluxDataLogger.hh>

The size, in characters, and the epoch seconds of a device log entry saved to Influx.

Used for calculating the logging rates associated to a device.

class InfluxLogReader¶

Inherits from karabo::devices::DataLogReader

Private Functions

void asyncDataCountForProperty(const std::shared_ptr<PropertyHistoryContext> &context)¶

Triggers the retrieval of the number of data points for a given device property during a time interval.

Parameters

context:

void onDataCountForProperty(const karabo::net::HttpResponse &dataCountResp, const std::shared_ptr<PropertyHistoryContext> &ctxt)¶

Handles the retrieval of the number of data points for an ongoing GetPropertyHistory process. Responsible for invoking the appropriate async method for retrieving the property values depending on the number of data points received.

Parameters

dataCountResponse:
context:

void asyncGetPropertyValues(const std::shared_ptr<PropertyHistoryContext> &ctxt)¶

Triggers the retrieval of the property values in an ongoing GetPropertyHistory process.

Parameters

context:

void asyncGetPropertyValuesMean(const std::shared_ptr<PropertyHistoryContext> &ctxt)¶

Triggers the retrieval of the property values mean in an ongoing GetPropertyHistory process. This is used when the number of available data points for the property is larger than the maximum requested by the slot caller and all values are scalar numbers. The UINT64 properties are included in this despite being reinterpreted as INT64 on the backend and possibly returning incorrect data.

Parameters

context:

void asyncGetPropertyValuesSamples(const std::shared_ptr<PropertyHistoryContext> &ctxt)¶

Triggers the retrieval of the property values samples in an ongoing GetPropertyHistory process. This is used when the number of available data points for the property is larger than the maximum requested by the slot caller.

Parameters

context:

void onPropertyValues(const karabo::net::HttpResponse &valuesResp, const std::string &columnPrefixToRemove, const std::shared_ptr<PropertyHistoryContext> &ctxt)¶

Handles the retrieval of the values of a property in an ongoing GetPropertyHistory process. Responsible for transforming the json formatted values received from InfluxDbClient into a vector of hashes suitable to be returned to the slot caller. Also responsible for replying to the slot caller.

Parameters

valuesResp:
columnPrefixToRemove:
context:

void onMeanPropertyValues(const karabo::net::HttpResponse &valuesResp, const std::shared_ptr<PropertyHistoryContext> &ctxt)¶

Handles the retrieval of the values of a property in an ongoing GetPropertyHistory process. Responsible for transforming the json formatted values received from InfluxDbClient into a vector of hashes suitable to be returned to the slot caller. This function extends the functionality of onPropertyValues while keeping the property history protocol.

Also responsible for replying to the slot caller.

Parameters

valuesResp:
context:

std::string unescapeLoggedString(const std::string &loggedStr)¶

Unescapes a logged string. A logged string has its new lines mangled, then its double slashes escaped and then its double quotes escaped. This functions applies those transformations in the reverse order.

Return

The unescaped original string.

Parameters

loggedStr: The string as it has been escaped by the Influx Logger.

bool handleHttpResponseError(const karabo::net::HttpResponse &httpResponse, const karabo::xms::SignalSlotable::AsyncReply &asyncReply)¶

Handles a given Http response whenever it indicates an error.

In the InfluxDb client <-> server communication context, any response with a status code greater or equal to 300 is considered an error and will be handled by this method.

The error handling consists of sending the appropriate error reply to the caller of the InfluxLogReader slot affected by the error and of optionally disconnecting the InfluxDbClient used by the slot.

Return

true if the httpResponse indicated an error that has been handled. false if the httpResponse didn’t indicate an error.

Parameters

httpResponse: the response that potentially indicates an error.
asyncReply: the reply to be sent to the caller of the slot where the error happened.

karabo::util::Epochstamp toEpoch(unsigned long long timeFromInflux) const¶: Convert a time point from influx to karabo Epochstamp

karabo::util::Hash buildInfluxClientConfig(const std::string &dbUrlForSlot) const¶

Builds and returns the configuration Hash for instantiating an InfluxDbClient to be used in the execution of one of the slots supported by the reader.

Return

the configuration Hash for the InfluxDbClient.

Parameters

dbUrlForSlot: the URL to be used in the configuration - each slot can use a different database URL.

class PropertyTest¶

#include <PropertyTest.hh>

The PropertyTest device includes all types Karabo knows about in it’s expected parameter section. It is a test device to assure changes to the framework do not result in broken types.

Inherits from karabo::core::Device<>

Private Functions

void orderTest_slotStart()¶

The order test started with this slot works as follows:

’stringProperty’ defines the ‘other’ PropertyTest device supposed to send messages to us
’int32Property’ defines how many messages it should send
the number of messages and our own id are transferred to the other device
we connect our ‘slotCount’ to the other’s ‘signalCount’
we call the other’s ‘slotStartCount’ which will trigger sending messages to us, alternating between direct calls to our ‘slotCount’ and emitting ‘signalCount’ with count arguments starting from 0
we keep track of all counts received and their order (so do not run with billions of counts!)
end of messaging is signaled to us via a call with count = -1
we publish the number of received messages and those counts (well, up to 1000 only) that are not in order as “orderTest.receivedCounts” and “orderTest.nonConsecutiveCounts”, respectively.

struct PropFileInfo¶: #include <FileLogReader.hh>
A compound structure holding data on an logger archive file.

The karabo::io Namespace¶

namespace karabo::io¶

Namespace for package io

Typedefs

typedef std::vector<char> BufferType¶

typedef InputElement INPUT_ELEMENT¶

typedef OutputElement OUTPUT_ELEMENT¶

Functions

std::ostream &operator<<(std::ostream &os, const BufferSet &bs)¶

template <class T>

void loadFromFile(T &object, const std::string &filename, const karabo::util::Hash &config = karabo::util::Hash())¶

Load an object of class T from a file. The configuration determines which access and de-serialzation methods to use.

Parameters

object: to load data into
filename: of the file to load from. The input chose depends on the file extension:
- .h5: Hdf5File
- .bin: BinaryFile
- .others: TextFile
config: for the Input class that will be used

template <class T>

void saveToFile(const T &object, const std::string &filename, const karabo::util::Hash &config = karabo::util::Hash())¶

Save an object of class T to a file. The configuration determines which access and serialzation methods to use.

Parameters

object: to save
filename: of the file to load from. The input chose depends on the file extension:
- .h5: Hdf5File
- .bin: BinaryFile
- .others: TextFile
config: for the Output class that will be used

void saveToFile(const std::vector<char> &buffer, const std::string &filename)¶

Save a buffer into a file

Parameters

buffer:
filename:

void loadFromFile(std::vector<char> &buffer, const std::string &filename)¶

Load a buffer from a file

Parameters

buffer:
filename:

template <class T>

std::string getIODataType()¶

Get the I/O datatype for type T in terms of the Karabo class id

Return

template <>
template<> std::string getIODataType<std::vector<char>>()¶

class AbstractInput¶

#include <AbstractInput.hh>

The AbstractInput class is the base for input classes in Karabo

Their specific implementation defines how the input acquires data. This can be either through a network or in memory connection, or through a data source accessing persited data.

Inherits from std::enable_shared_from_this< AbstractInput >

Subclassed by karabo::io::Input< T >

Public Functions

virtual void reconfigure(const karabo::util::Hash &input)¶

Reconfigure the input, e.g. to use a different data source

Parameters

input:

void setInstanceId(const std::string &instanceId)¶

Register a SignalSlotable instance to this input

Parameters

instanceId:

const std::string &getInstanceId() const¶

Get the registered SignalSlotable instance

Return

void setInputHandlerType(const std::string &language, const std::string &inputType)¶

Set language handling input parsing

Parameters

language: may be C++ or PYTHOn
inputType: type of input

InputHandler::Pointer getInputHandler()¶

Get the registered input Handler

Return

void registerIOEventHandler(const std::any &ioEventHandler)¶: Register a handler to be called for I/O events

void registerEndOfStreamEventHandler(const std::any &endOfStreamEventHandler)¶

Register a handler to be called for end of stream events. End of stream event are used to signify that a group of related data tokens is complete and that a new group of data token follow

Parameters

endOfStreamEventHandler:

virtual bool needsDeviceConnection() const¶

Return if this input needs to used in the context of a device

Return

virtual std::vector<karabo::util::Hash> getConnectedOutputChannels()¶

Get the output channels connected to this input

Return

virtual void connect(const karabo::util::Hash &outputChannelInfo)¶

Connect this input to an output channel as specified by its configuration.

Parameters

outputChannelInfo:

virtual void disconnect(const karabo::util::Hash &outputChannelInfo)¶

Disconnect the output channel specified by its configuration

Parameters

outputChannelInfo:

virtual bool canCompute() const¶

Should return true if the input can handle more data

Return

virtual void update()¶: Update the input to an receiving state

virtual bool respondsToEndOfStream()¶

Check if the input responds to end of stream events, e.g. by calling the registered handler.

Return

Protected Functions

void triggerIOEvent()¶: Trigger an I/O event in the event handler

void triggerEndOfStreamEvent()¶: Trigger an end of stream event in the event handler.

class AbstractOutput¶

Public Functions

AbstractOutput(const karabo::util::Hash &configuration)¶

If this object is constructed using the factory/configuration system this method is called

See

expectedParameters) and default-filled configuration

Parameters

input: Validated (

Public Static Functions

static KARABO_CONFIGURATION_BASE_CLASS void karabo::io::AbstractOutput::expectedParameters(karabo::util::Schema & expected)

Necessary method as part of the factory/configuration system

Parameters

expected: [out] Description of expected parameters for this object (Schema)

template <class T>

class BinaryFileInput¶

#include <BinaryFileInput.hh>

The binary file input specializes the Input class to read data from a binary file types T have been serialized to. The actual serialization format depends on the Serializer selected in this class’ configuration.

Inherits from karabo::io::Input< T >

Public Functions

void read(T &data, size_t idx = 0)¶

Read data from the input located at a given index

Parameters

data:
idx:

size_t size()¶

Total size (in terms of type T entries) of the input’s data soruce

Return

template <class T>

class BinaryFileOutput¶

#include <BinaryFileOutput.hh>

The binary file output specializes the Output class to write data of type T to a binary file. The actual serialization format depends on the Serializer selected in this class’ configuration.

Inherits from karabo::io::Output< T >

Public Functions

void write(const T &object)¶

Write an object to the output channel. Output channels may accept multiple writes before an update leads to processing of the written data.

Parameters

object:

Private Functions

void update()¶: Calling update tells that the output channel should cycle its state to be ready for new data written to it.

template <class T>

class BinarySerializer¶

Public Functions

virtual void save(const T &object, std::vector<char> &archive) = 0¶

Save an object to a binary archive

Parameters

object: to save
archive: to save to - some implementations clear() it before appending (e.g. in HashBinarySerializer), some do not (e.g. in SchemaBinarySerializer)

virtual void save2(const T &object, std::vector<char> &archive) = 0¶

Save an object by appending it to a binary archive

Parameters

object: to save
archive: to append to - no clear() called

virtual void save(const T &object, karabo::io::BufferSet &archive)¶

Save an object to the BufferSet

Parameters

object:
archive:

virtual size_t load(T &object, const char *archive, const size_t nBytes) = 0¶

Load an object from a binary archive.

Return

number of processed bytes in archive

Parameters

object: to load data into
archive: binary archive containing the data
nBytes: size in bytes of the data archive

size_t load(T &object, const std::vector<char> &archive)¶

Load an object from a binary archive.

Return

number of processed bytes in archive

Parameters

object: to load data into
archive: binary archive containing the data

virtual void load(T &object, const karabo::io::BufferSet &archive)¶

Load an object from BufferSet archive

Parameters

object:
archive: BufferSet object

void loadLastFromSequence(T &object, const char *archive, const std::size_t nBytes)¶

Loads the last object from a sequence of concatenated binary serialized objects of the same type. Sequences with only one object are also supported.

Parameters

object: to load the last instance into.
archive: sequence containing 1 or more objects of type T in binary serialized form.

void save(const std::shared_ptr<T> &object, std::vector<char> &archive)¶

Save an object to a binary archive

Parameters

object: to save
archive: to save to

size_t load(const std::shared_ptr<T> &object, const char *archive, const size_t nBytes)¶

Load an object from a binary archive.

Return

number of processed bytes in archive

Parameters

object: to load data into
archive: binary archive containing the data
nBytes: size in bytes of the data archive

size_t load(const std::shared_ptr<T> &object, const std::vector<char> &archive)¶

Load an object from a binary archive.

Return

number of processed bytes in archive

Parameters

object: to load data into
archive: binary archive containing the data

std::vector<char> save(const T &object)¶

Return the serialized binary representation of an object, i.e. save into an empty archive and return this

Return

Parameters

object:

T load(const char *archive, const size_t nBytes)¶

Load an object from a binary archive.

Parameters

archive: binary archive containing the data
nBytes: size in bytes of the data archive

T load(const std::vector<char> &archive)¶

Load an object from a binary archive.

Parameters

archive: binary archive containing the data

virtual void save(const std::vector<T> &objects, std::vector<char> &archive)¶

Save a vector of objects into a binary archive

Parameters

objects:
archive:

virtual size_t load(std::vector<T> &objects, const char *archive, const size_t nBytes)¶

Load a vector of objects from a binary archive.

Return

number of processed bytes in archive

Parameters

objects: to load data into
archive: binary archive containing the data
nBytes: size in bytes of the data archive

size_t load(std::vector<T> &objects, const std::vector<char> &archive)¶

Load a vector of objects from a binary archive.

Parameters

objects: to load data into
archive: binary archive containing the data

class BufferSet¶

Public Functions

BufferSet(bool copyAllData = false)¶

Construct a BufferSet

Parameters

copyAllDataset: to true if data should always be copied

void add()¶

Add empty buffer (COPY type) to the BufferSet.

No new buffer is added if the last buffer is still empty and of COPY type. Also makes internal information about size of last buffer (before adding a new one) consistent.

void add(std::size_t size, int type)¶

Add a buffer to the BufferSet

Parameters

size: - size of buffer
type: - BufferContents::COPY means buffer is COPY type BufferContents::NO_COPY_BYTEARRAY_CONTENTS means buffer where space allocated in char array (NO_COPY_BYTEARRAY_CONTENTS type)

void updateSize()¶: Update the size of the current buffer to reflect the size of the vector is refers to

BufferType &back() const¶: Return the last buffer in the BufferSet

BufferType &current() const¶

Return the current buffer in the BufferSet

Return

void rewind() const¶: Rewind the BufferSet to the first position

bool next() const¶

Advance to the next buffer in the BufferSet

Return: true if a next buffer exists, false otherwise

void emplaceBack(const karabo::util::ByteArray &array, bool writeSize = true)¶: Emplace a ByteArray at the back of the BufferSet

void emplaceBack(const std::shared_ptr<BufferType> &ptr)¶: Emplace a shared pointer to a vector at the end of the BufferSet

void appendTo(BufferSet &other, bool copy = true) const¶

Append the contents of this BufferSet to another BufferSet

Parameters

other: the BufferSet to append to
copy:

karabo::util::ByteArray currentAsByteArray() const¶

Return the current buffer as a ByteArray

Return

void clear()¶: Clear the BufferSet

size_t totalSize() const¶

Return the combined byte size of all buffers in the BufferSet.

Return

bool containsNonCopies() const¶: Will return true if any data in the BufferSet is a reference or a pointer to data not managed by the BufferSet.

template <typename BufferSequenceType>

void appendTo(BufferSequenceType &boost_buffers) const¶

Append the buffers of this BufferSet to, for instance, a vector of boost asio buffers, const or mutable

Parameters

boost_buffers: to a append to

bool currentIsByteArrayCopy() const¶

Returns true if the current buffer is a copy of a ByteArray

Return

std::vector<unsigned int> sizes() const¶

Return: Returns vector of sizes of this BufferSet

std::vector<int> types() const¶

Return: Returns vector of buffer types for this BufferSet

template <class InputType>

class CppInputHandler¶

#include <CppInputHandler.hh>

The CppInputHandler specializes the InputHandler class for Karabo’s C++ interface. The handlers used here are std::function objects.

Inherits from karabo::io::InputHandler

Public Functions

void registerIOEventHandler(const std::any &eventHandler)¶

Register an input handler for I/O events. The handler must be of a callable type.

Parameters

eventHandler:

void registerEndOfStreamEventHandler(const std::any &endOfStreamEventHandler)¶

Register an input handler for end of stream events. The handler must be of a callable type.

Parameters

endOfStreamEventHandler:

void triggerIOEvent()¶: Trigger an I/O event on the registered handler

void triggerEndOfStreamEvent()¶: Trigger an end of stream event on the registered handler

class HashBinarySerializer¶

#include <HashBinarySerializer.hh>

The HashBinarySerializer provides an implementation of BinarySerializer for the karabo::util::Hash.

While a karabo::util::Hash can in principle hold arbitrary data types, Hash serialization is limited to data types known to the karabo::util::Types type system. Hashes containing other data types will lead to exceptions during serialization.

Inherits from karabo::io::BinarySerializer< karabo::util::Hash >

Public Functions

void save(const karabo::util::Hash &object, std::vector<char> &buffer)¶

Save a Hash to a binary archive

Parameters

object: to save
archive: to save to - buffer.clear() will be called first

void save2(const karabo::util::Hash &object, std::vector<char> &buffer)¶

Save a Hash by appending it to a binary archive

Parameters

object: to save
archive: to append to - no clear() called

void save(const karabo::util::Hash &object, BufferSet &archive)¶

Save an object to the BufferSet

Parameters

object:
archive:

size_t load(karabo::util::Hash &object, const char *archive, const size_t nBytes)¶

Load an object from a binary archive.

Return

number of processed bytes in archive

Parameters

object: to load data into
archive: binary archive containing the data
nBytes: size in bytes of the data archive

void load(karabo::util::Hash &object, const BufferSet &archive)¶

Load an object from BufferSet archive

Parameters

object:
archive: BufferSet object

void save(const std::vector<karabo::util::Hash> &objects, std::vector<char> &archive)¶

Save a vector of objects into a binary archive

Parameters

objects:
archive:

size_t load(std::vector<karabo::util::Hash> &objects, const char *archive, const size_t nBytes)¶

Load a vector of objects from a binary archive.

Return

number of processed bytes in archive

Parameters

objects: to load data into
archive: binary archive containing the data
nBytes: size in bytes of the data archive

virtual ~HashBinarySerializer()¶: Destructor.

class HashXmlSerializer¶

#include <HashXmlSerializer.hh>

The HashXmlSerializer provides an implementation of TextSerializer for the karabo::util::Hash.

While a karabo::util::Hash can in principle hold arbitrary data types, Hash serialization is limited to data types known to the karabo::util::Types type system. Hashes containing other data types will lead to exceptions during serialization.

Inherits from karabo::io::TextSerializer< karabo::util::Hash >

Public Functions

void save(const karabo::util::Hash &object, std::string &archive)¶

Save an object into a text archive

Parameters

object: to save
archive: to save into

void load(karabo::util::Hash &object, const std::string &archive)¶

Load an object from a text archive

Parameters

object: to load data into
archive: to load the object from

void load(karabo::util::Hash &object, const char *archive)¶

Load an object from a text archive

Parameters

object: to load data into
archive: to load the object from

void save(const std::vector<karabo::util::Hash> &objects, std::string &archive)¶

Save a vector of objects into a text archive

Parameters

objects: to save
archive: to save into

void load(std::vector<karabo::util::Hash> &objects, const std::string &archive)¶

Save a vector of objects into a text archive

Parameters

objects: to save
archive: to save into

Private Functions

bool readStrConvertibleAttrs(karabo::util::Hash::Attributes &attrs, const pugi::xml_node &node) const¶

Reads all the hash attributes that are convertible from string from a given xml node.

Return

true if all the attributes in the xml node have been read; false if there is at least one attribute that is not convertible from string that should still be processed.

Parameters

attrs: the set of attrs that are convertible from string.
node: the xml node with the attributes to be read.

void extractNonStrConvertibleAttrs(std::vector<karabo::util::Hash> &nonStrAttrs, const pugi::xml_node &node) const¶

Extracts all the hash attributes that are non convertible from string from a given xml node.

Note

: currently there are two types of attributes that are not convertible from string: VECTOR_HASH and SCHEMA.

Parameters

node: the xml node with the attributes to be read.
nonStrAttrs: vector of hashes with each hash corresponding to a nonStringfiedAttr read from the xml node. Each hash in the vector has one node with the attribute name for its key and the attribute value for its value.

void addNonStrConvertibleAttrs(karabo::util::Hash &hash, const std::string &hashPath, std::vector<karabo::util::Hash> &attrs) const¶

Adds hash attributes non convertible from string to a given hash on a given path. The hash attributes are stored in a vector of hashes argument.

Parameters

hash: the hash that will have the attributes added to.
hashPath: the path in the hash where the attributes will be added.
attrs: the vector with the attributes to be added. Each attribute is an element of this vector and has a single key that corresponds to the attribute name and whose value is the attribute value. This value will be ‘moved away’ to the attributes to avoid copies.

struct CustomWriter¶: Inherits from xml_writer

template <class T>

class Input¶

#include <Input.hh>

The Input class provides a datatype T specific base for inputs in the Karabo system. The not type-specific methods are provided by the AbstractInput class.

Inherits from karabo::io::AbstractInput

Subclassed by karabo::io::BinaryFileInput< T >, karabo::io::TextFileInput< T >

Public Functions

virtual void read(T &data, size_t idx = 0) = 0¶

Read data from the input located at a given index

Parameters

data:
idx:

virtual size_t size() = 0¶

Total size (in terms of type T entries) of the input’s data soruce

Return

class InputElement¶

#include <InputElement.hh>

The InputElement provides acces to karabo::io::Input in terms of a Schema Element, defined in an expected parameter section.

Inherits from karabo::util::GenericElement< InputElement >

Public Functions

virtual InputElement &init()¶

The init method serves for setting up an access type property that allows the element to be included in initial schema.

Return: reference to the Element (to allow method’s chaining)

virtual InputElement &reconfigurable()¶

The reconfigurable method serves for setting up an access type property that allows the element to be included in initial, reconfiguration and monitoring schemas.

Return: reference to the Element (to allow method’s chaining)

class InputHandler¶

#include <InputHandler.hh>

The InputHandler class is the base class for registering and accessing I/O and end of stream input handlers.

Subclassed by karabo::io::CppInputHandler< InputType >

Public Functions

virtual void registerIOEventHandler(const std::any &eventHandler) = 0¶

Register an input handler for I/O events. The handler must be of a callable type.

Parameters

eventHandler:

virtual void registerEndOfStreamEventHandler(const std::any &endOfStreamEventHandler) = 0¶

Register an input handler for end of stream events. The handler must be of a callable type.

Parameters

endOfStreamEventHandler:

virtual void triggerIOEvent() = 0¶: Trigger an I/O event on the registered handler

virtual void triggerEndOfStreamEvent() = 0¶: Trigger an end of stream event on the registered handler

template <class T>

class Output¶

#include <Output.hh>

The Output class provides a base for outputs in the Karabo system.

Outputs act as sinks. Their specific implementation defines what is done with data written to them. They may e.g. pass it on a network or in-memory connection or persist it e.g. to a specific file using a specific format.

Subclassed by karabo::io::BinaryFileOutput< T >, karabo::io::TextFileOutput< T >

Public Functions

virtual void write(const T &object) = 0¶

Write an object to the output channel. Output channels may accept multiple writes before an update leads to processing of the written data.

Parameters

object:

virtual void update()¶: Calling update tells that the output channel should cycle its state to be ready for new data written to it.

class OutputElement¶

#include <OutputElement.hh>

The OutputElement provides acces to karabo::io::Output in terms of a Schema Element, defined in an expected parameter section.

Inherits from karabo::util::GenericElement< OutputElement >

Public Functions

virtual OutputElement &init()¶

The init method serves for setting up an access type property that allows the element to be included in initial schema.

Return: reference to the Element (to allow method’s chaining)

virtual OutputElement &reconfigurable()¶

The reconfigurable method serves for setting up an access type property that allows the element to be included in initial, reconfiguration and monitoring schemas.

Return: reference to the Element (to allow method’s chaining)

class SchemaBinarySerializer¶

#include <SchemaBinarySerializer.hh>

The SchemaBinarySerializer provides an implementation of BinarySerializer for the karabo::util::Schema.

Inherits from karabo::io::BinarySerializer< karabo::util::Schema >

Public Functions

void save(const karabo::util::Schema &object, std::vector<char> &archive)¶

Save a Schema by appending it to a binary archive

Parameters

object: to save
archive: to append to - no clear() called

void save2(const karabo::util::Schema &object, std::vector<char> &archive)¶

Save a Schema by appending it to a binary archive

Parameters

object: to save
archive: to append to - no clear() called

size_t load(karabo::util::Schema &object, const char *archive, const size_t nBytes)¶

Load an object from a binary archive.

Return

number of processed bytes in archive

Parameters

object: to load data into
archive: binary archive containing the data
nBytes: size in bytes of the data archive

class SchemaXmlSerializer¶

#include <SchemaXmlSerializer.hh>

The SchemaXmlSerializer provides an implementation of TextSerializer for the karabo::util::Hash.

Inherits from karabo::io::TextSerializer< karabo::util::Schema >

Public Functions

void save(const karabo::util::Schema &object, std::string &archive)¶

Save an object into a text archive

Parameters

object: to save
archive: to save into

void load(karabo::util::Schema &object, const std::string &archive)¶

Load an object from a text archive

Parameters

object: to load data into
archive: to load the object from

template <class T>

class TextFileInput¶

#include <TextFileInput.hh>

The text file input specializes the Input class to read data from a text file types T have been serialized to. The actual serialization format depends on the Serializer selected in this class’ configuration.

Inherits from karabo::io::Input< T >

Public Functions

void read(T &data, size_t idx = 0)¶

Read data from the input located at a given index

Parameters

data:
idx:

size_t size()¶

Total size (in terms of type T entries) of the input’s data soruce

Return

template <class T>

class TextFileOutput¶

#include <TextFileOutput.hh>

The text file output specializes the Output class to write data of type T to a text file. The actual serialization format depends on the Serializer selected in this class’ configuration.

Inherits from karabo::io::Output< T >

Public Functions

void write(const T &object)¶

Write an object to the output channel. Output channels may accept multiple writes before an update leads to processing of the written data.

Parameters

object:

Private Functions

void update()¶: Calling update tells that the output channel should cycle its state to be ready for new data written to it.

template <class T>

class TextSerializer¶

Public Functions

virtual KARABO_CONFIGURATION_BASE_CLASS void karabo::io::TextSerializer::save(const T & object, std::string & archive) = 0

Save an object into a text archive

Parameters

object: to save
archive: to save into

virtual void save(const std::vector<T> &objects, std::string &archive)¶

Save a vector of objects into a text archive

Parameters

objects: to save
archive: to save into

virtual void load(T &object, const std::string &archive) = 0¶

Load an object from a text archive

Parameters

object: to load data into
archive: to load the object from

virtual void load(T &object, const std::stringstream &archive)¶

Load an object from a text archive

Parameters

object: to load data into
archive: to load the object from

virtual void load(T &object, const char *archive)¶

Load an object from a text archive

Parameters

object: to load data into
archive: to load the object from

virtual void load(T &object, const char *archive, const size_t nBytes)¶

Load an object from a text archive

Parameters

object: to load data into
archive: to load the object from
nBytes: size of the archive

virtual void load(std::vector<T> &objects, const std::string &archive)¶

Save a vector of objects into a text archive

Parameters

objects: to save
archive: to save into

virtual void load(std::vector<T> &objects, const std::stringstream &archive)¶

Save a vector of objects into a text archive

Parameters

objects: to save
archive: to save into

virtual std::string save(const T &object)¶

Return the serialized text representation of an object, i.e. save into an empty archive and return this

Return

Parameters

object:

virtual T load(const std::string &archive)¶

Load an object from a text archive.

Parameters

archive: binary text containing the data

virtual T load(const char *archive)¶

Load an object from a text archive.

Parameters

archive: binary text containing the data

virtual T load(char *archive, const size_t nBytes)¶

Load an object from a text archive.

Parameters

archive: binary text containing the data
nBytes: size in bytes of the data archive

The karabo::net Namespace¶

namespace karabo::net¶

Namespace for package net

Typedefs

typedef boost::system::error_code ErrorCode¶

typedef std::function<void(const ErrorCode&)> ErrorHandler¶

using karabo::net::tcp = typedef boost::asio::ip::tcp

using karabo::net::errorCode = typedef boost::beast::error_code

using karabo::net::flatBuffer = typedef boost::beast::flat_buffer

using karabo::net::getRequest = typedef boost::beast::http::request<boost::beast::http::empty_body>

using karabo::net::HttpHeader = typedef boost::beast::http::field

using karabo::net::HttpHeaders = typedef boost::beast::http::fields

using karabo::net::HttpResponseHandler = typedef std::function<void(const boost::beast::http::response<boost::beast::http::string_body>&)>

using karabo::net::postRequest = typedef boost::beast::http::request<boost::beast::http::string_body>

using karabo::net::response = typedef boost::beast::http::response<boost::beast::http::string_body>

using karabo::net::resolver = typedef boost::asio::ip::tcp::resolver

using karabo::net::results_type = typedef boost::asio::ip::tcp::resolver::results_type

using karabo::net::tcp_stream = typedef boost::beast::tcp_stream

using karabo::net::ssl_stream = typedef boost::beast::ssl_stream<boost::beast::tcp_stream>

using karabo::net::ssl_context = typedef boost::asio::ssl::context

using karabo::net::verb = typedef boost::beast::http::verb

using karabo::net::InfluxResponseHandler = typedef std::function<void(const HttpResponse&)>

using karabo::net::InfluxConnectedHandler = typedef std::function<void(bool)>

typedef std::shared_ptr<std::vector<char>> VectorCharPointer¶

typedef std::shared_ptr<Channel> ChannelPointer¶

using karabo::net::AuthOneTimeTokenHandler = typedef std::function<void(const OneTimeTokenAuthorizeResult&)>

using karabo::net::AsyncHandler = typedef std::function<void(const boost::system::error_code)>

Enums

enum AmqpCppErrc¶

Values:

eCreateChannelError = 1000¶

eCreateExchangeError¶

eCreateQueueError¶

eBindQueueError¶

eCreateConsumerError¶

eUnbindQueueError¶

eDrop¶

eMessageDrop¶

enum AsyncStatus¶

Values:

PENDING = 0¶

FAILED = -1¶

DONE = 1¶

enum ConnectionStatus¶

Values:

DISCONNECTED = 0¶

CONNECTING¶

CONNECTED¶

DISCONNECTING¶

Functions

boost::system::error_code make_error_code(AmqpCppErrc e)¶

std::ostream &operator<<(std::ostream &os, const HttpResponse &o)¶

InfluxDbClient::Pointer buildInfluxReadClient()¶

Instantiates an InfluxDbClient that connects to an InfluxDb reading node.

The connection parameters for the InfluxDb reading node are obtained via the following environment variables:

KARABO_INFLUXDB_QUERY_URL KARABO_INFLUXDB_DBNAME (with fallback to the Broker domain) KARABO_INFLUXDB_QUERY_USER KARABO_INFLUXDB_QUERY_PASSWORD

Return: A std::shared_ptr to the built InfluxDbClient instance.

std::ostream &operator<<(std::ostream &os, const NetworkInterface &ni)¶: Send a string representation of the NetworkInterface object to a stream. (Mostly for debug purposes)

static karabo::util::Hash extendHeaderForBufferSets(const karabo::util::Hash &hdr, const std::vector<karabo::io::BufferSet::Pointer> &body)¶

Helper to extend header for writing header and BufferSet pointers.

Return: extended header

std::string bareHostName()¶

Return the bare host name after stripping domain (exflxxx12345.desy.de => exflxxx12345)

Return

void runProtected(std::shared_ptr<boost::asio::io_service> service, const std::string &category, const std::string &errorMessage, unsigned int delayInMilliSec = 100)¶

Wrapper around boost::asio::io_service::run that catches exceptions, logs them as errors and continues after some delay.

Parameters

service: shared pointer to the io_service
category: the category used for logging
errorMessage: will be part of the logged error
delayInMilliSec: is the delay after each catch

std::tuple<std::string, std::string> parseGenericUrl(const std::string &url)¶

Parses a URL and returns a tuple.

The URL must of format: <scheme>:<scheme-dependent-part>

Return

tuple containing scheme and scheme dependent part

Parameters

url: A well formed URL

std::tuple<std::string, std::string, std::string, std::string, std::string> parseUrl(const std::string &url)¶

Parses a HTTP-like URL and returns a tuple.

The URL must of format: <scheme>://<domain>:<port>/<path>?<query>

Return

tuple containing scheme, domain, port, path and query

Parameters

url: A well formed URL

string urlencode(const std::string &value)¶

std::string getIpFromCIDRNotation(const std::string &addressRange)¶

Returns an IP string from a Classless Inter-Domain Routing specification

e.g. the string 192.168.0.0/24 represents the IP range between 192.168.0.0 and 192.168.0.255.

The function will ignore loopback interface and interfaces that are down. Only IP4 specifications are implemented.

Return: an IP address matching the input range or the input string if the input string does not specify a network range or if it does not match any external active interface

Variables

const size_t kDefaultQueueCapacity = 5000¶

class AmqpBroker¶

Inherits from karabo::net::Broker

Public Functions

Broker::Pointer clone(const std::string &instanceId)¶

The function creates broker communication object with the new identity by cloning the parent object. Concrete meaning of cloning strategy is an implementation detail.

Return

new broker communication object

Parameters

instanceId: - unique ID

void connect()¶: This function establishes connection to the broker otherwise throws exception

void disconnect()¶: Close broker connection

bool isConnected() const¶

Predicate to check broker connection status

Return: true if connection is open

std::string getBrokerUrl() const¶

Get active URI used for establishing connection to broker

Return: uri like “mqtt://localhost:1883”

std::string getBrokerType() const¶

Get type string identifying broker. Example: “AmqpBroker”

Return: the type defined by active uri

boost::system::error_code subscribeToRemoteSignal(const std::string &signalInstanceId, const std::string &signalFunction)¶

Establish logical signal-slot connection between 2 devices that is required by used protocol for registration

Parameters

signalInstanceId: device instance ID of a signal
signalFunction: signal name

boost::system::error_code unsubscribeFromRemoteSignal(const std::string &signalInstanceId, const std::string &signalFunction)¶

Close logical signal-slot connection. De-registration in broker specific API.

Parameters

signalInstanceId:
signalFunction:

void subscribeToRemoteSignalAsync(const std::string &signalInstanceId, const std::string &signalFunction, const AsyncHandler &completionHandler)¶

Establish signal-slot connection asynchronously

Parameters

signalInstanceId:
signalFunction:
completionHandler: this callback is called when complete

void unsubscribeFromRemoteSignalAsync(const std::string &signalInstanceId, const std::string &signalFunction, const AsyncHandler &completionHandler)¶

Unsubscribe from (remote) signal asynchronously

Parameters

signalInstanceId:
signalFunction:
completionHandler:

void startReading(const consumer::MessageHandler &handler, const consumer::ErrorNotifier &errorNotifier = consumer::ErrorNotifier())¶

AMQP subscription: subscribe to the following exchanges… “m_domain.slots” with routingKey m_instanceId “m_domain.global_slots”

Parameters

handler: - success handler
errorNotifier: - error handler

void stopReading()¶: Stop processing messages coming via main path

void startReadingHeartbeats(const consumer::MessageHandler &handler, const consumer::ErrorNotifier &errorNotifier = consumer::ErrorNotifier())¶

Heartbeat is used for tracking instances (tracking all instances or no tracking at all)

AMQP subscription Subscribe to the exchange “m_domain.signals” with the routing key: “*.signalHeartbeat” heartbeats of all known connections

Parameters

handler: - success handler
errorNotifier: - error handler

void write(const std::string &topic, const karabo::util::Hash::Pointer &header, const karabo::util::Hash::Pointer &body, const int = 4, const int = 0)¶

Write message to broker, blocks until written

Parameters

topic: Either the “domain” as passed to the Broker base class, the “domain” with the suffix “_beats”, or “karaboGuiDebug”
header: of the message - must contain
body: of the message
priority: unused (needed by JmsBroker)
timeToLive: unused (needed by JmsBroker)

Public Static Functions

void expectedParameters(karabo::util::Schema &s)¶

AmqpBroker operates currently with the following set of …

Signals are sent to the exchange …

exchange = <domain>.signals routing_key = <signalInstanceId>.<signalName> < selector queue = <m_instanceId> < common queue

the signals are emitted to the exchange bound via routing_key to the queue. The slotInstanceIds should subscribe to the AMQP::topic type exchange with the ‘routing_key’ and queue = <slotInstanceId>

Special case of above signals… signalHeartbeat … exchange = <domain>.signals routing_key = <signalInstanceId>.signalHeartbeat queue = <m_instanceId>

Calls, commands, requests, replies are sent to

exchange = <domain>.slots routing_key = <slotInstanceId> queue = <m_instanceId> < common queue

all requests/calls/replies to the device send to this exchange The further message dispatching to slots is provided by using info in message header.

Broadcast messages should be sent to …

exchange = <domain>.global_slots routing_key = “” queue = <m_instanceId>

there is a way of implementing “broadcast” messages like in JmsBroker. In JMS it was enough to use “|*|” in header’s slotInstanceIds. In AMQP we have to be subscribed to such exchange (to receive broadcast messages). Known global slots: slotInstanceNew to announce the new device in Karabo network slotInstanceUpdated to announce the device info to be updated slotInstanceGone to announce device death, slotPing to trigger sending their status by all devices received such message

GUI debug

exchange = <domain>.karaboGuiDebug routing_key = “” queue = <as gui=”” debug=”” listener=”” defines>=”“>

GUI debugging channel

void defaultQueueArgs(AMQP::Table &args)¶: Fill argument with default AMQP message queue creation arguments

class AmqpClient¶

#include <AmqpClient.hh>

Class that exposes an AMQP client.

It will create a unique queue and consume from it exclusively and with automatic acknowledgment. Its queue name will start with the given instanceId and will potentially be suffixed by some characters to ensure uniqueness.

To actually receive messages via the handlers specified in the constructor, the client has to subscribe to exchanges, potentially with routing keys to select messages on the broker side.

Note: : This client does not know about Karabo “domains” (a.k.a. “topics”), i.e. exchanges and queues created are “shared” among all clients connected to the same broker.

Inherits from std::enable_shared_from_this< AmqpClient >

Public Types

enum ChannelStatus¶

Channel status tells what should be the next step to do in channel preparation

Values:

REQUEST¶

CREATE¶

CREATE_QUEUE¶

CREATE_CONSUMER¶

READY¶

enum ExchangeStatus¶

Exchange status tells about the status of a known exchange

Values:

DECLARING¶

READY

enum SubscriptionStatus¶

Subscription status tells in which status a registered subscription currently is

Values:

PENDING

CHECK_EXCHANGE¶

DECLARE_EXCHANGE¶

BIND_QUEUE¶

READY

UNBIND_QUEUE¶

Public Functions

AmqpClient(AmqpConnection::Pointer connection, std::string instanceId, AMQP::Table queueArgs, ReadHandler readHandler)¶

Create client with raw data interface from connection

Parameters

connection: the connection, all internal data access will run in its io context
instanceId: the client id - will usually be the name of the queue that will be subscribed
queueArgs: the arguments passed to queue creation
readHandler: a read handler for all received messages (if an invalid function, must call setReadHandler before the first subscription)

void setReadHandler(ReadHandler readHandler)¶

(Re-)set the read handler that will be called for all received messages

Parameters

readHandler: A valid read function (karabo::util::ParameterException if not valid)

void asyncSubscribe(const std::string &exchange, const std::string &routingKey, AsyncHandler onSubscriptionDone)¶

Asynchronously subscribes client

If subscription is reported to have failed, it will be tried again

at next subscription or
if reviveIfReconnected() is called.

Parameters

exchange: name of AMQP exchange that will be created if not yet existing
routingKey: the AMQP routing key
onSubscriptionDone: a valid handler called in AMQP io context (so please no mutex inside, please) when subscription established or failed

void asyncUnsubscribe(const std::string &exchange, const std::string &routingKey, AsyncHandler onUnsubscriptionDone)¶

Asynchronously unsubscribes client

Note: Success will be reported for an unsubscription from exchange/routing key that it was not subscribed before

Parameters

exchange: name of AMQP exchange that will be unsubscribed from
routingKey: the AMQP routing key to unsubscribe from
onUnsubscriptionDone: a valid handler called in AMQP io context (so please no mutex inside, please) when unsubscription succeeded or failed

void asyncUnsubscribeAll(AsyncHandler onUnsubscriptionsDone)¶

Asynchronously unsubscribes client from all subscriptions

Parameters

onUnsubscriptionDone: a valid handler called in AMQP io context (so please no mutex inside, please) when all unsubscription requests are done. If any of them failed, the error code passed is the one of the last failure

void asyncPublish(const std::string &exchange, const std::string &routingKey, const std::shared_ptr<std::vector<char>> &data, AsyncHandler onPublishDone)¶

Asynchronously publish data

Parameters

exchange: the exchange…
routingKey: …and the routingkey for the data
data: a raw data container fo the message to be published (must be non-zero pointer)
onPublishDone: handler called in AMQP io context (so please no mutex inside, please) when data published

void reviveIfReconnected()¶

Revice after connection was lost and re-established

Means to recreate channel, redo all subscriptions and publish postponed messages

To be called if AmqpConnection is connected again after connection loss Must be called within io context of AmqpConnection

Private Functions

void asyncPrepareChannel(AsyncHandler onChannelPrepared)¶

Prepare m_channel until it is ChannelStatus::READY

Must be called in the io context of the AmqpConnection

Parameters

onChannelPrepared: handler called when m_channel READY or if failure on the way

void moveChannelState()¶: Helper to move the created channel through its states, asynchronously calling itself. If READY (or failure), call and erase the m_channelPreparationCallback

void doPublish(const std::string &exchange, const std::string &routingKey, const std::shared_ptr<std::vector<char>> &data, const AsyncHandler &onPublishDone)¶: Helper to publish, must run in io context and only when channel is READY and exchange declared

void queueMessage(PostponedMessage &&message)¶: Queue message (or drop if queueu too long), must run in io context

void publishPostponed()¶: Helper to publish postponed messages until first found with an exchange that is not yet declared

Private Members

std::queue<PostponedMessage> m_postponedPubMessages¶: Messages postponed since channel not yet ready or exchange not yet declared.

class AmqpConnection¶

#include <AmqpConnection.hh>

Wraps the AMQP::TcpConnection and the single threaded io context where all calls to the amqp library must run.

AmqpConnection

Inherits from std::enable_shared_from_this< AmqpConnection >

Public Types

enum State¶

Connection states

Values:

eUnknown = 2000¶

eStarted¶

eNotConnected¶

eConnectionDone¶

eConnectionReady¶

eConnectionClosed¶

eConnectionError¶

eConnectionLost¶

using ChannelCreationHandler = std::function<void(const std::shared_ptr<AMQP::Channel>&, const std::string &errMsg)>¶

Handler for asyncCreateChannel

Either returns the channel or (if returned channel pointer is empty) state the failure reason.

Public Functions

AmqpConnection(std::vector<std::string> urls)¶

Constructing a connection and starting the thread of the io context

Parameters

urls: vector of broker urls to try to connect to in asyncConnect (throws karabo::util::NetworkException if vector is empty)

std::string getCurrentUrl() const¶: Return currently used broker URL (either already connected to it or the currently/next tried one)

bool isConnected() const¶: Whether connection established

std::string connectionInfo() const¶: Various info about internal connection (for debug logs)

void asyncConnect(AsyncHandler onComplete)¶

Asynchronously connect to any of the broker addresses passed to the constructor.

Addresses will be tried in the order they have been passed. Can be called from any thread.

Parameters

onComplete: AsyncHAndler called (not from within asyncConnect) about success or failure of connection attempt. If all addresses failed, the error code passed is the one of the last address passed to the constructor. The handler (if valid) will be called from within the internal io context, but not within the scope of asyncConnect.

void asyncCreateChannel(ChannelCreationHandler onComplete)¶

Trigger creation of an amqp channel and return it via the handler.

If not connected yet, try to connect first. Note that if connection lost, channel creation will not be tried again, but failure is reported.

Can be called from any thread.

Parameters

onComplete: A valid (!) ChannelCreationHandler that will be called from within the internal io context, but not within the scope of asyncCreateChannel.

void registerForReconnectInfo(std::weak_ptr<AmqpClient> client)¶: Register client to be informed about re-established connection after connection loss

void cleanReconnectRegistrations()¶

Clean clients registered to receive reconnect info, i.e. remove all dangling weak pointers

Can e.g. be called in the destructor of a client that registered before.

template <typename CompletionToken>

void post(CompletionToken &&task) const¶

Post a task to the io context

The task must not contain blocking code since otherwise the thread running the AMQP communication is blocked.

template <typename CompletionToken>

void dispatch(CompletionToken &&task) const¶

Detach a task to the io context, i.e. run it now or later depending on which thread we are in

The task must not contain blocking code since otherwise the thread running the AMQP communication is blocked.

Private Functions

void doAsyncConnect()¶

Helper to asyncConnect iterating over urls until success or all urls tried. Then calls m_onConnectionComplete.

Prerequisite: m_urlIndex < m_urls.size()

void informReconnection(const boost::system::error_code &ec)¶: Must run in io context

void triggerReconnection()¶: Must run in io context

const char *stateString(AmqpConnection::State state)¶: Convert State to a string (or rather const char*)

Private Members

std::set<std::weak_ptr<AmqpClient>, std::owner_less<std::weak_ptr<AmqpClient>>> m_registeredClients¶: Track clients to inform about reconnections.

class AmqpHashClient¶

#include <AmqpHashClient.hh>

Class that wraps around AmqpClient to provide a message interface with Hash header and body.

Deserialisation of incoming messages is done via a karabo::net::Strand, i.e. a running karabo::net::EventLoop is needed.

Inherits from std::enable_shared_from_this< AmqpHashClient >

Public Functions

void asyncSubscribe(const std::string &exchange, const std::string &routingKey, AsyncHandler onSubscriptionDone)¶

Asynchronously subscribes client by just forwarding to AmqpClient::asyncSubscribe

==> See docs of that.

void asyncUnsubscribe(const std::string &exchange, const std::string &routingKey, AsyncHandler onUnsubscriptionDone)¶

Asynchronously unsubscribes client by just forwarding to AmqpClient::asyncUnsubscribe

==> See docs of that.

void asyncUnsubscribeAll(AsyncHandler onUnsubscriptionDone)¶

Asynchronously unsubscribes client from all subscriptions by just forwarding to AmqpClient::asyncUnsubscribeAll

==> See docs of that.

void asyncPublish(const std::string &exchange, const std::string &routingKey, const util::Hash::Pointer &header, const util::Hash::Pointer &body, AsyncHandler onPublishDone)¶

Asynchronously publish data from header and body

Hashes are serialised such that AmqpClient::asyncPublish can be use internally. ==> See docs of that.

Public Static Functions

AmqpHashClient::Pointer create(AmqpConnection::Pointer connection, std::string instanceId, AMQP::Table queueArgs, HashReadHandler readHandler, ErrorReadHandler errorReadHandler)¶

Create client with message interface based on two Hashes (header and body).

Parameters

connection: the connection, all internal data access will run in its io context
instanceId: the client id - will usually be the name of the queue that will be subscribed
queueArgs: the arguments passed to queue creation
readHandler: a valid read handler for all received messages
errorReadHandler: a valid handler called when a received message could not be processed, e.g. due to serialisation problems

Private Functions

AmqpHashClient(AmqpConnection::Pointer connection, std::string instanceId, AMQP::Table queueArgs, HashReadHandler readHandler, ErrorReadHandler errorReadHandler)¶: Internal constructor, use static create instead: raw clients read handler has to be set after construction

void onRead(const std::shared_ptr<std::vector<char>> &data, const std::string &exchange, const std::string &routingKey)¶

Handler passed to raw client (i.e. runs in io context of connection).

Post arguments for deserialzation on the respective strand that runs in Karabo event loop

void deserialize(const std::shared_ptr<std::vector<char>> &data, const std::string &exchange, const std::string &routingKey)¶: Deserializes ‘data’ input into Hash for header and body, adds exchange and key to the header and calls handler passed to constructor

class Broker¶

Inherits from std::enable_shared_from_this< Broker >

Subclassed by karabo::net::AmqpBroker

Public Functions

virtual Broker::Pointer clone(const std::string &instanceId) = 0¶

The function creates broker communication object with the new identity by cloning the parent object. Concrete meaning of cloning strategy is an implementation detail.

Return

new broker communication object

Parameters

instanceId: - unique ID

virtual void connect() = 0¶: This function establishes connection to the broker otherwise throws exception

virtual void disconnect() = 0¶: Close broker connection

virtual bool isConnected() const = 0¶

Predicate to check broker connection status

Return: true if connection is open

virtual std::string getBrokerUrl() const = 0¶

Get active URI used for establishing connection to broker

Return: uri like “mqtt://localhost:1883”

virtual std::string getBrokerType() const = 0¶

Get type string identifying broker. Example: “AmqpBroker”

Return: the type defined by active uri

const std::string &getInstanceId() const¶

Get current instance ID associated with this broker object

Return: instanceId

const std::string &getDomain() const¶

Get the domain this broker is communicating to

Return: domain

void setConsumeBroadcasts(bool consumeBroadcasts)¶

Set flag defining the way how to handle broadcast messages. It influences on subscription to such messages, i.e. has to be called before startReading(..)

Parameters

consumeBroadcasts: true means subscription

virtual boost::system::error_code subscribeToRemoteSignal(const std::string &signalInstanceId, const std::string &signalFunction) = 0¶

Establish logical signal-slot connection between 2 devices that is required by used protocol for registration

Parameters

signalInstanceId: device instance ID of a signal
signalFunction: signal name

virtual boost::system::error_code unsubscribeFromRemoteSignal(const std::string &signalInstanceId, const std::string &signalFunction) = 0¶

Close logical signal-slot connection. De-registration in broker specific API.

Parameters

signalInstanceId:
signalFunction:

virtual void subscribeToRemoteSignalAsync(const std::string &signalInstanceId, const std::string &signalFunction, const AsyncHandler &completionHandler) = 0¶

Establish signal-slot connection asynchronously

Parameters

signalInstanceId:
signalFunction:
completionHandler: this callback is called when complete

virtual void unsubscribeFromRemoteSignalAsync(const std::string &signalInstanceId, const std::string &signalFunction, const AsyncHandler &completionHandler) = 0¶

Unsubscribe from (remote) signal asynchronously

Parameters

signalInstanceId:
signalFunction:
completionHandler:

virtual void startReading(const consumer::MessageHandler &handler, const consumer::ErrorNotifier &errorNotifier = consumer::ErrorNotifier()) = 0¶

Set up handlers for processing messages arriving via main communication path

Parameters

handler: - read handler
errorNotifier: - error handler

virtual void stopReading() = 0¶: Stop processing messages coming via main path

virtual void startReadingHeartbeats(const consumer::MessageHandler &handler, const consumer::ErrorNotifier &errorNotifier) = 0¶

Set up handlers for processing heartbeat messages arriving via special path.

Heartbeat is used for tracking instances (tracking all instances or no tracking at all)

Parameters

handler: - read message handler
errorNotifier: - error handler

virtual void write(const std::string &topic, const karabo::util::Hash::Pointer &header, const karabo::util::Hash::Pointer &body, const int priority, const int timeToLive) = 0¶

Send message to broker

Parameters

topic:
header:
body:
priority:
timeToLive:

Public Static Functions

std::vector<std::string> brokersFromEnv()¶: Specifies the string of broker URLs from the environment variable KARABO_BROKER. If KARABO_BROKER is not defined, uses a hard coded fallback.

std::string brokerTypeFromEnv()¶: Specifies the broker type as the protocol of the broker URLs defined by brokersFromEnv(). Throws LogicException if broker addresses specified with different types or without protocol.

std::string brokerTypeFrom(const std::vector<std::string> &urls)¶: Specifies the broker type as the protocol of the given broker URLs. Throws LogicException if broker addresses specified with different types or without protocol.

std::string brokerDomainFromEnv()¶

Specify broker domain (i.e. topic for JmsBroker) from environment variables.

First source is KARABO_BROKER_TOPIC, as a fall back the environment variables LOGNAME, USER, LNAME and USERNAME are checked in that order.

class Channel¶

#include <Channel.hh>

Represents a communication channel used for p2p messaging on a connection to a remote instance. This is only an interface, see TcpChannel for a concrete implementation using the tcp protocol.

Inherits from std::enable_shared_from_this< Channel >

Subclassed by karabo::net::TcpChannel

Public Functions

virtual Connection::Pointer getConnection() const = 0¶

Return a pointer to the connection this channels belongs to

Return

virtual size_t readSizeInBytes()¶

Synchronously reads the message’s size. Will block until a message arrives on the socket.

Return: Size in bytes of incoming TCP message

virtual std::string consumeBytesAfterReadUntil(const size_t nBytes)¶

Synchronously reads size bytes and return them as a string. The reading will block until the bytes are read.

Note

reads up nBytes expecting no header. To be used ONLY after a readAsyncStringUntil operation in case some bytes must be read after readAsyncStringUntil has been used.

Parameters

size: This number of bytes will be copied into data

virtual void read(char *data, const size_t &size)¶

Synchronously reads size bytes into data. The reading will block until the data record is read.

Parameters

data: Pre-allocated contiguous block of memory
size: This number of bytes will be copied into data

virtual void read(std::vector<char> &data)¶

This function reads into a vector of chars The reading will block until the data record is read.

Parameters

data: A vector which will be updated accordingly

virtual void read(std::string &data)¶

This function reads into a string The reading will block until the data record is read. CAVEAT: As string is not guaranteed to be represented by a contiguous block of memory this function will always introduce a copy under the hood.

Parameters

data: A string which will be updated accordingly

virtual void read(karabo::util::Hash &data)¶

This function reads into a hash. The reading will block until the data record is read. The reading will block until the data record is read.

Parameters

data: Hash object which will be updated

virtual void read(karabo::util::Hash &header, char *data, const size_t &size)¶

Synchronously reads size bytes from socket into data and provides a header. The reading will block until the data record is read.

Parameters

header: Hash object which will be updated to contain header information
data: Pre-allocated contiguous block of memory
size: This number of bytes will be copied into data

virtual void read(karabo::util::Hash &header, std::vector<char> &data)¶

This function reads into a header and a vector of chars. The reading will block until the data record is read.

Parameters

header: Hash object which will be updated to contain header information
data: A vector which will be updated accordingly

virtual void read(karabo::util::Hash &header, std::string &data)¶

This function reads into header and a string The reading will block until the data record is read. CAVEAT: As string is not guaranteed to be represented by a contiguous block of memory this function will always introduce a copy under the hood.

Parameters

data: A string which will be updated accordingly

virtual void read(karabo::util::Hash &header, karabo::util::Hash &data)¶

This function reads into a header hash and a data hash. The reading will block until the data record is read. The reading will block until the data record is read.

Parameters

header: Hash object which will be updated to contain header information
data: Hash object which will be updated to contain data information

virtual void readAsyncSizeInBytes(const ReadSizeInBytesHandler &handler)¶

In case a message arrived, handler will be called back The handler will inform about the number of bytes going to come in

Parameters

handler: Call-back function of signature: void (Channel::Pointer, const size_t&)

virtual void readAsyncRaw(char *data, const size_t &size, const ReadRawHandler &handler)¶

Asynchronously reads size number of bytes into pre-allocated data buffer A handler can be registered to inform about completion of writing NOTE: This function only makes sense calling after having used “readAsyncSizeInBytes”, which gives a chance to correctly pre-allocated memory in user-space.

Parameters

data: Pre-allocated contiguous block of memory
size: This number of bytes will be copied into data
handler: Call-back function of signature: void (Channel::Pointer)

virtual void readAsyncStringUntil(const std::string &terminator, const ReadStringHandler &handler)¶

Read a string until terminator string is found. (No header is expected).

Parameters

terminator: when this string found, read is done
handler: handler with signature ReadStringHandler, i.e. void (const boost::system::error_code&, std::string&) is called. second handler parameter is the read string with terminator stripped away

virtual void readAsyncVector(const ReadVectorHandler &handler)¶

Asynchronously reads data into a vector<char>. All memory management is done by the API.

Parameters

handler: Call-function of signature: void (Channel::Pointer, const std::vector<char>&)

virtual void readAsyncString(const ReadStringHandler &handler)¶

Asynchronously reads data into a string. All memory management is done by the API. NOTE: A string in general is not storing data contiguously. Thus, an additional copy under the hood is needed which makes this interface slightly slower.

Parameters

handler: Call-function of signature: void (Channel::Pointer, const std::string&)

virtual void readAsyncHash(const ReadHashHandler &handler)¶

Asynchronously reads data into a hash. All memory management is done by the API.

Parameters

handler: Call-function of signature: void (Channel::Pointer, const karabo::util::Hash&)

virtual void readAsyncHashPointer(const ReadHashPointerHandler &handler)¶

Asynchronously reads data into a hash. All memory management is done by the API.

Parameters

handler: Call-function of signature: void (Channel::Pointer, const karabo::util::Hash&)

virtual void readAsyncVectorPointer(const ReadVectorPointerHandler &handler)¶

Asynchronously reads data into a vector<char>. All memory management is done by the API.

Parameters

handler: Call-function of signature: void (Channel::Pointer, const std::vector<char>&)

virtual void readAsyncHashVector(const ReadHashVectorHandler &handler)¶

Asynchronously reads data into a hash header and a vector<char>. All memory management is done by the API.

Parameters

handler: Call-function of signature: void (Channel::Pointer, const karabo::util::Hash&, const std::vector<char>&)

virtual void readAsyncHashString(const ReadHashStringHandler &handler)¶

Asynchronously reads data into a hash header and a string. All memory management is done by the API. NOTE: A string in general is not storing data contiguously. Thus, an additional copy under the hood is needed which makes this interface slightly slower.

Parameters

handler: Call-function of signature: void (Channel::Pointer, const karabo::util::Hash&, const std::string&)

virtual void readAsyncHashHash(const ReadHashHashHandler &handler)¶

Asynchronously reads data into a hash header and a hash body. All memory management is done by the API.

Parameters

handler: Call-function of signature: void (const ErrorCode&, const karabo::util::Hash&, const karabo::util::Hash&)

virtual void readAsyncHashPointerHashPointer(const ReadHashPointerHashPointerHandler &handler)¶

Asynchronously reads data into a hash header and a hash body. All memory management is done by the API.

Parameters

handler: Call-function of signature: void (const ErrorCode&, const karabo::util::Hash&, const karabo::util::Hash&)

virtual void readAsyncHashVectorPointer(const ReadHashVectorPointerHandler &handler)¶

Asynchronously reads data into a hash header and a vector<char>. All memory management is done by the API.

Parameters

handler: Call-function of signature: void (const ErrorCode&, const karabo::util::Hash&, const std::vector<char>&)

virtual void readAsyncHashVectorBufferSetPointer(const ReadHashVectorBufferSetPointerHandler &handler)¶

Asynchronously reads data into a hash header and into a vector of BufferSet pointers. All memory management is done by the API.

Parameters

handler: Call-function of signature: void (const ErrorCode&, const karabo::util::Hash&, const std::vector<karabo::io::BufferSet::Pointer>&)

virtual void write(const char *data, const size_t &size)¶

Synchronous write. The function blocks until all bytes are written.

Parameters

data: Pointer to a contiguous block of memory that should be written
size: This number of bytes will be written

virtual void write(const std::vector<char> &data)¶

Synchronous write. The function blocks until all bytes are written.

Parameters

data: vector of chars containing the data to be written

virtual void write(const std::string &data)¶

Synchronous write. The function blocks until all bytes are written.

Parameters

data: string, where each character represents on byte of data to be written

virtual void write(const karabo::util::Hash &data)¶

Synchronous write. The function blocks until all bytes are written.

Parameters

data: is contained in a Hash with no particular structure, but serializable, i.e. containing no non-karabo data types or Hash derived types

virtual void write(const karabo::util::Hash &header, const char *data, const size_t &size)¶

Synchronous write. The function blocks until all bytes are written.

Parameters

header: containing metadata for the data being written
data: Pointer to a contiguous block of memory that should be written
size: This number of bytes will be written

virtual void write(const karabo::util::Hash &header, const std::vector<char> &data)¶

Synchronous write. The function blocks until all bytes are written.

Parameters

header: containing metadata for the data being written
data: vector of chars containing the data to be written

virtual void write(const karabo::util::Hash &header, const std::vector<karabo::io::BufferSet::Pointer> &body)¶

Synchronous write. The function blocks until all bytes are written.

Parameters

header: containing metadata for the data being written and BufferSet’s layout
body: vector of BufferSet pointers

virtual void write(const karabo::util::Hash &header, std::shared_ptr<const std::vector<char>> &data)¶

Synchronous write. The function blocks until all bytes are written.

Parameters

header: containing metadata for the data being written
data: vector of chars containing the data to be written, passed as a shared pointer

virtual void write(const karabo::util::Hash &header, const std::string &data)¶

Synchronous write. The function blocks until all bytes are written.

Parameters

header: containing metadata for the data being written
data: string, where each character represents on byte of data to be written

virtual void write(const karabo::util::Hash &header, const karabo::util::Hash &body)¶

Synchronous write. The function blocks until all bytes are written.

Parameters

header: containing metadata for the data being written
data: is contained in a Hash with no particular structure, but serializable, i.e. containing no non-karabo data types or Hash derived types

virtual void writeAsyncRaw(const char *data, const size_t &size, const WriteCompleteHandler &handler)¶

Write data asynchronously, i.e. do not block upon call. Upon write completion a handler function is called

Parameters

data: Pointer to a contiguous block of memory that should be written
size: This number of bytes will be written
handler: to be called upon write completion handler. Needs to be a function wrapped into a std::function which takes const boost::system::error_code& as its only argument.

virtual void writeAsyncVector(const std::vector<char> &data, const WriteCompleteHandler &handler)¶

Write data asynchronously, i.e. do not block upon call. Upon write completion a handler function is called

Parameters

data: vector of chars containing the data to be written
handler: to be called upon write completion handler. Needs to be a function wrapped into a std::function which takes const boost::system::error_code& as its only argument.

virtual void writeAsyncVectorPointer(const std::shared_ptr<std::vector<char>> &data, const WriteCompleteHandler &handler)¶

Write data asynchronously, i.e. do not block upon call. Upon write completion a handler function is called

Parameters

data: vector of chars containing the data to be written, passed as a shared pointer
handler: to be called upon write completion handler. Needs to be a function wrapped into a std::function which takes const boost::system::error_code& as its only argument.

virtual void writeAsyncHash(const karabo::util::Hash &data, const WriteCompleteHandler &handler)¶

Write data asynchronously, i.e. do not block upon call. Upon write completion a handler function is called

Parameters

data: is contained in a Hash with no particular structure, but serializable, i.e. containing no non-karabo data types or Hash derived types
handler: to be called upon write completion handler. Needs to be a function wrapped into a std::function which takes const boost::system::error_code& as its only argument.

virtual void writeAsyncHashRaw(const karabo::util::Hash &header, const char *data, const size_t &size, const WriteCompleteHandler &handler)¶

Write data asynchronously, i.e. do not block upon call. Upon write completion a handler function is called

Parameters

header: containing metadata for the data being written
data: Pointer to a contiguous block of memory that should be written
size: This number of bytes will be written
handler: to be called upon write completion handler. Needs to be a function wrapped into a std::function which takes const boost::system::error_code& as its only argument.

virtual void writeAsyncHashVector(const karabo::util::Hash &header, const std::vector<char> &data, const WriteCompleteHandler &handler)¶

Write data asynchronously, i.e. do not block upon call. Upon write completion a handler function is called

Parameters

header: containing metadata for the data being written
data: vector of chars containing the data to be written
handler: to be called upon write completion. Needs to be a function wrapped into a std::function which takes const boost::system::error_code& as its only argument.

virtual void writeAsyncHashVectorPointer(const karabo::util::Hash &header, const std::shared_ptr<std::vector<char>> &data, const WriteCompleteHandler &handler)¶

Write data asynchronously, i.e. do not block upon call. Upon write completion a handler function is called

Parameters

header: containing metadata for the data being written
data: vector of chars containing the data to be written, passed as a shared pointer
handler: to be called upon write completion handler. Needs to be a function wrapped into a std::function which takes const boost::system::error_code& as its only argument.

virtual void writeAsyncHashHash(const karabo::util::Hash &header, const karabo::util::Hash &data, const WriteCompleteHandler &handler)¶

Write data asynchronously, i.e. do not block upon call. Upon write completion a handler function is called

Parameters

header: containing metadata for the data being written
body: data contained in a Hash with no particular structure, but serializable, i.e. containing no non-karabo data types or Hash derived types
handler: to be called upon write completion. Needs to be a function wrapped into a std::function which takes const boost::system::error_code& as its only argument.

virtual void writeAsyncHashVectorBufferSetPointer(const karabo::util::Hash &header, const std::vector<karabo::io::BufferSet::Pointer> &body, const WriteCompleteHandler &handler)¶

Write header and vector<BufferSet::Pointer> asynchronously.

Upon write completion a handler function is called. Data inside the buffers must not be changed or deleted before this handler is called. Special care is needed if any Hash that had been serialised into the buffers contained an NDArray: The raw data of the array will be shared between the BufferSet and the Hash. Deletion of the Hash is safe, though.

Parameters

header: containing metadata for the data being written
body: data as a vector of BufferSet::Pointer
handler: to be called upon write completion. Needs to be a function wrapped into a std::function which takes const boost::system::error_code& as its only argument.

virtual size_t dataQuantityRead()¶: Returns the number of bytes read since the last call of this method

virtual size_t dataQuantityWritten()¶: Returns the number of bytes written since the last call of this method

virtual void setTimeoutSyncRead(int milliseconds)¶

Set a timeout in when synchronous reads timeout if the haven’t been handled

Parameters

milliseconds:

virtual void close() = 0¶: Close this channel

virtual bool isOpen() = 0¶

Check if this channel is open

Return

virtual void writeAsync(const char *data, const size_t &size, int prio = 4)¶

Write data asynchronously, i.e. do not block upon call. Fire and forget, no callback called upon completion

Parameters

data: Pointer to a contiguous block of memory that should be written
size: This number of bytes will be written
prio: the priority of this write operation

virtual void writeAsync(const std::vector<char> &data, int prio = 4)¶

Write data asynchronously, i.e. do not block upon call. Fire and forget, no callback called upon completion

Parameters

data: vector of chars containing the data to be written
prio: the priority of this write operation

virtual void writeAsync(const std::shared_ptr<std::vector<char>> &data, int prio = 4)¶

Write data asynchronously, i.e. do not block upon call. Fire and forget, no callback called upon completion

Parameters

data: vector of chars containing the data to be written, passed as a shared pointer
prio: the priority of this write operation

virtual void writeAsync(const std::string &data, int prio = 4)¶

Write data asynchronously, i.e. do not block upon call. Fire and forget, no callback called upon completion

Parameters

data: passed as a string were each character represents one byte of the message
prio: the priority of this write operation

virtual void writeAsync(const karabo::util::Hash &data, int prio = 4, bool copyAllData = true)¶

Write data asynchronously, i.e. do not block upon call. Fire and forget, no callback called upon completion

Parameters

data: is contained in a Hash with no particular structure, but serializable, i.e. containing no non-karabo data types or Hash derived types
prio: the priority of this write operation
copyAllData: When false, raw data (ByteArray) inside an NDArray won’t be copied. For other kind of data, the value of this flag is ignored and a copy will take place.

virtual void writeAsync(const karabo::util::Hash &header, const char *data, const size_t &size, int prio = 4)¶

Write data asynchronously, i.e. do not block upon call. Fire and forget, no callback called upon completion

Parameters

data: Pointer to a contiguous block of memory that should be written
header: containing metadata for the data being written
size: This number of bytes will be written
prio: the priority of this write operation

virtual void writeAsync(const karabo::util::Hash &header, const std::vector<char> &data, int prio = 4)¶

Write data asynchronously, i.e. do not block upon call. Fire and forget, no callback called upon completion

Parameters

header: containing metadata for the data being written
data: vector of chars containing the data to be written
prio: the priority of this write operation

virtual void writeAsync(const karabo::util::Hash &header, const std::shared_ptr<std::vector<char>> &data, int prio = 4)¶

Write data asynchronously, i.e. do not block upon call. Fire and forget, no callback called upon completion

Parameters

header: containing metadata for the data being written
data: vector of chars containing the data to be written, passed as a shared pointer
prio: the priority of this write operation

virtual void writeAsync(const karabo::util::Hash &header, const std::string &data, int prio = 4)¶

Write data asynchronously, i.e. do not block upon call. Fire and forget, no callback called upon completion

Parameters

header: containing metadata for the data being written
data: passed as a string were each character represents one byte of the message
prio: the priority of this write operation

virtual void writeAsync(const karabo::util::Hash &header, const karabo::util::Hash &data, int prio = 4, bool copyAllData = true)¶

Write data asynchronously, i.e. do not block upon call. Fire and forget, no callback called upon completion

Parameters

header: containing metadata for the data being written
data: is contained in a Hash with no particular structure, but serializable, i.e. containing no non-karabo data types or Hash derived types
prio: the priority of this write operation.
copyAllData: When false, raw data (ByteArray) inside an NDArray won’t be copied. For other kind of data, the value of this flag is ignored and a copy will take place.

virtual void setAsyncChannelPolicy(int priority, const std::string &new_policy, const size_t capacity = 0)¶

Set the policy of how data is queue on this channel for the queue of the given priority. Policies are:

“LOSSLESS”: all data is queue and the queue increases in size within incoming data
”REJECT_NEWEST”: if the queue’s fixed capacity is reached new data is rejected
”REMOVE_OLDEST”: if the queue’s fixed capacity is the oldest data is rejected

NOTE: This method can potentially modify the capacity of a queue which is in use! This is undefined behavior. Users are encouraged to only call this method when intializing a Channel object instance.

Parameters

priority: of the queue to set the policy for
policy: to set for this queue
capacity: is an optional capacity for the queue

class Connection¶

#include <Connection.hh>

This class serves as the interface for all connections. A connection is only established upon call of the start() function.

Inherits from std::enable_shared_from_this< Connection >

Subclassed by karabo::net::TcpConnection

Public Functions

virtual ChannelPointer start() = 0¶: Starts the connection

virtual int startAsync(const ConnectionHandler &handler)¶

Starts the connection asynchronously

Parameters

handler: A callback with the following signature: void myHandler(ErrorCode, ChannelPointer)

virtual void stop() = 0¶: Stops the connection

virtual ChannelPointer createChannel() = 0¶

This function creates a “channel” for the given connection.

Return: Pointer to Channel

class ConnectionHandler¶

#include <AmqpConnection.hh>

Declare our custom ConnectionHandler to implement their callbacks. Every callback delegates processing to externally assigned callback if it was set. ConnectionHandler object calls its callbacks as follows… while connecting… onAttached, onConnected, onReady in case of error … onError, (onLost), onDetached in case of normal closure … onClosed, onDetached.

onAttached is called if new connection is associated with the handler onConnected is called if physical (TCP) connection is successfully established. onReady is called if login is successful onClosed is called in case of normal connection closure onError is called if errors encountered on connection onLost is called if onError was called and earlier onConnected was called. onDetached id called as a last step of connection loss

Inherits from LibBoostAsioHandler

class EventLoop¶

#include <EventLoop.hh>

Karabo’s central event loop. Asynchronous events are passed throughout the distributed system by posting to the loop.

Inherits from noncopyable

Public Static Functions

void addThread(const int nThreads = 1)¶

Add a number of threads to the event loop, increasing the number of thread available to handle events posted to the loop

Parameters

nThreads:

void removeThread(const int nThreads = 1)¶

Remove a number of threads from the event loop, reducing the number of threads available to handle events posted to the loop

Parameters

nThreads:

template <class Function>

void post(Function &&func, unsigned int delayMs = 0)¶

Post a task on the underlying io event loop for later execution

Parameters

func: a functor not taking any argument, but with any return type
delayMs: execution will be delayed by given time (in milliseconds)

boost::asio::io_service &getIOService()¶

Return the Eventloop’s underlying boost::asio::io_service

Return

void work()¶

Start the event loop and block until EventLoop::stop() is called.

The system signals SIGINT and SIGTERM will be caught and trigger the following actions:

a signal handler set via setSignalHandler is called,
and EventLoop::stop() is called.

Must not be called in parallel to itself or to run().

If one or more tasks are in deadlock and thus their threads cannot be joined at the end, a karabo::util::TimeoutException is thrown.

void run()¶

Start the event loop and block until all work posted to its io service is completed or until EventLoop::stop() is called.

Must not be called in parallel to itself or to work().

If one or more tasks are in deadlock and thus their threads cannot be joined at the end, a karabo::util::TimeoutException is thrown.

void stop()¶: Stop the event loop, canceling any remaining work, i.e. unblocking run()

size_t getNumberOfThreads()¶

Return the number of threads currently available to the event loop for distributing work

Return

void setSignalHandler(const SignalHandler &handler)¶

Set the handler to be called if a system signal is caught.

See work() about which signals are caught.

Parameters

handler: function with signature ‘void (int signal)’

Private Functions

void clearThreadPool()¶

Clears the thread pool and joins the threads

If joining fails repeatedly, throws karabo::util::TimeoutException.

class HttpClient¶

Public Functions

HttpClient(const std::string &baseURL, bool verifyCerts = false)¶

Creates a web client capable of submitting GET and POST requests to a given URL, over a secure or a plain connection.

Parameters

baseURL: the base URL to be prepended to each request path.
verifyCerts: when set to false, allows self generated server certificates when connecting securely (by bypassing certificate origin verification).

class Impl¶: Implementation of the WebClient class.

class HttpRequestRunner¶: Inherits from std::enable_shared_from_this< HttpRequestRunner >

class HttpsRequestRunner¶: Inherits from std::enable_shared_from_this< HttpsRequestRunner >

class InfluxDbClient¶

#include <InfluxDbClient.hh>

This class uses HTTP protocol for communications with InfluxDB server. The protocol follows request/response pattern and before sending next request the response from the current one should be received. Only one request/response session per connection is allowed. To follow this rule the internal queue is used. Any request (functor) first is pushed into internal queue and then checked the internal state if some current request/response session is ongoing. If not, the next request is popped from front side of internal queue and executed. The internal flag (state) is raised. When response callback is called it checks if the internal queue has next entry and if so this entry is popped and executed. If not, the internal flag is lowered. For the time being the internal queue has no limits defined so it is possible that if the client cannot cope with input load rate some overflow condition can be encountered. The practice should show how we can handle these problems.

Inherits from std::enable_shared_from_this< InfluxDbClient >

Public Functions

void startDbConnectIfDisconnected(const InfluxConnectedHandler &hook = InfluxConnectedHandler())¶

Check if connection is lost and try to re-establish connection to InfluxDB server

Parameters

hook: function that will be called when connection is established

bool isConnected()¶: Returns true if connection is established to InfluxDB server

std::string influxVersion()¶

The version of the InfluxDb server the client is connected to.

Return: std::string the connected InfluxDb server version (empty if no server is currently connected).

std::string serverUrl()¶

The url of the InfluxDb server the client is connected to (or supposed to connect to).

Return: std::string the InfluxDb server url.

void queryDb(const std::string &statement, const InfluxResponseHandler &action)¶

HTTP request “GET /query …” to InfluxDB server is registered in internal queue. Can be called with connection to InfluxDB or without. Blocking if no connection exists. Otherwise non-blocking.

Parameters

statement: is SELECT expression.
action: callback: void(const HttpResponse&) is called when response comes from InfluxDB server

void postQueryDb(const std::string &statement, const InfluxResponseHandler &action)¶

HTTP request “POST /query …” to InfluxDB server is registered in internal queue.

Parameters

statement: SELECT, SHOW, DROP and others QL commands
action: callback: void(const HttpResponse&) is called when response comes from InfluxDB server

void flushBatch(const InfluxResponseHandler &respHandler = InfluxResponseHandler())¶

Flushes the contents of the write buffer to the InfluxDb.

Parameters

respHandler: If defined, the handler function will be called with the response sent by Influx after it accepted and processed the current batch of updates. If not defined, the flushBatch will work in a call-and-forget mode.

void getPingDb(const InfluxResponseHandler &action)¶

HTTP request “GET /ping …” to InfluxDB server is registered in internal queue.

Parameters

action: callback: void(const HttpResponse&) is called when response comes from InfluxDB server

bool connectWait(std::size_t millis)¶

Returns true if connection is established in “millis” time range, otherwise timeout condition comes up and returns false.

Return

true if connection established, or false in case of timeout

Parameters

millis: time in milliseconds to wait for connection to be established

Public Static Functions

std::string generateUUID()¶: Returns UUID used as Request-ID for HTTP requests

Private Functions

void writeDb(const std::string &message, const std::string &requestId)¶

Writing HTTP request

Parameters

message: formed in compliance of HTTP protocol Malformed requests resulting in response code 4xx
requestId: unique id of the HTTP request to be sent to Influx.

void onDbConnect(const karabo::net::ErrorCode &ec, const karabo::net::Channel::Pointer &channel, const InfluxConnectedHandler &hook)¶: Low-level callback called when connection to InfluxDB is established

void onDbRead(const karabo::net::ErrorCode &ec, const std::string &data)¶: Low-level callback called when reading is done

void onDbWrite(const karabo::net::ErrorCode &ec, std::shared_ptr<std::vector<char>> p)¶: Low-level callback called when writing into networks interface is done

void postWriteDb(const std::string &batch, const InfluxResponseHandler &action)¶

HTTP request “POST /write …” to InfluxDB server is registered in internal queue.

Parameters

batch: is a bunch of lines following InfluxDB “line protocol” separated by newline (‘ ‘) the “line protocol” is detailed at https://influxdbcom.readthedocs.io/en/latest/content/docs/v0.9/write_protocols/write_syntax/
action: callback is called when acknowledgment (response) comes from InfluxDB server. The callback signature is void(const HttpResponse&). The success error code in HttpResponse structure is 204.

void postQueryDbTask(const std::string &statement, const InfluxResponseHandler &action)¶: Actual “POST /query …” is accomplished. Non-blocking call. The connection to InfluxDB has to be established before this call

void getPingDbTask(const InfluxResponseHandler &action)¶: Actual “GET /ping …” is accomplished. Non-blocking call. The connection to InfluxDB has to be established before this call

void postWriteDbTask(const std::string &batch, const InfluxResponseHandler &action)¶: Actual “POST /write …” is accomplished. Non-blocking call, Connection should be established before this call

void queryDbTask(const std::string &statement, const InfluxResponseHandler &action)¶: Actual “GET /query …” is accomplished. If no connection to DB, this call is blocked until the connection is established. Otherwise the call is non-blocking.

void onResponse(const HttpResponse &o, const InfluxResponseHandler &action)¶: Generic wrap callback is called and call in turn the user “action”.

void tryNextRequest(std::unique_lock<std::mutex> &requestQueueLock)¶

Try to take the next request from internal queue and execute it. Set internal state to be “active” if it was not. Helper function.

Parameters

requestQueueLock: must be locked scoped_lock of m_requestQueueMutex, will be unlocked afterwards

void sendToInfluxDb(const std::string &msg, const InfluxResponseHandler &action, const std::string &requestId)¶

Send HTTP request to InfluxDb. Helper function.

Wraps the given InfluxResponseHandler within a callback to onResponse. It will be up to onResponse to call the action InfluxResponseHandler and keep the consumption of requests submitted to the InfluxDbClient going.

std::string getRawBasicAuthHeader()¶

Gets the raw form of the http Authorization header with values of dbUser and dbPassword separated by a colon and base64 encoded.

Return: The raw form of the Authorization header.

void handleHttpReadError(const std::string &errMsg, const std::string &requestId, bool logAsError = true)¶

Handle unrecoverable read and parsing errors while processing HTTP responses from Influx.

The recovery involves recycling the network connection, as there is no way to recover synchronism in the read operation within the current connection after those kind of errors happen. Also generates an HTTP response with status code 700 and an error message to communicate to users of the InfluxDbClient instance.

Parameters

errMsg: the error message to be put in the generated 700 coded http response.
requestId: the unique identifier of the HTTP request whose response could not be processed (needed to update the internal bookeeping of the InfluxDb client).
logEsError: if true (default), log as info, else as error

class LosslessQueue¶

#include <Queues.hh>

The LosslessQueue implements a queue that guarantees to preserve messages.

Inherits from karabo::net::Queue

Subclassed by karabo::net::RejectNewestQueue

Public Functions

size_t size()¶

Return the size of the queue, i.e. the number of messages it holds

Return

size_t max_size()¶

Return the maximum allowed size of this queue

Return

void set_capacity(size_t capacity)¶

Set the capacity in terms of messages this queue can hold

Parameters

capacity:

size_t capacity()¶

Return this queues message capacity

Return

void clear()¶: Clear this queue

bool empty()¶

Check if this queue is empty, i.e. size is 0

Return

bool full()¶

Check if this queue is full, i.e. if it has reached its maximum capacity

Return

void resize(size_t new_size)¶

Resize the queue to a new size

Parameters

new_size:

const Message::Pointer &front()¶

Return the first element in the queue

Return

void push_back(const Message::Pointer &entry)¶

Add an element to the end of the queue, increases the size by one

Parameters

entry:

void pop_front()¶: Pop the first element from the queue, decreases the size by one

class Message¶

#include <Queues.hh>

This class represents a message in the distributed Karabo system.

Public Functions

const karabo::io::BufferSet::Pointer &body() const¶

Return the body of the message

Return

const VectorCharPointer &header() const¶

Return the header of the message

Return

class NetworkInterface¶

Public Functions

NetworkInterface(const std::string &name_or_ip, bool exclude_loopback = true)¶: Construct a NetworkInterface object from an interface or IP address.

const std::string &name() const¶: Return the interface name for the object (for instance, ‘lo’ or ‘enp4s0’)

const std::string &presentationIP() const¶

Return the presentation address for the object.

The presentation address is the IP address (four numbers between 0 and 255, separated with ‘.’)

Private Functions

void constructFromInterface(const struct ifaddrs *ifa)¶: Fill the object fields with the information specified in the ifaddrs object passed as parameter.

struct OneTimeTokenAuthorizeResult¶

#include <UserAuthClient.hh>

The results of a one-time token validation / authorization.

Subclassed by karabo::devices::BeginTemporarySessionResult

class Queue¶

#include <Queues.hh>

This class defines the interface for message queues in the Karabo distributed system.

Subclassed by karabo::net::LosslessQueue, karabo::net::RemoveOldestQueue

Public Functions

virtual size_t size() = 0¶

Return the size of the queue, i.e. the number of messages it holds

Return

virtual size_t max_size() = 0¶

Return the maximum allowed size of this queue

Return

virtual void set_capacity(size_t capacity) = 0¶

Set the capacity in terms of messages this queue can hold

Parameters

capacity:

virtual size_t capacity() = 0¶

Return this queues message capacity

Return

virtual void clear() = 0¶: Clear this queue

virtual bool empty() = 0¶

Check if this queue is empty, i.e. size is 0

Return

virtual bool full() = 0¶

Check if this queue is full, i.e. if it has reached its maximum capacity

Return

virtual void resize(size_t new_size) = 0¶

Resize the queue to a new size

Parameters

new_size:

virtual const Message::Pointer &front() = 0¶

Return the first element in the queue

Return

virtual void push_back(const Message::Pointer &entry) = 0¶

Add an element to the end of the queue, increases the size by one

Parameters

entry:

virtual void pop_front() = 0¶: Pop the first element from the queue, decreases the size by one

class RejectNewestQueue¶

#include <Queues.hh>

The RejectNewestQueue implements a queue that will reject new entries when it has reached its maximum capacity.

Inherits from karabo::net::LosslessQueue

Public Functions

void set_capacity(size_t capacity)¶

Set the capacity in terms of messages this queue can hold

Parameters

capacity:

size_t capacity()¶

Return this queues message capacity

Return

size_t max_size()¶

Return the maximum allowed size of this queue

Return

void push_back(const Message::Pointer &entry)¶

Add an element to the end of the queue, increases the size by one

Parameters

entry:

class RemoveOldestQueue¶

#include <Queues.hh>

The RemoveOldestQueue implements a queue that removes the oldest element in the queue when it has reached is maximum capacity and a new element is pushed to it.

Inherits from karabo::net::Queue

Public Functions

size_t size()¶

Return the size of the queue, i.e. the number of messages it holds

Return

size_t max_size()¶

Return the maximum allowed size of this queue

Return

void set_capacity(size_t capacity)¶

Set the capacity in terms of messages this queue can hold

Parameters

capacity:

size_t capacity()¶

Return this queues message capacity

Return

void clear()¶: Clear this queue

bool empty()¶

Check if this queue is empty, i.e. size is 0

Return

bool full()¶

Check if this queue is full, i.e. if it has reached its maximum capacity

Return

void resize(size_t new_size)¶

Resize the queue to a new size

Parameters

new_size:

const Message::Pointer &front()¶

Return the first element in the queue

Return

void push_back(const Message::Pointer &entry)¶

Add an element to the end of the queue, increases the size by one

Parameters

entry:

void pop_front()¶: Pop the first element from the queue, decreases the size by one

struct RemoveThreadException¶

#include <EventLoop.hh>

An exception that is thrown if a thread cannot be removed from the EventLoop

Inherits from std::exception

class Strand¶

#include <Strand.hh>

A poor man’s substitute for boost::asio::strand because that does not guarantee that handlers posted on different strands can run in parallel (“strand collision”). Compared to boost::asio::strand, this

lacks dispatch: we usually do not want that in Karabo since it allows the handler to be called now in this scope
lacks running_in_this_thread: probably not too important
has a more restrictive wrap: would be useful to support more, but a proper implementation would also need dispatch

Every handler posted will be put into a FIFO queue and the FIFO will be emptied in the background by posting the handlers to the given boost::asio::io_context (either from net::EventLoop, passed in constructor, or defined by setContext(..)).

NOTE: Do not create a Strand on the stack, but do it on the heap using the Configurator:

auto stack = karabo::util::Configurator<Strand>::create(Hash(…));

Otherwise ‘enable_shared_from_this’ does not work which is needed to guarantee (via usage of karab::util::bind_weak) that an internal Strand method is executed on the event loop when the Strand is already destructed.

Inherits from std::enable_shared_from_this< Strand >

Public Functions

Strand(boost::asio::io_context &ioContext)¶

Contructor only kept for backward compatibility.

Better use karabo::util::Configurator<Strand>::create(“Strand”, Hash())

Strand(const karabo::util::Hash &config)¶

Construct the Strand.

The boost::asio::io_context of the karabo::net::EventLoop will be used.

Best use this constructor indirectly via karabo::util::Configurator<Strand>::create(“Strand”, cfg) which will validate cfg and create the Strand properly on the heap.

Keys of cfg are “maxInARow” (unsigned int) and “guaranteeToRun” (bool), see expectedParameters.

void setContext(boost::asio::io_context &ioContext)¶

Set the context to which the handlers are to be posted.

No concurrency protection: Must be called directly after Strand creation, before it is used.

void post(const std::function<void()> &handler)¶

Post a handler to the io_context with the guarantee that it is not executed before any other handler posted before has finished. Handlers posted on different Strands can always be run in parallel.

Note that “guaranteeToRun” flag of the constructor determines what happens with yet unhandled handlers when the Strand is destructed.

Parameters

handler: function without arguments and return value - will be copied

void post(std::function<void()> &&handler)¶

Post a handler to the io_context with the guarantee that it is not executed before any other handler posted before has finished. Handlers posted on different Strands can always be run in parallel.

Note that “guaranteeToRun” flag of the constructor determines what happens with yet unhandled handlers when the Strand is destructed.

Parameters

handler: function without arguments and return value as r-value reference - will be moved to avoid a copy

std::function<void()> wrap(std::function<void()> handler)¶

This function is used to create a new handler function object that, when invoked, will pass the wrapped handler to the Strand’s post function (instead of using dispatch as boost::io_service::strand::wrap does).

Return

A function object that, when invoked, passes the wrapped handler to the Strand’s post function.

Parameters

handler: The handler to be wrapped. The strand will make a copy of the handler object. Compared to boost::io_service::strand::wrap, the handler signature is much more restricted, i.e. must be void().

boost::asio::io_context &getContext() const¶

This function may be used to obtain the io_context object that the strand uses to post handlers.

Return: A reference to the io_context of the Strand. Ownership is not transferred to the caller.

boost::asio::io_context &get_io_service() const¶

Deprecated.

Use getContext() instead.

Private Functions

void startRunningIfNeeded()¶: Helper for post - to be called under protection of m_tasksMutex!

void run()¶: Helper to run one task after another until tasks queue is empty.

class TcpChannel¶

Inherits from karabo::net::Channel

Public Functions

Connection::Pointer getConnection() const¶: Pointer to connection of this channel - empty if that is not alive anymore

size_t readSizeInBytes()¶

Synchronously reads the TCP message’s size. Will block until a message arrives on the socket.

Return: Size in bytes of incoming TCP message

void readAsyncSizeInBytes(const ReadSizeInBytesHandler &handler)¶

In case a TCP message arrived, handler will be called back The handler will inform about the number of bytes going to come in The handler must have the following signature: void handler(Channel::Pointer, const size_t&)

Parameters

handler: Callback with signature: void (Channel::Pointer, const size_t&)

std::string consumeBytesAfterReadUntil(const size_t nBytes)¶

Synchronously reads size bytes and return them as a string. The reading will block until the bytes are read.

Note

reads up nBytes expecting no header. This method should ONLY be used in association with readAsyncStringUntil - they consume from the same boost::asio::streamBuffer and should not be used in the same context of the other read* methods.

Parameters

size: This number of bytes will be copied into data

void read(char *data, const size_t &size)¶

Synchronously reads size bytes from TCP socket into data.

Parameters

data: Pre-allocated contiguous block of memory
size: This number of bytes will be copied into data

void read(std::vector<char> &data)¶

This function reads from a channel into vector of chars The reading will block until the data record is read. The vector will be updated accordingly (must not be pre-allocated before)

Return: void

void read(std::shared_ptr<std::vector<char>> &data)¶

This function reads from a channel into shared pointer of vector of chars The reading will block until the data record is read. The shared pointer of vector will be updated accordingly (must not be pre-allocated before)

Return: void

void read(karabo::util::Hash &data)¶

This function reads from a channel into vector of chars The reading will block until the data record is read. The size of data record is the first 4 bytes in a channel stream. The hash will be updated accordingly.

Return: void

void read(karabo::util::Hash &header, char *data, const size_t &size)¶

Synchronously reads size bytes from socket into data and provides a header.

Parameters

header: Hash object which will be updated to contain header information
data: Pre-allocated contiguous block of memory
size: This number of bytes will be copied into data

void read(karabo::util::Hash &header, std::vector<char> &data)¶

This function reads into a header and a vector of chars. The reading will block until the data record is read.

Parameters

header: Hash object which will be updated to contain header information
data: A vector which will be updated accordingly

void read(karabo::util::Hash &header, std::shared_ptr<std::vector<char>> &data)¶

This function reads into a header and shared pointer of vector of chars. The reading will block until the data record is read.

Parameters

header: Hash object which will be updated to contain header information
data: A shared pointer of a vector which will be updated accordingly

void read(karabo::util::Hash &header, karabo::util::Hash &data)¶

This function reads into a header hash and a data hash. The reading will block until the data record is read. The reading will block until the data record is read.

Parameters

header: Hash object which will be updated to contain header information
data: Hash object which will be updated to contain data information

void readAsyncRaw(char *data, const size_t &size, const ReadRawHandler &handler)¶

Asynchronously reads size number of bytes into pre-allocated data buffer A handler can be registered to inform about completion of writing

Parameters

data: Pre-allocated contiguous block of memory
size: This number of bytes will be copied into data
handler: Function of signature: <void (Channel::Pointer)> which will be call-backed upon read completion

void readAsyncStringUntil(const std::string &terminator, const ReadStringHandler &handler)¶

wrapper around boost::asio::async_read_until

Read a string until terminator string is found. (No header is expected).

Note

This method should ONLY be used in association with consumeBytesAfterReadUntil - they consume from the same boost::asio::streambuf and should not be used in the same context of the other read* methods.

Parameters

terminator: when this string found, read is done
handler: handler with signature ReadStringHandler, i.e. void (const boost::system::error_code&, std::string&) is called. second handler parameter is the read string including the terminator

void readAsyncString(const ReadStringHandler &handler)¶

Asynchronously reads data into a string. All memory management is done by the API. NOTE: A string in general is not storing data contiguously. Thus, an additional copy under the hood is needed which makes this interface slightly slower.

Parameters

handler: Call-function of signature: void (Channel::Pointer, const std::string&)

void readAsyncVector(const ReadVectorHandler &handler)¶

Asynchronously reads data into a vector<char>. All memory management is done by the API.

Parameters

handler: Call-function of signature: void (Channel::Pointer, const std::vector<char>&)

void readAsyncHash(const ReadHashHandler &handler)¶

Asynchronously reads data into a hash. All memory management is done by the API.

Parameters

handler: Call-function of signature: void (Channel::Pointer, const karabo::util::Hash&)

void readAsyncHashPointer(const ReadHashPointerHandler &handler)¶

Asynchronously reads data into a hash. All memory management is done by the API.

Parameters

handler: Call-function of signature: void (Channel::Pointer, const karabo::util::Hash&)

void readAsyncVectorPointer(const ReadVectorPointerHandler &handler)¶

Asynchronously reads data into a vector<char>. All memory management is done by the API.

Parameters

handler: Call-function of signature: void (Channel::Pointer, const std::vector<char>&)

void readAsyncHashVector(const ReadHashVectorHandler &handler)¶

Asynchronously reads data into a hash header and a vector<char>. All memory management is done by the API.

Parameters

handler: Call-function of signature: void (Channel::Pointer, const karabo::util::Hash&, const std::vector<char>&)

void readAsyncHashString(const ReadHashStringHandler &handler)¶

Asynchronously reads data into a hash header and a string. All memory management is done by the API. NOTE: A string in general is not storing data contiguously. Thus, an additional copy under the hood is needed which makes this interface slightly slower.

Parameters

handler: Call-function of signature: void (Channel::Pointer, const karabo::util::Hash&, const std::string&)

void readAsyncHashHash(const ReadHashHashHandler &handler)¶

Asynchronously reads data into a hash header and a hash body. All memory management is done by the API.

Parameters

handler: Call-function of signature: void (const ErrorCode&, const karabo::util::Hash&, const karabo::util::Hash&)

void readAsyncHashPointerHashPointer(const ReadHashPointerHashPointerHandler &handler)¶

Asynchronously reads data into a hash header and a hash body. All memory management is done by the API.

Parameters

handler: Call-function of signature: void (const ErrorCode&, const karabo::util::Hash&, const karabo::util::Hash&)

void readAsyncHashVectorPointer(const ReadHashVectorPointerHandler &handler)¶

Asynchronously reads data into a hash header and a vector<char>. All memory management is done by the API.

Parameters

handler: Call-function of signature: void (const ErrorCode&, const karabo::util::Hash&, const std::vector<char>&)

void readAsyncHashVectorBufferSetPointer(const ReadHashVectorBufferSetPointerHandler &handler)¶

Asynchronously reads data into a hash header and into a vector of BufferSet pointers. All memory management is done by the API.

Parameters

handler: Call-function of signature: void (const ErrorCode&, const karabo::util::Hash&, const std::vector<karabo::io::BufferSet::Pointer>&)

void write(const char *data, const size_t &size)¶

Synchronous write. The function blocks until all bytes are written.

Parameters

data: Pointer to a contiguous block of memory that should be written
size: This number of bytes will be written

void write(const karabo::util::Hash &header, const char *data, const size_t &size)¶

Synchronous write. The function blocks until all bytes are written.

Parameters

header: containing metadata for the data being written
data: Pointer to a contiguous block of memory that should be written
size: This number of bytes will be written

void write(const karabo::util::Hash &data)¶

Synchronous write. The function blocks until all bytes are written.

Parameters

data: is contained in a Hash with no particular structure, but serializable, i.e. containing no non-karabo data types or Hash derived types

void write(const karabo::util::Hash &header, const std::vector<karabo::io::BufferSet::Pointer> &body)¶

Synchronous write. The function blocks until all bytes are written.

Parameters

header: containing metadata for the data being written and BufferSet’s layout
body: vector of BufferSet pointers

void write(const karabo::util::Hash &header, const karabo::util::Hash &body)¶

Synchronous write. The function blocks until all bytes are written.

Parameters

header: containing metadata for the data being written
data: is contained in a Hash with no particular structure, but serializable, i.e. containing no non-karabo data types or Hash derived types

void writeAsyncRaw(const char *data, const size_t &size, const WriteCompleteHandler &handler)¶

Write data asynchronously, i.e. do not block upon call. Upon write completion a handler function is called

Parameters

data: Pointer to a contiguous block of memory that should be written
size: This number of bytes will be written
handler: to be called upon write completion handler. Needs to be a function wrapped into a std::function which takes const boost::system::error_code& as its only argument.

void writeAsyncVector(const std::vector<char> &data, const WriteCompleteHandler &handler)¶

Write data asynchronously, i.e. do not block upon call. Upon write completion a handler function is called

Parameters

data: vector of chars containing the data to be written
handler: to be called upon write completion handler. Needs to be a function wrapped into a std::function which takes const boost::system::error_code& as its only argument.

void writeAsyncHash(const karabo::util::Hash &data, const WriteCompleteHandler &handler)¶

Write data asynchronously, i.e. do not block upon call. Upon write completion a handler function is called

Parameters

data: is contained in a Hash with no particular structure, but serializable, i.e. containing no non-karabo data types or Hash derived types
handler: to be called upon write completion handler. Needs to be a function wrapped into a std::function which takes const boost::system::error_code& as its only argument.

void writeAsyncHashRaw(const karabo::util::Hash &header, const char *data, const size_t &size, const WriteCompleteHandler &handler)¶

Write data asynchronously, i.e. do not block upon call. Upon write completion a handler function is called

Parameters

header: containing metadata for the data being written
data: Pointer to a contiguous block of memory that should be written
size: This number of bytes will be written
handler: to be called upon write completion handler. Needs to be a function wrapped into a std::function which takes const boost::system::error_code& as its only argument.

void writeAsyncHashVector(const karabo::util::Hash &header, const std::vector<char> &data, const WriteCompleteHandler &handler)¶

Write data asynchronously, i.e. do not block upon call. Upon write completion a handler function is called

Parameters

header: containing metadata for the data being written
data: vector of chars containing the data to be written
handler: to be called upon write completion. Needs to be a function wrapped into a std::function which takes const boost::system::error_code& as its only argument.

void writeAsyncHashVectorBufferSetPointer(const karabo::util::Hash &header, const std::vector<karabo::io::BufferSet::Pointer> &body, const WriteCompleteHandler &handler)¶

Write header and vector<BufferSet::Pointer> asynchronously.

Upon write completion a handler function is called. Data inside the buffers must not be changed or deleted before this handler is called. Special care is needed if any Hash that had been serialised into the buffers contained an NDArray: The raw data of the array will be shared between the BufferSet and the Hash. Deletion of the Hash is safe, though.

Parameters

header: containing metadata for the data being written
body: data as a vector of BufferSet::Pointer
handler: to be called upon write completion. Needs to be a function wrapped into a std::function which takes const boost::system::error_code& as its only argument.

void writeAsyncHashHash(const karabo::util::Hash &header, const karabo::util::Hash &data, const WriteCompleteHandler &handler)¶

Write data asynchronously, i.e. do not block upon call. Upon write completion a handler function is called

Parameters

header: containing metadata for the data being written
body: data contained in a Hash with no particular structure, but serializable, i.e. containing no non-karabo data types or Hash derived types
handler: to be called upon write completion. Needs to be a function wrapped into a std::function which takes const boost::system::error_code& as its only argument.

size_t dataQuantityRead()¶: Returns the number of bytes read since the last call of this method

size_t dataQuantityWritten()¶: Returns the number of bytes written since the last call of this method

void close()¶: Close this channel

bool isOpen()¶

Check if this channel is open

Return

karabo::util::Hash queueInfo()¶: Records the sizes of the write queues in a Hash. Useful for debugging devices with multiple channels open (like the GuiServerDevice…)

std::string remoteAddress() const¶: Address of the remote endpoint

void writeAsync(const char *data, const size_t &size, int prio)¶: Writes a copy from the data array.

void writeAsync(const std::vector<char> &data, int prio)¶: Writes a copy of the data vector.

void writeAsync(const std::shared_ptr<std::vector<char>> &data, int prio)¶: Sends the vector pointed by data. The data vector must not be changed after the call to writeAsync.

void writeAsync(const std::string &data, int prio)¶: Writes a copy of the data string.

void writeAsync(const karabo::util::Hash &data, int prio, bool copyAllData)¶: When copyAllData is false, elements of type NDArray in the hash won’t be copied before being sent.

void writeAsync(const karabo::util::Hash &header, const char *data, const size_t &size, int prio)¶: Writes copies of the header hash and the data array.

void writeAsync(const karabo::util::Hash &header, const std::vector<char> &data, int prio)¶: Writes copies of the header hash and of the data vector.

void writeAsync(const karabo::util::Hash &header, const std::shared_ptr<std::vector<char>> &data, int prio)¶: Writes a copy of the header hash. Sends the vector pointed by data, not a copy of it. The data vector must not be changed after the call to writeAsync.

void writeAsync(const karabo::util::Hash &header, const std::string &data, int prio)¶: Writes copies of the header hash and of the data string.

void writeAsync(const karabo::util::Hash &header, const karabo::util::Hash &data, int prio, bool copyAllData)¶: When copyAllData is false, elements of type NDArray in the body hash won’t be copied before being sent. copyAllData doesn’t influence the handling of the header hash.

void setAsyncChannelPolicy(int priority, const std::string &new_policy, const size_t capacity = 0)¶

Set the policy of how data is queue on this channel for the queue of the given priority. Policies are:

“LOSSLESS”: all data is queue and the queue increases in size within incoming data
”REJECT_NEWEST”: if the queue’s fixed capacity is reached new data is rejected
”REMOVE_OLDEST”: if the queue’s fixed capacity is the oldest data is rejected

NOTE: This method can potentially modify the capacity of a queue which is in use! This is undefined behavior. Users are encouraged to only call this method when intializing a Channel object instance.

Parameters

priority: of the queue to set the policy for
policy: to set for this queue
capacity: is an optional capacity for the queue

Public Static Functions

karabo::util::Hash getChannelInfo(const std::shared_ptr<karabo::net::TcpChannel> &ptr)¶

This function returns low level info about connection like … “localIp”, “localPort”, “remoteIp”, “remotePort” that constitute active connection. in form of Hash container

Return

Hash with 4 key/value pairs

Parameters

ptr: input TcpChannel boost shared pointer

Private Functions

void bytesAvailableHandler(const boost::system::error_code &e)¶

Internal default handler

Parameters

channel:

void onSizeInBytesAvailable(const ErrorCode &error, const ReadSizeInBytesHandler &handler)¶

This function calls the corresponding handler

Parameters

handler:
error:

void onVectorBufferSetPointerAvailable(const ErrorCode &error, size_t length, const std::vector<karabo::io::BufferSet::Pointer> &buffers, const ReadVectorBufferSetPointerHandler &handler)¶

Internal handler called after filling the buffer set

Parameters

error: error code
length: number of bytes read == total size of buffer set
buffers: vector of buffer set pointers with the data
handler: to be called

void byteSizeAvailableHandler(const size_t byteSize)¶

Internal default handler

Parameters

byteSize:

karabo::io::BufferSet::Pointer bufferSetFromString(const std::string &str)¶

Creates a buffer set with the given string stored in its sole buffer.

Return

shared_ptr to the buffer set with the string stored.

Note

actually places a copy of the string into the buffer set.

Parameters

str: the string to be stored in the buffer set.

karabo::io::BufferSet::Pointer bufferSetFromPointerToChar(const char *data, size_t size)¶

Creates a buffer set with contents of a given buffer of chars stored in its sole buffer.

Return

shared_ptr to the buffer set with the input buffer contents stored.

Note

actually places a copy of the contents of the input buffer into the buffer set.

Parameters

data: a pointer to the first char in the input sequence.

karabo::io::BufferSet::Pointer bufferSetFromVectorCharPointer(const VectorCharPointer &dataVect)¶

Creates a buffer set with characters in a given vector of chars stored in its sole buffer.

Return

shared_ptr to the buffer set with the character in the vector stored.

Parameters

data: a pointer to the vector of chars to be stored in the buffer set.

karabo::io::BufferSet::Pointer bufferSetFromHash(const karabo::util::Hash &data, bool copyAllData)¶

Creates a buffer set with a given hash stored in its sole buffer.

Return

pBuffSet a shared pointer that will be pointed to the newly created buffer set with the hash.

Parameters

data: the hash to be stored in the buffer set.
copyAllData: if false no copy of any NDArray internal to the hash will be made upon storing the hash in the bufferset (the buffer set will actually become one of the “owners” of the NDArray).

unsigned int storeCompleteHandler(const WriteCompleteHandler &handler)¶

Helper to store async write completion handler

Return

index under which handler is stored in internal map

Parameters

handler: write completion handler to be stored

void applySocketKeepAlive()¶

Helper to apply the TCP keep-alive settings to the socket if configured to do so.

Requires that m_socketMutex is locked.

class TcpConnection¶

#include <TcpConnection.hh>

a class for handling tcp connections

This class serves as the interface for all connections. A connection is only established upon call of the start() function. It is a factory class and thus can be configured using its expected parameters

Inherits from karabo::net::Connection

Public Functions

Channel::Pointer start()¶: Starts the connection

int startAsync(const ConnectionHandler &slot)¶: Starts the connection asynchronously providing a slot

void stop()¶: Closes the connection

ChannelPointer createChannel()¶

This function creates a “channel” for the given connection.

Return: Pointer to Channel

class UserAuthClient¶

Public Functions

void authorizeOneTimeToken(const std::string &token, const std::string &topic, const AuthOneTimeTokenHandler &handler)¶

Validate and authorize, asynchronously, a given one-time token against a given topic.

Parameters

token: the token to be validated and authorized.
topic: the topic against which the user linked to a valid token will be authorized.
handler: the handler to be called when the token is processed.

namespace consumer¶

Typedefs

using karabo::net::consumer::MessageHandler = typedef std::function<void(karabo::util::Hash::Pointer, karabo::util::Hash::Pointer)>

using karabo::net::consumer::ErrorNotifier = typedef std::function<void(Error, const std::string& description)>

Enums

enum Error¶

Values:

drop = 0¶

type¶: messages have been dropped

unknown¶

status reported is not specially treated or unknown

message of wrong type (i.e. non binary format, serialisation failure, …) received and dropped

The karabo::xms Namespace¶

namespace karabo::xms¶

Namespace for package xms

Namespace for package io

Typedefs

typedef InputChannelElement INPUT_CHANNEL_ELEMENT¶

typedef InputChannelElement INPUT_CHANNEL¶

typedef std::function<void(const std::vector<karabo::util::Hash>&)> ShowConnectionsHandler¶

typedef std::function<void(const std::vector<unsigned long long>&, const std::vector<unsigned long long>&)> ShowStatisticsHandler¶

typedef std::function<std::string(const std::vector<std::string>&)> SharedInputSelector¶

typedef OutputChannelElement OUTPUT_CHANNEL_ELEMENT¶

typedef OutputChannelElement OUTPUT_CHANNEL¶

Functions

Hash getHeartbeatInfo(const Hash &instanceInfo)¶

Variables

const int kMaxServerInitializationAttempts = 2000¶

const int msPingTimeoutInIsValidInstanceId = 1000¶: Milliseconds of timeout when asking for validity of my id at startup:

const char *beatsTopicSuffix = "_beats"¶

const int channelReconnectIntervalSec = 6¶

const int getOutChannelInfoTimeoutMsec = 3000¶

class InputChannel¶

#include <InputChannel.hh>

The InputChannel class is used to receive data from pipelined processing OutputChannels.

The InputChannel class is used to receive data from pipelined processing OutputChannels. It additionally supports receiving meta data associated with each data token read. Specifically, the meta information contains source information, i.e. what produced the data token, and timing information, e.g. train ids.

void onInput(const InputChannel::Pointer& input) {

     for (unsigned int i = 0; i != input->size(); ++i) {
          Hash h;
          const InputChannel::MetaData& meta = input->read(i);
          std::cout<<"Source: <<meta.getSource()<<std::endl;
          std::cout<<"TrainId: <<meta.getTimestamp().getTrainId()<<std::endl;
     }
}

Inherits from std::enable_shared_from_this< InputChannel >

Public Functions

InputChannel(const karabo::util::Hash &config)¶

If this object is constructed using the factory/configuration system this method is called

See

expectedParameters) and default-filled configuration

Parameters

input: Validated (

void reconfigure(const karabo::util::Hash &config, bool allowMissing = true)¶

Reconfigure InputChannel Disconnects any previous “connectedOutputChannels” if not in config[“connectedOutputChannels”].

Parameters

config: as needed by the constructor
allowMissing: if true, lack of keys “dataDistribution”, “minData”, “onSlowness”, “delayOnInput” and “respondToEndOfStream” is OK and their respective previous configuration is kept, if false, an exception is thrown when these keys are missing in config

void registerInputHandler(const InputHandler &ioInputHandler)¶

Register handler to be called when new data has arrived. For each index i from 0 to < size(), data and meta data can be received via read(i, dataHash) and readMetaData(i, metaData), respectively.

Note: The internal variable that stores the handler is neither protected against concurrent calls to getRegisteredHandlers() nor to concurrent usage of the handler when data arrives, i.e. this registration must not be called if (being) connected to any output channel.

void registerDataHandler(const DataHandler &ioDataHandler)¶

Register handler to be called for each data item that arrives.

Note: The internal variable that stores the handler is neither protected against concurrent calls to getRegisteredHandlers() nor to concurrent usage of the handler when data arrives, i.e. this registration must not be called if (being) connected to any output channel.

void registerEndOfStreamEventHandler(const InputHandler &endOfStreamEventHandler)¶

Register handler to be called when connected output channels inform about end-of-stream. If connected to more than one output channel, the handler is called if the last of them sends the end-of-stream signal.

Note: The internal variable that stores the handler is neither protected against concurrent calls to getRegisteredHandlers() nor to concurrent usage of the handler when the end-of-stream signal arrives, i.e. this registration must not be called if (being) connected to any outpu channel.

InputChannel::Handlers getRegisteredHandlers() const¶

Get handlers registered for data, input and end-of-stream handling.

Do not call concurrrently with the corresponding register[Data|Input|EndOfStreamEvent]Handler() methods.

size_t dataQuantityRead()¶

Returns the number of bytes read since the last call of this method

See karabo::util::TcpChannel::dataQuantityRead()

size_t dataQuantityWritten()¶

Returns the number of bytes written since the last call of this method

See karabo::util::TcpChannel::dataQuantityWritten()

std::map<std::string, karabo::util::Hash> getConnectedOutputChannels()¶

Returns a map of between “output channel string” and “output channel info” Hash outputChannelString (STRING) represented like “instanceId@channelName” or “instanceId:channelName” outputChannelInfo contains connection parameters or is empty, depending on connection state. This contains all output channels that the InputChannel is configured for, irrespective whether currently connected or not.

Return: map.

std::unordered_map<std::string, karabo::net::ConnectionStatus> getConnectionStatus()¶

Provide a map between the output channels that are configured and their connection status.

Return: map

const InputChannel::MetaData &read(karabo::util::Hash &data, size_t idx = 0)¶

Read data from the InputChannel - to be called inside an InputHandler callback

Kept for backward compatibility only since internally the data is copied! Use one of the other read methods instead.

Return

meta data associated to the data token. Lifetime of the object corresponds to live time of the InputHandler callback.

Parameters

data: reference that will hold the data
idx: of the data token to read from the available data tokens. Use InputChannel::size to request number of available tokens

karabo::util::Hash::Pointer read(size_t idx = 0)¶

Read data from the InputChannel - to be called inside an InputHandler callback

Return

the data as a pointer

Parameters

idx: of the data token to read from the available data tokens. Use InputChannel::size to request number of available tokens

karabo::util::Hash::Pointer read(size_t idx, MetaData &source)¶

Read data and meta data from the InputChannel - to be called inside an InputHandler callback

Return

the data as a pointer

Parameters

idx: of the data token to read from the available data tokens. Use InputChannel::size to request number of available tokens
source: reference that will hold the meta data

size_t size()¶: Number of data tokens - to be called inside an InputHandler callback

void connect(const karabo::util::Hash &outputChannelInfo, const std::function<void(const karabo::net::ErrorCode&)> &handler = std::function<void(const karabo::net::ErrorCode&)>())¶

Asynchronously connect this input channel to the output channel described by the first argument

Parameters

outputChannelInfo: Hash with three keys
- ”outputChannelString”: a string matching one of the configured “connectedOutputChannels”
- ”connectionType”: a string - currently only “tcp” supported
- ”hostname”: a string telling which host/ip address to connect to
- ”port”: an unsigned int telling the port
- ”memoryLocation: string “remote” or “local” to tell whether other end is in another process or can share memory
handler: indicates asynchronously (like via EventLoop::post) the success of the connection request

void disconnect(const std::string &connectionString)¶

Disconnect and clean internals

Parameters

connectionString: One of the “connectedOutputChannels” given at construction

void updateOutputChannelConfiguration(const std::string &outputChannelString, const karabo::util::Hash &config = karabo::util::Hash())¶

Update list of output channels that can be connected

Parameters

outputChannelString: string that can later be used as key “outputChannelString” of Hash argument to connect
config: kept for backward compatibility

const std::vector<InputChannel::MetaData> &getMetaData() const¶

Get the current meta data for input data available on this input channel. Validity time of the object corresponds to lifetime of the InputHandler callback. Also the InputHandler this is called in needs to have been registered using registerInputHandler.

Return

std::vector<unsigned int> sourceToIndices(const std::string &source) const¶

Return the list of indices of the data tokens (for read(index) ) for a given source identifier. Multiple indices may be returned if the same source was appended more than once in one batch write. Indices increase monotonically in insertion order of the write operations. Validity time of the indices corresponds to lifetime of the InputHandler callback. Also the InputHandler this is called in needs to have been registered using registerInputHandler.

Return

Parameters

source:

std::vector<unsigned int> trainIdToIndices(unsigned long long trainId) const¶

Return the list of indices of the data tokens (for read(index) ) for a given train id. Multiple indices may be returned if the same source was appended more than once in one batch write. Indices increase monotonically in insertion order of the write operations. Validity time of the indices corresponds to lifetime of the InputHandler callback. Also the InputHandler this is called in needs to have been registered using registerInputHandler.

Return

Parameters

source:

const InputChannel::MetaData &indexToMetaData(unsigned int index) const¶

Return the data source identifier pertinent to a data token at a given index. Validity time of the object corresponds to lifetime of the InputHandler callback. Also the InputHandler this is called in needs to have been registered using registerInputHandler.

Return

Parameters

index:

Exceptions

A: KARABO_LOGIC_EXCEPTION of there is no meta data available for the given index.

Public Static Functions

void expectedParameters(karabo::util::Schema &expected)¶

Necessary method as part of the factory/configuration system

Parameters

expected: [out] Description of expected parameters for this object (Schema)

Private Functions

void disconnectImpl(const std::string &outputChannelString)¶

Disconnect internals - needs protection by m_outputChannelsMutex

Parameters

outputChannelString: One of the “connectedOutputChannels” given at construction

void prepareData()¶

Prepares data and metadata from the active chunk.

prepareData assumes that it has exclusive access to the m_activeChunk member variable when it’s called. Is up to the caller to guarantee that assumption.

Private Members

InputHandler m_inputHandler¶: Callback on available data (per InputChannel)

DataHandler m_dataHandler¶: Callback on available data (per item in InputChannel)

std::unordered_map<std::string, std::pair<unsigned int, std::function<void(const karabo::net::ErrorCode&)>>> m_connectionsBeingSetup¶: All ‘outputChannelString’ for that a connection attempt is currently ongoing, with their handlers and ids

struct Handlers¶

#include <InputChannel.hh>

Container for InputChannel handlers that concern data handling.

Public Functions

Handlers(const DataHandler &data, const InputHandler &eos = InputHandler())¶: Construct with data and end-of-stream handlers - input handler could be specified afterwards

Handlers(const InputHandler &input, const InputHandler &eos = InputHandler())¶: Construct with input and end-of-stream handlers - data handler could be specified afterwards

class Memory¶

#include <Memory.hh>

The Memory class is an internal utility for InputChannel and OutputChannel to provide static shared memory.

Public Static Functions

void read(karabo::util::Hash &data, const size_t dataIdx, const size_t channelIdx, const size_t chunkIdx)¶

Read the contents of a single Hash out of the cache. The passed in Hash will be cleared first.

Parameters

data:
dataIdx:
channelIdx:
chunkIdx:

Memory::DataPointer read(const size_t dataIdx, const size_t channelIdx, const size_t chunkIdx)¶

Read the contents of a single Hash out of the cache. A pointer tag_of a newly created Hash will be returned.

Parameters

dataIdx:
channelIdx:
chunkIdx:

void write(const karabo::util::Hash &data, const size_t channelIdx, const size_t chunkIdx, const MetaData &metaData, bool copyAllData = true)¶

Write the contents of a single Hash into the cache. The Hash will be serialized before control is returned to the caller. Note that the data of an NDArray inside the Hash will not be copied, i.e. the Memory internal buffer will point to the same memory as the NDArray, except if copyAllData = true. it is safe to mutate the Hash after writing it.

Parameters

data: input
channelIdx: where to store the serialised data
chunkIdx: where to store the serialised data
metaData: of the data
copyAllData: defines whether all data (incl. NDArray data) is copied into the internal buffer (default: true)

void assureAllDataIsCopied(const size_t channelIdx, const size_t chunkIdx)¶

Ensure that the data of given chunk is not shared with anyone else, i.e. copy data if needed.

Parameters

channelIdx:
chunkIdx:

const std::vector<Memory::MetaData> &getMetaData(const size_t channelIdx, const size_t chunkIdx)¶

Return a vector of MetaData objects for the data tokens in the bucket identified by channelIdx and chunkIdx.

Return

Parameters

channelIdx:
chunkIdx:

class MetaData¶

Inherits from karabo::util::Hash

Public Functions

MetaData(const std::string &source, const karabo::util::Timestamp &timestamp)¶

Constructor to directly set meta data entries

Parameters

source: an identifier of the data producer
timestamp: a timestamp relevant for this data token.

void setSource(const std::string &source)¶

Set data source, i.e. identifier of the data producer

Parameters

source:

const std::string &getSource() const¶

Get data source, i.e. identifier of the data producer

Return

void setTimestamp(const karabo::util::Timestamp &timestamp)¶

Set the timestamp relevant to this data token

Parameters

timestamp:

const karabo::util::Timestamp getTimestamp() const¶

Get the timestamp relevant to this data token

Return

class OutputChannel¶

#include <OutputChannel.hh>

An OutputChannel for passing data to pipelined processing.

The OutputChannel class is used for writing data to pipelined processing inputs. It supports tracking of meta data for each data token written to it. Specifically, it e.g. allows for keeping track of data producers, here called sources, and timing and train information. Meta data information enables aggregation of multiple data source into one output channel interaction with a remote host, as well as aggregation of multiple train-related data of the same source. A mixture of both scenarios is possible.

An example of these use cases

OutputChannel::Pointer output = ... //

Hash data1;
....
OutputChannel::MetaData meta1("THIS/IS/SOURCE/A/channel1", karabo::util::Timestamp());
output->write(data1, meta1)

Hash data2_10;
....
OutputChannel::MetaData meta2_10("THIS/IS/SOURCE/B/channel2", timestampForTrain10);
output->write(data2_10, meta2)
OutputChannel::MetaData meta2_11("THIS/IS/SOURCE/B/channel2", timestampForTrain11);
output->write(data2_11, meta2_11)

Hash data_this_source;
...
// not passing any meta data to write will default the source to [deviceId]/[channelName]
// and the timestamp to the current timestamp
output->write(data_this_source);

// now actually send over the network
output->update();

Inherits from std::enable_shared_from_this< OutputChannel >

Public Functions

OutputChannel(const karabo::util::Hash &config)¶

If this object is constructed using the factory/configuration system this method is called.

The initialize() method must not be called if constructed this way.

Deprecated: Tcp server initialization is triggered, but there is no control when and whether it succeeded. So better use the constructor with additional int argument (and set it to zero).

See

expectedParameters) and default-filled configuration

Parameters

config: Validated (

OutputChannel(const karabo::util::Hash &config, int autoInit)¶

Recommended constructor, allowing guaranteed-to-work initialization.

The recommended way to call it is via the Configurator and with autoInit == 0, followed by calling initialize():

Hash config(<here state=”” non-default=”” config=”” parameters>=”“>); OutputChannel::Pointer output = Configurator<OutputChannel>::create(“OutputChannel”, cfg, 0); output->initialize();

Caveat: Make sure you do not pass a ‘bool’ instead of an ‘int’ as argument to create(..) since then the other constructor is chosen and the value of the ‘bool’ determines whether to validate cfg or not.

See

expectedParameters) and default-filled configuration

Parameters

config: Validated (

Parameters

autoInit: If set to 0 (strongly recommended), the constructor does not yet try to initiate the TCP server initialization and the initialize() method has to be called as “second constructor”. The advantage is that the initialization cannot fail on busy systems and one has control when the server is available for remote connections. If autoInit != 0, this constructor behaves as the other constructor and initialize() must not be called.

void initialize()¶

“Second constructor”, to be called after construction with second argument autoInit == 0.

Initializes the underlying Tcp server connection and makes it available for others.

May throw a karabo::util::NetworkException, e.g. if a non-zero port was defined in the input configuration and that is not available since used by something else.

karabo::util::Hash getInitialConfiguration() const¶

returns the initial readonly configuration parameters

Returns a Hash containing the initial information that should not be updated via ShowConnectionHandler and ShowStatisticsHandler. Currently only the address key is included.

std::string getInstanceIdName() const¶: Concatenation of instance id and name

bool hasRegisteredCopyInputChannel(const std::string &instanceId) const¶

Check whether an InputChannel with given id is registered to receive all data

i.e. an InputChannel with “dataDistribution == copy”

Return

bool whether InputChannel of specified type is connected

Parameters

instanceId: of InputChannel

bool hasRegisteredSharedInputChannel(const std::string &instanceId) const¶

Check whether an InputChannel with given id is registered to receive a share of the data

i.e. an InputChannel with “dataDistribution == shared”

Return

bool whether InputChannel of specified type is connected

Parameters

instanceId: of InputChannel

void write(const karabo::util::Hash &data, const Memory::MetaData &metaData, bool = false)¶

Writes a Hash containing data to the output channel. Sending to the network happens when update() is called.

Note: Any NDArray/ImageData inside data must stay untouched at least until update() or the callback of asyncUpdate(cb) has been called. See also the documentation of the safeNDArray flag of the update()/asyncUpdate() methods.

Parameters

data: input Hash object
metaData: a MetaData object containing meta data for this data token.

Thread safety: All the ‘write(..)’ methods, ‘[async]UpdateNoWait’ and ‘[async]SignalEndOfStream(..)’ must not be called concurrently.

void write(const karabo::util::Hash &data, bool = false)¶

Writes a Hash containing data to the output channel. Sending to the network happens when update() is called. Metadata is initialized to default values. Namely the sending devices device id and the output channel’s name are used as data source.

Note: Any NDArray/ImageData inside data must stay untouched at least until update() or the callback of asyncUpdate(cb) has been called. See also the documentation of the safeNDArray flag of the update()/asyncUpdate() methods.

Parameters

data: input Hash object

Thread safety: All the ‘write(..)’ methods, ‘[async]UpdateNoWait’ and ‘[async]SignalEndOfStream(..)’ must not be called concurrently.

void write(const karabo::util::Hash::Pointer &data, const Memory::MetaData &metaData)¶

Writes a Hash containing data to the output channel. Sending to the network happens when update() is called. Note: Any NDArray/ImageData inside data must stay untouched at least until update() or the callback of asyncUpdate(cb) has been called. See also the documentation of the safeNDArray flag of the update()/asyncUpdate() methods.

Parameters

data: shared pointer to input Hash object
metaData: a MetaData object containing meta data for this data token.

Thread safety: All the ‘write(..)’ methods, ‘[async]UpdateNoWait’ and ‘[async]SignalEndOfStream(..)’ must not be called concurrently.

void write(const karabo::util::Hash::Pointer &data)¶

Writes a Hash containing data to the output channel. Sending to the network happens asynchronously. Metadata is initialized to default values. Namely the sending devices device id and the output channel’s name are used as data source. Note: Any NDArray/ImageData inside data must stay untouched at least until update() or the callback of asyncUpdate(cb) has been called. See also the documentation of the safeNDArray flag of the update()/asyncUpdate() methods.

Parameters

data: shared pointer to input Hash object

Thread safety: All the ‘write(..)’ methods, ‘[async]UpdateNoWait’ and ‘[async]SignalEndOfStream(..)’ must not be called concurrently.

void update(bool safeNDArray = false)¶

Update the output channel, i.e. send all data over the wire that was previously written by calling write(…). This is a synchronous method, i.e. blocks until all data is actually sent (or dropped or queued).

Thread safety: All the ‘write(..)’ methods, ‘[async]UpdateNoWait’ and ‘[async]SignalEndOfStream(..)’ must not be called concurrently.

Parameters

safeNDArray: boolean to indicate whether all NDArrays inside the Hash passed to write(..) before are ‘safe’, i.e. their memory will not be referred to elsewhere after update is finished. Default is ‘false’, ‘true’ can avoid safety copies of NDArray content when data is queued or sent locally.

void asyncUpdate(bool safeNDArray = false, std::function<void()> &&writeDoneHandler = []() {})¶

Semi-asynchronously update the output channel, i.e. start asynchronous sending of data over the wire that was previously written to the output channel’s‘ buffer by calling write(…), but block as long as required to really start sending. The start of sending data is delayed

for any connected input channel that is currently not ready to receive more data, but is configured with “dataDistribution” as “copy” and with “onSlowness” as “wait”,
or if none of the connected input channels that are configured with “dataDistribution” as “shared” are currently ready to receive data and if this output channel is configured with “noInputShared” as “wait”.

Thread safety: All the ‘write(..)’ methods, ‘[async]UpdateNoWait’ and ‘[async]SignalEndOfStream(..)’ must not be called concurrently.

Parameters

safeNDArray: boolean to indicate whether all NDArrays inside the Hash passed to write(..) before are ‘safe’, i.e. their memory will not be referred to elsewhere before ‘readyHandler’ is called. Default is ‘false’, ‘true’ can avoid safety copies of NDArray content when data is queued or sent locally.
writeDoneHandler: callback when data (that is not queued) has been sent and thus even NDArray data inside it can be re-used again (except if safeNDArray was set to ‘true’ in which case its memory may still be used in a queue).

void asyncUpdateNoWait(std::function<void()> &&readyForNextHandlerstd::function<void()> &&writeDoneHandlerbool safeNDArray, )¶

Expert method

Asynchronously update the output channel, i.e. asynchronously send all data over the wire that was previously written by calling write(…) without any blocking.

This method must not be called again before either ‘readyForNextHandler’ or ‘writeDoneHandler’ have been called. If next data should be sent, but neither handler has been called yet, one has to block or skip the data. In the latter case, the wish of a connected input channel that is configured to make the output “wait” if not ready, is ignored (policy violation).

Both handlers have to be valid function pointers.

TODO: Provide a handler called when sending data is completed, including any queued data, and thus NDArray data can be re-used again even if safeNDArray=false (i.e. buffers could be re-used).

Parameters

readyForNextHandler: callback when asyncUpdateNoWait may be called again (this can only be delayed if any blocking input channel [“wait”] is connected)
writeDoneHandler: callback when sending is finished (as confirmed by Tcp) or stopped due to disconnection, or data is internally queued. So now all NDArray inside the Hash passed to write(..) before can be re-used again (except if safeNDArray was set to ‘true’ in which case its memory may still be used in a queue)
safeNDArray: boolean to indicate whether all NDArrays inside the Hash passed to write(..) before are ‘safe’, i.e. their memory will not be referred to elsewhere after update is finished. False triggers a data copy if data needs to be queued.

Thread safety: All the ‘write(..)’ methods, ‘[async]UpdateNoWait’ and ‘[async]SignalEndOfStream(..)’ must not be called concurrently.

void signalEndOfStream()¶

Synchronously send end-of-stream (EOS) notification to all connected input channels to indicate a logical break in the data stream.

Thread safety: All the ‘write(..)’ methods, ‘[async]UpdateNoWait’ and ‘[async]SignalEndOfStream(..)’ must not be called concurrently.

void asyncSignalEndOfStream(std::function<void()> &&readyHandler)¶

Asynchonously send end-of-stream (EOS) notification to all connected input channels to indicate a logical break in the data stream.

Thread safety: All the ‘write(..)’ methods, ‘update()’/’asyncUpdate(cb)’ and ‘signalEndOfStream()’/’asyncSignalEndOfStream(cb)’ must not be called concurrently.

Parameters

readyHandler: callback when notification has been sent or queued

void registerSharedInputSelector(SharedInputSelector &&selector)¶

Register handler that selects which of the connected input channels that have dataDistribution = “shared” is to be served.

The handler will be called during update(..)/asyncUpdateNoWait with the ids of the connected “shared” input channels (e.g. “deviceId:input”) as argument. The returned channel id will receive the data. If an empty string or an unknown id is returned, the data will be dropped.

Parameters

selector: takes vector<string> as argument and returns string

void disable()¶

Shut down all underlying connections, object will not be usable afterwards.

Needed if stray shared pointers may be kept somewhere.

Public Static Functions

void expectedParameters(karabo::util::Schema &expected)¶

Necessary method as part of the factory/configuration system

Parameters

expected: [out] Description of expected parameters for this object (Schema)

Private Functions

void eraseOldChannel(InputChannels &channelContainer, const std::string &instanceId, const karabo::net::Channel::Pointer &newChannel) const¶: Erase instance with ‘instanceId’ from ‘channelContainer’ if existing - if same as ‘newChannel’, do not close

void pushShareNext(const std::string &instanceId)¶

Helper to indicate that given shared input is ready to receive more data

Requires m_registeredInputsMutex to be locked

std::string popShareNext()¶

Helper to provide id of shared input that is ready to receive more data

Requires m_registeredInputsMutex to be locked

bool isShareNextEmpty() const¶

Helper to tell whether none of the shared inputs is ready to receive more data

Requires m_registeredInputsMutex to be locked

bool hasSharedInput(const std::string &instanceId)¶

Helper to query whether given shared input is ready to receive more data

Requires m_registeredInputsMutex to be locked

void eraseSharedInput(const std::string &instanceId)¶

Helper to indicate that given shared input is currently not ready to receive more data

Requires m_registeredInputsMutex to be locked

void pushCopyNext(const std::string &instanceId)¶

Helper to indicate that given copy input is ready to receive more data

Requires m_registeredInputsMutex to be locked

bool eraseCopyInput(const std::string &instanceId)¶

Erase instance from container of copy channels that are ready to receive data

Requires m_registeredInputsMutex to be locked

Return

whether instanceId could be removed (i.e. was actually ready to receive)

Parameters

instanceId:

bool updateChunkId()¶

helper to set new m_chunkId

Return: true if new m_chunkId is valid (i.e. not equal m_invalidChunkId)

void ensureValidChunkId(std::unique_lock<std::mutex> &lockOfRegisteredInputsMutex)¶

helper for asyncUpdate() to ensure that at the end m_chunkId is valid - may block a while

Parameters

lockOfRegisteredInputsMutex: a scoped_lock locking m_registeredInputsMutex (may be unlocked and locked again during execution)

void asyncPrepareCopy(unsigned int chunkId, std::vector<karabo::util::Hash *> &toSendImmediately, std::vector<karabo::util::Hash *> &toQueue, std::vector<karabo::util::Hash *> &toBlock)¶

Figure out how to treat copy inputs, return via appending to reference arguments

Requires m_registeredInputsMutex to be locked

void asyncPrepareDistribute(unsigned int chunkId, std::vector<karabo::util::Hash *> &toSendImmediately, std::vector<karabo::util::Hash *> &toQueue, std::vector<karabo::util::Hash *> &toBlock, bool &queue, bool &block)¶

Figure out how to treat shared inputs, return via (appending to) reference arguments

Requires m_registeredInputsMutex to be locked

bool asyncPrepareDistributeEos(unsigned int chunkId, std::vector<karabo::util::Hash *> &toSendImmediately, std::vector<karabo::util::Hash *> &toQueue, std::vector<karabo::util::Hash *> &toBlock)¶

Figure out how to send EndOfStream for shared outputs, return via reference arguments

Requires m_registeredInputsMutex to be locked

Return: whether to queue for shared queue

void asyncPrepareDistributeSelected(unsigned int chunkId, std::vector<karabo::util::Hash *> &toSendImmediately, std::vector<karabo::util::Hash *> &toQueue, std::vector<karabo::util::Hash *> &toBlock)¶

Figure out how to treat shared inputs if sharedInputSelector is registered

Requires m_registeredInputsMutex to be locked

void asyncPrepareDistributeLoadBal(unsigned int chunkId, std::vector<karabo::util::Hash *> &toSendImmediately, std::vector<karabo::util::Hash *> &toQueue, std::vector<karabo::util::Hash *> &toBlock, bool &queue, bool &block)¶

Figure out how to treat shared inputs when load-balancing

Requires m_registeredInputsMutex to be locked

void resetSendOngoing(const std::string &instanceId)¶: Helper that sets the sendOngoing flag to false for given instanceId

void asyncSendOne(unsigned int chunkId, InputChannelInfo &channelInfo, std::function<void()> &&doneHandler)¶

Helper to asynchronously send chunk data to channel in given channelInfo

Parameters

chunkId: The chunk to send
channelInfo: Container with info about channel to send to
doneHandler: Callback when sending done or failed

void awaitUpdateFuture(std::future<void> &fut, const char *which)¶

Helper for waiting for future that in case of long delay adds a thread to unblock

Throws TimeoutException if not unblocked after two minutes.

std::string debugId() const¶: Provide a string identifying this output channel (useful in DEBUG logging)

class Signal¶

Public Functions

template <typename… Args>
void setSignature()¶: Use like setSignature<int, util::Hash, std::string>() to ensure that any emitted signal has to take arguments of these three types in that order.

bool registerSlot(const std::string &slotInstanceId, const std::string &slotFunction)¶

Register a slot to receive an emitted signal

Return

bool whether freshly registered (false means: was already registered)

Parameters

slotInstanceId: id of the instance of the slot
slotFunction: name of the slot

bool unregisterSlot(const std::string &slotInstanceId, const std::string &slotFunction = "")¶

Undo registration of a slot

Return

bool whether slot registration could be undone, i.e. false if slot was not registered

Parameters

slotInstanceId: instance id of the slot to be removed
slotFunction: the slot - if empty string, remove all registered slots of slotInstanceId

void setTopic(const std::string &topic)¶

This function allows to use a specific topic to which all messages are emitted If the setter is not called, the topic of SignalSlotable will be used NOTE: The idea is to keep a door open for a later change where each emit will use a topic identical to the signal name. In that case the setter can just be removed.

Parameters

topic: The topic name

class SignalSlotable¶

#include <SignalSlotable.hh>

The SignalSlotable class. This class implements the so-called “Signal-Slot” design pattern orginally termed by the Qt-Gui framework. However, signals and slots are not restricted to a local application but can be connected and triggered across the network. This allows for programming with network components in the same intuitive (event-driven) way as Qt allows to do with its local components (e.g. widgets).

Moreover does this implementation (unlike Qt) not require any pre-processing. Another additional feature is the ability to setup new signals and/or slots at runtime.

Furthermore, this class implements functions for the common request/response patterns.

For a full documentation of the signal-slot component see the documentation in the software-guide.

Inherits from std::enable_shared_from_this< SignalSlotable >

Subclassed by karabo::core::BaseDevice, karabo::core::BaseFsm, karabo::core::DeviceServer, karabo::core::StartStopInterface

Public Types

typedef std::function<void()> AsyncErrorHandler¶

An AsyncErrorHandler takes no argument, but it will be called such that it can rethrow and then catch exceptions. The caught exception indicates the failure reason, e.g.:

void asyncErrorHandler () { try { throw; } catch (std::exception& e) { // or any other exception type - or several catch statements KARABO_LOG_FRAMEWORK_WARN << “Probem when trying to do something: ” << e.what(); } }

Public Functions

SignalSlotable()¶: This constructor does nothing. Call init() afterwards for setting up.

SignalSlotable(const std::string &instanceId, const karabo::net::Broker::Pointer &connection, const int heartbeatInterval = 30, const karabo::util::Hash &instanceInfo = karabo::util::Hash())¶

Creates a functional SignalSlotable object using an existing connection.

Don’t call init() afterwards.

Parameters

instanceId: The future instanceId of this object in the distributed system
connection: An existing broker connection
heartbeatInterval: The interval (in s) in which a heartbeat is emitted
instanceInfo: A hash containing any important additional information

SignalSlotable(const std::string &instanceId, const karabo::util::Hash &brokerConfiguration = karabo::util::Hash(), const int heartbeatInterval = 30, const karabo::util::Hash &instanceInfo = karabo::util::Hash())¶

Creates a function SignalSlotable object allowing to configure the broker connection.

Don’t call init() afterwards.

Parameters

instanceId: The future instanceId of this object in the distributed system
brokerConfiguration: A single keyed Hash where the key is the broker type and the Hash at that key is the configuration for the respective broker type (a given instanceId it will be replaced by the first constructor argument). Can be empty or can contain an empty Hash() at the single key, i.e. will be expanded from defaults.
heartbeatInterval: The interval (in s) in which a heartbeat is emitted
instanceInfo: A hash containing any important additional information

void init(const std::string &instanceId, const karabo::net::Broker::Pointer &connection, const int heartbeatInterval, const karabo::util::Hash &instanceInfo, bool consumeBroadcasts = true)¶

Initializes the SignalSlotable object (only use in conjunction with empty constructor).

Parameters

instanceId: The future instanceId of this object in the distributed system
connection: An existing broker connection
heartbeatInterval: The interval (in s) in which a heartbeat is emitted
instanceInfo: A hash containing any important additional information
consumeBroadcasts: if true (default), receive messages addressed to everybody (i.e. to ‘*’) on its own. If false, some other mechanism has to ensure to deliver these.

void start()¶

This function starts the communication.

After a call to this non-blocking function the object starts listening to messages. The uniqueness of the instanceId is validated (throws SignalSlotException if not unique) and if successful the object registers with a call to “slotInstanceNew” to the distributed system.

bool eraseTrackedInstance(const std::string &instanceId)¶

Erase instance from container of tracked instances

To be called if one is tracking instances and is sure that the given instance is not alive anymore (e.g. if another instance in the same process is dead as well). If erroneously called, the next arriving heartbeat of the instance will trigger an instanceNew event

Return

whether instanceId was tracked before

Parameters

instanceId: that shall be treated as not alive anymore

std::vector<string> getAvailableSignals(const std::string &instanceId, int timeout = 100)¶

This is a synchronous call with timeout in milliseconds return vector of device signals.

Return

vector of device’s signal names

Parameters

instanceId: of the device
timeout: in milliseconds

std::vector<string> getAvailableSlots(const std::string &instanceId, int timeout = 100)¶

This is a synchronous call with timeout in milliseconds return vector of device slots.

Return

vector of device’s slot names

Parameters

instanceId: of the device
timeout: in milliseconds

const std::string &getUserName() const¶

Retrieves currently logged in username (empty if not logged in)

Return: string username

const std::string &getInstanceId() const¶

Access to the identification of the current instance using signals and slots

Return: instanceId

void updateInstanceInfo(const karabo::util::Hash &update, bool remove = false)¶

Update and publish the instanceInfo

Parameters

update: a Hash containing new or updated keys - or keys to remove
remove: if false (default), merge ‘update’ to existing instance info, otherwise subtract it

const SignalSlotable::SlotInstancePointer &getSenderInfo(const std::string &slotFunction)¶

This function must only be called within a slotFunctions body. It returns the current object handling the callback which provides more information on the sender.

Return

instance of a Slot object (handler object for this callback)

Parameters

slotFunction: The string-ified name of the slotFunction you are currently in

bool connect(const std::string &signalInstanceId, const std::string &signalSignature, const std::string &slotInstanceId, const std::string &slotSignature)¶

This function tries to establish synchronously a connection between a signal and a slot, identified both by their respective instance IDs and signatures. Moreover, this SignalSlotable obeys (throughout its full lifetime or until “disconnect” is called with the same arguments) the responsibility to keep this connection alive, i.e. to reconnect if either signal or slot instance come back after they have shutdown or if they come up the first time.

Return

whether connection is already successfully established

Parameters

signalInstanceId: is the instance ID of the signal (if empty use this instance)
signalSignature: is the signature of the signal
slotInstanceId: is the instance ID of the slot (if empty use this instance)
slotSignature: is the signature of the slot

bool connect(const std::string &signal, const std::string &slot)¶

This function tries to establish a connection between a signal and a slot as “connect” with four arguments does, so see there for more details. If signal or slot instance IDs are not specified, they are interpreted as local and automatically assigned a “self” instanceId

Return

whether connection is already succesfully established

Parameters

signal: <signalInstanceId>:<signalSignature>
slot: <slotInstanceId>:<slotSignature>

void asyncConnect(const std::string &signalInstanceId, const std::string &signalSignature, const std::string &slotInstanceId, const std::string &slotSignature, const std::function<void()> &successHandler = std::function<void()>()const AsyncErrorHandler &failureHandler = AsyncErrorHandler(), int timeout = 0, )¶

This function tries to establish asynchronously a connection between a signal and a slot, identified both by their respective instance IDs and signatures. Moreover, this SignalSlotable obeys (throughout its full lifetime or until “disconnect” is called with the same arguments) the responsibility to keep this connection alive, i.e. to reconnect if either signal or slot instance come back after they have shutdown or if they come up the first time.

Parameters

signalInstanceId: is the instance ID of the signal (if empty use this instance)
signalSignature: is the signature of the signal
slotInstanceId: is the instance ID of the slot (if empty use this instance)
slotSignature: is the signature of the slot
successHandler: is called when connection is established (maybe be empty [=default])
failureHandler: is called when connection could not be established, in the same way as an Requestor::AsyncErrorHandler - if Signal or Slot do not exist, the exception is a SignalSlotException
timeout: in milliseconds for internal async requests - non-positive (default) means the very long default timeout

void asyncConnect(const std::vector<SignalSlotConnection> &signalSlotConnections, const std::function<void()> &successHandler = std::function<void()>()const AsyncErrorHandler &failureHandler = AsyncErrorHandler(), int timeout = 0, )¶

This function tries to establish asynchronously a connection between several signals and slots.

One of the two handlers will be called exactly once. The failureHandler will be called if any signal slot connection failed, no matter whether other connections succeeded or not.

Parameters

signalSlotConnections: e.g. vector<SignalSlotConnection>{SignalSlotConnection(“sigInst”, “signal”, “slotInst”, “slot”), …}
successHandler: is called when all connections are established (maybe be empty [=default])
failureHandler: is called when any of the connections could not be established, no matter whether the others failed or not, in the same way as a Requestor::AsyncErrorHandler.
timeout: in milliseconds for internal async requests - non-positive (default) means the very long default timeout

bool disconnect(const std::string &signalInstanceId, const std::string &signalFunction, const std::string &slotInstanceId, const std::string &slotFunction)¶

Disconnects a slot from a signal, identified both by their respective instance IDs and signatures. In case the connection was established by this instance, also erase it from the list of connections that have to re-established in case signal or slot instances come back after a shutdown.

Return

whether connection is successfully stopped, e.g. false if there was no such connection or if remote signal instance ID did not confirm in time

Parameters

signalInstanceId: is the instance ID of the signal (if empty use this instance)
signalSignature: is the signature of the signal
slotInstanceId: is the instance ID of the slot (if empty use this instance)
slotSignature: is the signature of the slot

void asyncDisconnect(const std::string &signalInstanceId, const std::string &signalFunction, const std::string &slotInstanceId, const std::string &slotFunction, const std::function<void()> &successHandler = std::function<void()>()const AsyncErrorHandler &failureHandler = AsyncErrorHandler(), int timeout = 0, )¶

This function tries to disconnect a previously established connection between a signal and a slot. These two are identified both by their respective instance IDs and signatures. In case the connection was established by this instance, the function also erases it from the list of connections that have to be re-established in case signal or slot instances come back after a shutdown.

Parameters

signalInstanceId: is the instance ID of the signal (if empty use this instance)
signalSignature: is the signature of the signal
slotInstanceId: is the instance ID of the slot (if empty use this instance)
slotSignature: is the signature of the slot
successHandler: is called when connection is successfully stopped (maybe be empty [=default])
failureHandler: is called when the disconnection failed (maybe be empty [=default])
timeout: in milliseconds for internal async requests - non-positive (default) means the very long default timeout

template <typename… Args>

void emit(const std::string &signalFunction, const Args&... args) const¶

Emits a signal, i.e. publishes the given payload Emitting a signal is a fire-and-forget activity. The function returns immediately.

Parameters

signalFunction: The name of the previously registered signal
args...: A variadic number of arguments to be published

template <typename… Args>

void call(const std::string &instanceId, const std::string &functionName, const Args&... args) const¶

Calls a (remote) function. Calling a remote function is a fire-and-forget activity. The function returns immediately after sending the message.

Parameters

instanceId: Instance to be called
functionName: Function on instance to be called (must be a registered slot)
args: Arguments with which to call the slot

template <typename… Args>

void reply(const Args&... args)¶

Place the reply of a slot call

To be used inside a method registered as a slot. The reply is not directly sent, but it is registered to be sent once all methods registered to the slot (usually only one) have finished execution. So if called several times in a slot, the last call defines the actual reply.

If this method is not called inside a slot, an “empty” reply will be send without arguments. But note that Device::updateState(const State s, …) implicitly calls reply(s.name()).

See about AsyncReply to avoid blocking the thread in case reply values are known only later, e.g. after some IO operations.

Parameters

args: 0 to 4 objects of the types known to serialisation, e.g. float, vector<long long>, Hash,…

void registerSlot(const std::function<void()> &slotconst std::string &funcName, )¶: Register a new slot function for a slot. A new slot is generated if so necessary. It is checked that the signature of the new slot is the same as an already registered one.

InputChannel::Pointer createInputChannel(const std::string &channelName, const karabo::util::Hash &config, const DataHandler &onDataAvailableHandler = DataHandler(), const InputHandler &onInputAvailableHandler = InputHandler(), const InputHandler &onEndOfStreamEventHandler = InputHandler(), const InputChannel::ConnectionTracker &connectTracker = InputChannel::ConnectionTracker())¶

Create and register an InputChannel together with handlers

Return

the created InputChannel - better do not store it anywhere, it can be received via getInputChannel(channelName)

Parameters

channelName: name of the channel, e.g. its path in the schema
config: is a Hash with a Hash at ‘channelName’ which will be passed to InputChannel::create
onDataAvailableHandler: is a DataHandler called for each data item coming through the pipeline
onInputAvailableHandler: is an InputHandler called when new data arrives - user has to loop over all items
onEndOfStreamEventHandler: is an InputHandler called when EOS is received
connectTracker: will be called whenever the connection status of the created channel changes

bool removeInputChannel(const std::string &channelName)¶

Remove the InputChannel created via createInputChannel

Return

true if such a channel existed and could be removed

Parameters

channelName: identifies the channel (first argument that was given to createInputChannel)

OutputChannel::Pointer createOutputChannel(const std::string &channelName, const karabo::util::Hash &config, const OutputHandler &onOutputPossibleHandler = OutputHandler())¶

Create an OutputChannel under the given name

If there is already one for than name, that one (and thus all other copies of its shared_ptr) will be disabled to disconnect any connection.

Return

pointer to created channel - do not store anywhere! If needed, retrieve again via getOutputChannel(channelName).

Parameters

channelName: the name for the channel
config: must have a Hash at key channelName - that is passed (after removeal of the “schema” key) to Configurator<OutputChannel>::create
onOutputPossibleHandler: ?

bool removeOutputChannel(const std::string &channelName)¶

Remove the OutputChannel created via createOutputChannel

Before removal, it (and thus all other copies of its shared_ptr) will be disabled to disconnect any connection.

Return

true if such a channel existed and could be removed

Parameters

channelName: identifies the channel (first argument that was given to createOutputChannel)

OutputChannel::Pointer getOutputChannel(const std::string &name)¶

Access pointer to OutputChannel with given name. Throws ParameterException if no such output channel.

Return

OutpuChannel::Pointer

Parameters

name: of output channel (e.g. path in expectedParameters)

OutputChannel::Pointer getOutputChannelNoThrow(const std::string &name)¶

Access pointer to OutputChannel with given name.

Return

OutputChannel::Pointer - empty if no channel of that name

Parameters

name: of output channel (e.g. path in expectedParameters)

InputChannel::Pointer getInputChannel(const std::string &name)¶

Access pointer to InputChannel with given name. Throws ParameterException if no such input channel.

Return: InputChannel::Pointer

InputChannel::Pointer getInputChannelNoThrow(const std::string &name)¶

Access pointer to InputChannel with given name.

Return

InputChannel::Pointer - empty if no channel of that name

Parameters

name: of input channel (e.g. path in expectedParameters)

void connectInputChannel(const InputChannel::Pointer &channel, int trails = 8)¶

Deprecated, use asyncConnectInputChannel!

Connects an input channel to those as defined on the input channel’s configuration. The function is asynchronous, but gives no feedback about success or failure.

void asyncConnectInputChannel(const InputChannel::Pointer &channel, const std::function<void(bool)> &handler, const std::vector<std::string> &outputChannelsToIgnore = std::vector<std::string>(), )¶

Connect input channel to output channels defined in its configuration.

Proper asynchronous implementation with feedback handler

Parameters

channel: pointer to InputChannel
handler: to report success or failure. In the latter case the argument is false and more information about the failure can be retrieved via try { throw; } catch (const std::exception&e) { const std::string reason(e.what());} in the same way as in SignalSlotable::AsyncErrorHandler
outputChannelsToIgnore: outputChannels that shall not be connected, e.g. because they are already connected (defaults to empty vector)

void connectInputChannels(const boost::system::error_code &e)¶

Trigger connection of all not connected input channel connections

Re-triggers itself regularly via internal m_channelConnectTimer

Parameters

e: do nothing if evaluates to true

Protected Functions

string fetchInstanceId(const std::string &signalOrSlotId) const¶

Parses out the instanceId part of signalId or slotId

Return

A string representing the instanceId

Parameters

signalOrSlotId:

void registerBroadcastHandler(std::function<void(const karabo::util::Hash::Pointer &header, const karabo::util::Hash::Pointer &body)> handler)¶

Register a handler to be called for every received message that is addressed to everybody. NOTE: This is not thread safe - call before SignalSlotable::start starts receiving messages.

Parameters

handler: with header and body (as Hash::Pointer) of the message

Private Functions

template <typename… Args>

SignalSlotable::SignalInstancePointer addSignalIfNew(const std::string &signalFunction, int priority = KARABO_SYS_PRIO, int messageTimeToLive = KARABO_SYS_TTL)¶

Helper for register(System)Signal: If signalFunction is not yet known, creates a signal corresponding to the template argument signature and adds it to the internal container. Otherwise an empty pointer is returned.

Return

pointer to new Signal or empty pointer

Parameters

signalFunction:
priority: is passed further to the Signal
messageTimeToLive: is passed further to the Signal

void ensureInstanceIdIsValid(const std::string &instanceId)¶: If instanceId has invalid characters, throws SignalSlotException.

void ensureInstanceIdIsUnique(const std::string &instanceId)¶: If instanceId not unique in system, throws SignalSlotException.

std::tuple<karabo::util::Hash::Pointer, std::string, bool> registerAsyncReply()¶

Internal method to provide info for AsyncReply object

Return: tuple of slot header, slot name and whether it is a global slot call

void reconnectSignals(const std::string &newInstanceId)¶: Calls connect for all signal-slot connections that involve ‘newInstanceId’ (be it on signal or slot side) and for which this instance is responsible, i.e. its “connect” has been called for this connection before (with or without immediate success). Calling “disconnect” stops this responsibility.

void registerForShortcutMessaging()¶: Register myself for short-cut messaging (i.e. bypass broker if in same process). Must not be called before instance ID is checked to be unique in overall system.

void deregisterFromShortcutMessaging()¶: Deregister myself from short-cut messaging.

void registerNewSlot(const std::string &funcName, SlotInstancePointer instance)¶: Register a new slot instance under name funcName. This will raise an error if the slot already exists.

void slotConnectToSignal(const std::string &signalFunction, const std::string &slotInstanceId, const std::string &slotFunction)¶: Register signal-slot connection on signal side.

void slotSubscribeRemoteSignal(const std::string &signalInstanceId, const std::string &signalFunction)¶: Slot to subscribe to remote signal.

void slotUnsubscribeRemoteSignal(const std::string &signalInstanceId, const std::string &signalFunction)¶: Slot to un-subscribe from remote signal.

bool instanceHasSlot(const std::string &slotInstanceId, const std::string &unmangledSlotFunction)¶: True if instance with ID ‘slotInstanceId’ has slot ‘slotFunction’. Internally uses “slotHasSlot” for remote instances, but shortcuts if ID is the own one. Always true if ‘slotInstanceId == “*”’ (i.e. global slot).

void slotHasSlot(const std::string &unmangledSlotFunction)¶: Slot to tell whether instance has a slot of given name.

void handleInputConnected(bool success, const std::string &channel, const std::shared_ptr<std::mutex> &mut, const std::shared_ptr<std::vector<karabo::net::AsyncStatus>> &status, size_t i, size_t numOutputsToIgnore)¶: helper for connectInputChannels()

bool tryToUnregisterSlot(const std::string &signalFunction, const std::string &slotInstanceId, const std::string &slotFunction)¶

Try to undo registration of a slot “slotInstanceId.slotFunction”. Thread-safe, locks m_signalSlotInstancesMutex.

Return

bool true if signal existed and given slot was registered before

Parameters

signalFunction: name of local signal
slotInstanceId: instance id that carries the slot
slotFunction: the slot - if empty, all registered slots of slotInstanceId

void addReceiveAsyncErrorHandles(const std::string &replyId, const std::shared_ptr<boost::asio::steady_timer> &timer, const AsyncErrorHandler &errorHandler)¶: For the given replyId of a ‘request.receiveAsync’, register error handling, i.e. the timer for timeout and the handler for remote exceptions.

Private Static Functions

void callErrorHandler(const AsyncErrorHandler &handler, const std::string &message)¶

Helper that calls ‘handler’ such that it can do

try { throw; } catch (const SignalSlotException &e) { <action>}

Parameters

message: text given to the SignalSlotException

class AsyncReply¶

#include <SignalSlotable.hh>

A functor to place an asynchronous reply during slot execution.

Create only inside a slot call of a SignalSlotable
Can be copied around as wished
Call either the operator or the error(..) method exactly once for one of the copies.
Call these methods from another context/thread, i.e. between creation and use of its methods you have to leave the thread at least once)
Must not be used once the SignalSlotable object that created it is (being) destructed (e.g. protect by bind_weak to member functions of the SignalSlotable)

Public Functions

AsyncReply(SignalSlotable *signalSlotable)¶

Construct functor for an asynchronous reply. Create only within a slot call of a SignalSlotable

Parameters

signalSlotable: pointer to the SignalSlotable whose slot is currently executed (usually: this)

template <typename… Args>

void operator()(const Args&... args) const¶

Place the reply - almost like using SignalSlotable::reply in the synchronous case. The difference is that here the reply is immediately sent and cannot be overwritten by a following call.

Parameters

args: 0-4 objects of the types known to serialisation, e.g. float, vector<long long>, Hash,…

void error(const std::string &message, const std::string &details = std::string()) const¶

If a proper reply cannot be placed, please use this to reply an error

Parameters

message: is the short text for the RemoteException
details: further details, usually an exception trace (e.g. util::Exception::detailedMsg()), default is empty for backward compatibility reasons

class Requestor¶

Private Functions

std::pair<karabo::util::Hash::Pointer, karabo::util::Hash::Pointer> receiveResponseHashes()¶

Receives the reply for the current request, returning shared pointers to the reply’s header and body hashes.

Return: A pair with a shared pointer to the header hash of the reply in the first position and a shared pointer to the body in the second.

void registerErrorHandler(const AsyncErrorHandler &errorHandler)¶: Register handler for errors in async requests, e.g. timeout or remote exception.

void getSignalInstanceId(const karabo::util::Hash::Pointer &header, std::string &result)¶

Extracts the value of the SignalInstanceId path in a response header hash.

Parameters

header: response header hash from where the value will be extracted
result: the string that will be assigned the value of the SignalInstanceId path

struct SignalSlotConnection¶: #include <SignalSlotable.hh>
A structure to keep information of a signal-slot connection.

class Slot¶

Subclassed by karabo::xms::SlotN< Ret, Args >

Public Functions

karabo::util::Hash::Pointer getHeaderOfSender() const¶: Return message header that triggered calling this slot Valid while callRegisteredSlotFunctions is processed.

class SLOT_ELEMENT¶: Inherits from karabo::xms::SlotElementBase< SLOT_ELEMENT >

template <class A1>
class SLOT_ELEMENT1¶: Inherits from karabo::xms::SlotElementBase< SLOT_ELEMENT1< A1 > >

template <class Derived>

class SlotElementBase¶

Inherits from karabo::util::GenericElement< Derived >

Public Functions

Derived &allowedStates(const std::vector<karabo::util::State> &value)¶

The allowedStates method serves for setting up allowed states for the element

Return

reference to the Element (to allow method’s chaining)

Parameters

states: A string describing list of possible states.
sep: A separator symbol used for parsing previous argument for list of states

Derived &key(const std::string &name)¶

The key method serves for setting up a unique name for the element. Example:

SOME_ELEMENT(expected)
        .key("type")
        ...
        .commit();

Return

reference to the Element (to allow method’s chaining)

Parameters

name: Unique name for the key - can be a nested path if all but its last sub-key are added as node elements before. Must not be an empty string.

template <typename Ret, typename… Args>

class SlotN¶

Inherits from karabo::xms::Slot

Public Functions

virtual void doCallRegisteredSlotFunctions(const karabo::util::Hash &body)¶

To be called under protection of m_registeredSlotFunctionsMutex

Parameters

body: a Hash with up to four keys “a1” to “a4” with the expected types behind

class Statics¶

#include <Statics.hh>

The Statics class.

Public Functions

Statics()¶: Default constructor.

virtual ~Statics()¶: Destructor.

The karabo::util Namespace¶

namespace karabo::util¶

Namespace for package packageName

Namespace for package util

Namespace for package devices

Typedefs

typedef AlarmConditionElement ALARM_ELEMENT¶

typedef ByteArrayElement BYTEARRAY_ELEMENT¶

typedef ChoiceElement CHOICE_ELEMENT¶

using karabo::util::InfluxResultSet = typedef std::pair< std::vector<std::string>, std::vector<std::vector<boost::optional<std::string> >> >

using karabo::util::JsonType = typedef std::optional<nlohmann::json::value_t>

typedef util::ListElement LIST_ELEMENT¶

typedef NDArrayElement NDARRAY_ELEMENT¶

typedef NodeElement NODE_ELEMENT¶

typedef OverwriteElement OVERWRITE_ELEMENT¶

typedef PathElement PATH_ELEMENT¶

typedef SimpleElement<bool> BOOL_ELEMENT¶

typedef SimpleElement<signed char> INT8_ELEMENT¶

typedef SimpleElement<char> CHAR_ELEMENT¶

typedef SimpleElement<signed short> INT16_ELEMENT¶

typedef SimpleElement<int> INT32_ELEMENT¶

typedef SimpleElement<long long> INT64_ELEMENT¶

typedef SimpleElement<unsigned char> UINT8_ELEMENT¶

typedef SimpleElement<unsigned short> UINT16_ELEMENT¶

typedef SimpleElement<unsigned int> UINT32_ELEMENT¶

typedef SimpleElement<unsigned long long> UINT64_ELEMENT¶

typedef SimpleElement<float> FLOAT_ELEMENT¶

typedef SimpleElement<double> DOUBLE_ELEMENT¶

typedef SimpleElement<std::string> STRING_ELEMENT¶

typedef StateElement STATE_ELEMENT¶

typedef util::TableElement TABLE_ELEMENT¶

typedef unsigned long long TimeValue¶

typedef std::pair<std::shared_ptr<char>, size_t> ByteArray¶

typedef MetricPrefix::MetricPrefixType MetricPrefixType¶

typedef Unit::UnitType UnitType¶

typedef VectorElement<bool> VECTOR_BOOL_ELEMENT¶

typedef VectorElement<signed char> VECTOR_INT8_ELEMENT¶

typedef VectorElement<char> VECTOR_CHAR_ELEMENT¶

typedef VectorElement<signed short> VECTOR_INT16_ELEMENT¶

typedef VectorElement<int> VECTOR_INT32_ELEMENT¶

typedef VectorElement<long long> VECTOR_INT64_ELEMENT¶

typedef VectorElement<unsigned char> VECTOR_UINT8_ELEMENT¶

typedef VectorElement<unsigned short> VECTOR_UINT16_ELEMENT¶

typedef VectorElement<unsigned int> VECTOR_UINT32_ELEMENT¶

typedef VectorElement<unsigned long long> VECTOR_UINT64_ELEMENT¶

typedef VectorElement<float> VECTOR_FLOAT_ELEMENT¶

typedef VectorElement<double> VECTOR_DOUBLE_ELEMENT¶

typedef VectorElement<std::string> VECTOR_STRING_ELEMENT¶

Enums

enum AccessType¶

Values:

INIT = 1 << 0¶

READ = 1 << 1¶

WRITE = 1 << 2¶

enum DaqDataType¶

Values:

PULSE = 0¶

TRAIN = 1¶

PULSEMASTER = 10¶

TRAINMASTER = 11¶

enum DAQPolicy¶

An enum specifying the DAQ storage policy

Values:

UNSPECIFIED = -1¶

OMIT = 0¶

SAVE = 1¶

enum TIME_UNITS¶

Values:

ATTOSEC = 0¶

FEMTOSEC = 3 + ATTOSEC¶

PICOSEC = 3 + FEMTOSEC¶

NANOSEC = 3 + PICOSEC¶

MICROSEC = 3 + NANOSEC¶

MILLISEC = 3 + MICROSEC¶

ONESECOND = 3 + MILLISEC¶

NOFRACTION = -1¶

SECOND = 1ULL¶

MINUTE = 60ULL * SECOND¶

HOUR = 60ULL * MINUTE¶

DAY = 24ULL * HOUR¶

Functions

template <class T>
void addPointerToHash(Hash &hash, const std::string &path, T *const &value, const Dims &dims, const char separator = Hash::k_defaultSep)¶

template <class T>
void getPointerFromHash(const Hash &hash, const std::string &path, T *&value, Dims &dims, const char separator = util::Hash::k_defaultSep)¶

void setDims(Hash &hash, const std::string &path, const Dims &dims, const char separator = Hash::k_defaultSep)¶

std::string base64Encode(const unsigned char *bytes_to_encode, const size_t len)¶

Base64 encode bytes

Return

Parameters

bytes_to_encode:
len:

void base64Decode(const std::string &in, std::vector<unsigned char> &out)¶

Base64 decode a string

Parameters

in:
out: vector of bytes

uint16_t byteSwap16(uint16_t in)¶

uint32_t byteSwap32(uint32_t in)¶

uint64_t byteSwap64(uint64_t in)¶

util::Epochstamp stringDoubleToEpochstamp(const std::string &timestampAsDouble)¶: Convert an std::string that represents a double of the seconds since Unix epoch to an Epochstamp

void getLeaves(const util::Hash &configuration, const util::Schema &schema, std::vector<std::string> &result, const char separator)¶

void getLeaves_r(const util::Hash &hash, const util::Schema &schema, std::vector<std::string> &result, std::string prefix, const char separator, const bool fullPaths)¶

void parseSingleJsonResult(const nl::json &respObj, InfluxResultSet &influxResult, const std::string &columnPrefixToRemove)¶

void jsonResultsToInfluxResultSet(const std::string &jsonResult, InfluxResultSet &influxResult, const std::string &columnPrefixToRemove)¶

Utility function to convert a string into an InfluxResultSet

One or multiple concatenated JSON objects containing the results of an InfluxDB query are decoded and filled into a InfluxResultSet object.

Parameters

jsonResult: : the string containing the JSON object(s)
influxResult: : the result
columnPrefixToRemove: : remove this prefix from the column names. InfluxQL selector functions (e.g. SAMPLE) are prepended to the column name. Use this argument to remove said prefixes.

Exceptions

karabo::util::NotSupportedException: in case the column mismatch nlohmann::json exceptions in case of malformatted JSON objects.

boost::optional<std::string> jsonValueAsString(nl::json value)¶

std::string toInfluxDurationUnit(const TIME_UNITS &karaboDurationUnit)¶

std::string epochAsMicrosecString(const Epochstamp &ep)¶

boost::optional<std::string> jsonValueAsString(nlohmann::json value)¶

Utility function to convert a json object.

Return

a boost::optional<std::string> a null boost::optional<std::string> matches a null JSON value

Parameters

value:

bool operator==(const Dims &lhs, const Dims &rhs)¶

std::ostream &operator<<(std::ostream &output, const Epochstamp &stamp)¶

bool operator==(const Epochstamp &lhs, const Epochstamp &rhs)¶

Relational operations between timestamps

Return

bool

Parameters

other: Epochstamp object

bool operator!=(const Epochstamp &lhs, const Epochstamp &rhs)¶

bool operator>(const Epochstamp &lhs, const Epochstamp &rhs)¶

bool operator>=(const Epochstamp &lhs, const Epochstamp &rhs)¶

bool operator<(const Epochstamp &lhs, const Epochstamp &rhs)¶

bool operator<=(const Epochstamp &lhs, const Epochstamp &rhs)¶

ostream &operator<<(ostream &os, const Exception &exception)¶: Automatic output using the << operator

static std::string concat(const std::vector<std::string> &vec, size_t len, const std::string &sep)¶

std::ostream &operator<<(std::ostream &os, const Hash &hash)¶

Serialize a hash to standard std::ostream object

Parameters

visitor:

bool similar(const Hash &left, const Hash &right)¶

bool similar(const std::vector<Hash> &left, const std::vector<Hash> &right)¶

bool similar(const Hash::Node &left, const Hash::Node &right)¶

size_t counter(const Hash &hash)¶

size_t counter(const Hash &hash, Types::ReferenceType type)¶

size_t counter(const Hash::Node &element)¶

void processJson(const nlohmann::json &j, Hash &result)¶

void processJsonObject(nlohmann::json::const_iterator &it, Hash &result)¶

void processJsonArray(nlohmann::json::const_iterator &it, Hash &result)¶

void processJsonValue(nlohmann::json::const_iterator &it, Hash &result)¶

JsonType getArrayType(const nlohmann::json &j)¶

karabo::util::Hash jsonToHash(const std::string &j)¶

Converts a JSON string representation into a Hash object.

This function parses a JSON string and constructs a corresponding Hash object representing the JSON structure. The JSON string is expected to follow the JSON standard format.

JSON Arrays of Mixed types are unsupported.

JSON types are mapped to C++ types as below:

JSON Integer -> long long
JSON Decimal -> double
JSON empty array -> empty std::vector<std::string>

Return

A Hash object representing the parsed JSON structure.

Parameters

jsonString: A string containing the JSON representation to be converted.

Exceptions

KARABO_PARAMETER_EXCEPTION: if the provided JSON string is invalid or cannot be parsed into a Hash object.

Hash generateAutoStartHash(const Hash &initHash)¶

Generates an auto-start configuration Hash based on the provided initialization Hash.

This function takes an initialization Hash representing the initial configuration of components and constructs an auto-start configuration Hash based on it.

The initialization Hash is expected to have been generated from the JSON for the init string used to autostart devices on a karabo cpp server.

An example conversion should look like this:

initHash: ‘data_logger_manager_1’ + ‘classId’ => DataLoggerManager STRING ‘serverList’ => karabo/dataLogger STRING ‘schema_printer1’ + ‘classId’ => SchemaPrinter STRING

Above transforms to autoStart hash: ‘autoStart’ @ [0] ‘DataLoggerManager’ + ‘deviceId’ => data_logger_manager_1 STRING ‘serverList’ => karabo/dataLogger STRING [1] ‘SchemaPrinter’ + ‘deviceId’ => schema_printer1 STRING

Return

A Hash object representing the auto-start configuration based on the provided initialization Hash.

Parameters

initHash: The initialization Hash containing the initial configuration of components.

template <typename Ret, typename… Args, typename Obj>

std::function<Ret(Args...)> karabo::util::exec_weak_impl(Ret(Obj::*)(Args...) const f, const Obj * o)

Provides a wrapper with the same signature as f, but securing shared ownership of an object of type Obj before execution of f. Class Obj needs to derive somewhere in its inheritance tree from enable_shared_from_this();

Return

a wrapped version of f.

Parameters

f: a const member function, can have any argument types and any return value
o: a pointer to an object that has a member function f

template <typename Ret, typename… Args, typename Obj>

std::function<Ret(Args...)> karabo::util::exec_weak_impl(Ret(Obj::*)(Args...) f, Obj * o)

Provides a wrapper with the same signature as f, but securing shared ownership of an object of type Obj before execution of f. Class Obj needs to derive somewhere in its inheritance tree from enable_shared_from_this();

Return

a wrapped version of f.

Parameters

f: a non-const member function, can have any argument types and any return value
o: a pointer to an object that has a member function f

template <typename F, typename Obj, typename… P>

auto bind_weak(const F &f, Obj *const o, const P... p)¶

Weakly binds member function f to an object of class Obj, but assures shared ownership of the object while f is executed. This means that during the lifetime of calling f, the object cannot be destroyed, but destruction is not blocked if f is not being executed but only bound. Class Obj needs to derive from std::enable_shared_from_this and the object pointer o has to be held by a shared_ptr. This means that you cannot use bind_weak within the constructor of Obj nor for objects constructed on the stack. Note that f may have any default constructable return type: If the bound functor will be called when the object is already destroyed, the functor returns a default constructed object of the return type.

Below is an example of how to bind to a boost::asio interface.

void Device::executeStepFunction(int arg, const boost::system::error_code& error) { …. m_timer.async_wait(bind_weak(&Device::executeStepFunction, this, arg + 1, _1)); …. }

Return

: bound functor, compatible with boost bind.

Parameters

f: function to bind, give as &Foo::bar
o: pointer to object to bind to
p: parameters as one would give to std::bind. Placeholders are fully supported.

template <typename F, typename Tuple>

void call(F f, Tuple &&t)¶

Call a function f with arguments unpacked from a std::tuple

Parameters

f:
t:

template <>
template<> OverwriteElement &setNewDefaultValue<karabo::util::State>(const karabo::util::State &value)¶

template <>
template<> OverwriteElement &setNewDefaultValue<karabo::util::AlarmCondition>(const karabo::util::AlarmCondition &value)¶

template <class… Ts>
void unpack(const Hash &hash, Ts&... args)¶: Unpack the hash (typically coming from the network) into the parameters given by reference.

template <typename… Args>

auto unpack(const karabo::util::Hash &h)¶

Unpack parameters into a tuple holding only references

Return

std::tuple<Args&…>

Parameters

h: Hash with keys a1, a2, etc. encoding function arguments

template <class… Ts>

void pack(Hash &hash, const Ts&... args)¶

Pack the parameters into a hash for transport over the network.

Parameters

hash: Will be filled with keys a1, a2, etc. and associated values
args: Any type and number of arguments to associated to hash keys

ostream &operator<<(ostream &os, const Schema &schema)¶

Default output using help function

Return

Parameters

key:

bool similar(const Schema &left, const Schema &right)¶

AccessType operator|(AccessType __a, AccessType __b)¶

AccessType &operator|=(AccessType &__a, AccessType __b)¶

AccessType operator&(AccessType __a, AccessType __b)¶

AccessType &operator&=(AccessType &__a, AccessType __b)¶

std::ostream &operator<<(std::ostream &os, const StackTrace &trace)¶

std::ostream &operator<<(std::ostream &out, const State &state)¶

static std::string typeNameFromTypeInfo(const std::type_info &typeInf)¶

std::string createCastFailureMessage(const std::string &key, const std::type_info &src, const std::type_info &tgt)¶

Create a cast failure message for a Hash key when trying to cast to a different value type

Return

the failure message

Parameters

key: the message pertains to
src: typeinfo of source type, i.e. type of the value in the Hash
tgt: typeinfo of target type, i.e. type to which the cast failed

std::string createCastFailureMessage(const std::string &key, const Types::ReferenceType &src, const Types::ReferenceType &tgt)¶

std::string createTypeMismatchMessage(const std::string &key, const std::type_info &srcType, const std::type_info &tgtType)¶

Creates a type mismatch message for an attempt to get a Hash node value with a type different from the current type of the node.

Return

std::string the failure message.

Parameters

key: the key of the node whose value has been requested.
srcType: the current type of the node whose value should have been retrieved.
tgtType: the expected type of the node whose value should have been retrieved

int getAndCropIndex(std::string &str)¶

std::vector<std::string> split(std::string &str, const char *dl = " ", std::size_t maxsplit = 0)¶

Split input string using delimiter (default = space) into vector of strings.

Return

vector of splitted parts of input string

Parameters

str: input string to split
dl: delimiter character used for splitting (default = ” “)
maxsplit: max size of resulting vector … (default = 0: unlimited)

std::string toString(const karabo::util::NDArray &value)¶

An NDArray is output in a flattened representation using StringTools::toString(const std::pair<const T*, size_t>&)

Return

Parameters

value:

std::string toString(const karabo::util::ByteArray &value, size_t maxBytesShown = 0)¶

Byte array is output as a hexadecimal string (short)

Return

string representation of ByteArray

Parameters

value: ByteArray object
maxBytesShown: max. number of bytes to be presented

std::string &toLower(std::string &str)¶

std::string &toUpper(std::string &str)¶

std::string &trim(std::string &str)¶

template <class T>

std::string toString(const T &value)¶

Return a string representation of a value of type T. Overloads for common value types exist. In general std::ostream is used for output so it will work for any type supporting the “<<” operator or supported by std::ostream

Return

Parameters

value:

std::string toString(const float &value)¶

Floats are output to their maximum precision of 7 digits

Return

Parameters

value:

std::string toString(const double &value)¶

Doubles are output to their maximum precision of 15 digits

Return

Parameters

value:

std::string toString(const std::complex<float> &value)¶

Complex floats are output to their maximum precision of 7 digits

Return

Parameters

value:

std::string toString(const std::complex<double> &value)¶

Complex doubles are output to their maximum precision of 15 digits

Return

Parameters

value:

std::string toString(const std::string &value)¶

std::string toString(const char *const &value)¶

std::string toString(const unsigned char value)¶

std::string toString(const signed char value)¶

std::string toString(const wchar_t *const &value)¶

std::string toString(const std::wstring &value)¶

std::string toString(const karabo::util::CppNone &value)¶

template <typename T>

std::string toString(const std::vector<T> &value, size_t maxElementsShown = 0)¶

Vector values are output as a comma separated list, where the StringTools::toString method for their value type T defines the representation of each element

Return

Parameters

value: is the vector to be converted
maxElementsShown: is the maximum number of vector elements treated. If value.size() is larger, skip elements in the middle. Default is 0 which means no skipping of elements.

std::string toString(const std::vector<std::string> &value)¶

String vector values are output as a comma separated list. The individual strings in the list may not contain comma (,) separators, e.g. an element “Hello, World” is not allowed as it would yield a representation ambiguous with two elements “Hello” and “World” -> “Hello, World”.

Return

Parameters

value:

std::string toString(const std::vector<unsigned char> &value)¶

std::string toString(const std::vector<char> &value)¶

template <typename T>

std::string toString(const std::pair<const T *, size_t> &value)¶

Pointers with size information given as a std::pair of pointer and size are output like vectors (see StringTools::toString(const std::vector<T>&) )

Return

Parameters

value:

std::string toString(const std::pair<const unsigned char *, size_t> &value)¶

std::string toString(const std::pair<const char *, size_t> &value)¶

template <typename T>

std::string toString(const std::set<T> &value)¶

A std::set is output as a list of comma (,) separated values

Return

Parameters

value:

template <typename T>

std::string toString(const std::unordered_set<T> &value)¶

A std::unordered_set is output as a list of comma (,) separated values

Return

Parameters

value:

template <typename T>

std::string toString(const std::deque<T> &value)¶

A std::deque is output as a list of comman (,) separated values

Return

Parameters

value:

template <typename KeyType, typename ValueType>

std::string toString(const std::map<KeyType, ValueType> &value)¶

A std::map is output in the form { key1 : value1, key2: value2, … }

Return

Parameters

value:

std::string toString(const karabo::util::State &value)¶

States are output using their stringified name

Return

Parameters

value:

template <class T>

T fromString(const std::string &value)¶

The generic fromString method tries to obtain a value of type T using a boost::lexical_cast of the passed value.

Return

Parameters

value:

template <>

int fromString(const std::string &value)

For integer return values the lowever overhead method strtol is used

Return

Parameters

value:

template <>
unsigned int fromString(const std::string &value)

template <>
long long fromString(const std::string &value)

template <>
unsigned long long fromString(const std::string &value)

template <>

karabo::util::CppNone fromString(const std::string &value)

A string “None” can be cast to karabo::util::CppNone. Any other string representation may not!

Return

Parameters

value:

template <>

karabo::util::ByteArray fromString(const std::string &value)

Bytearrays can be constructed from strings where each character in the string represents a byte (char) in the array

Return

Parameters

value:

template <typename T, template< typename ELEM, typename=std::allocator< ELEM >> class CONT>

CONT<T> fromString(const std::string &value, const std::string &separator = ",")¶

Sequence type elements can be constructed from strings of the form

[ value1, value2, …, valueN ]

where the enclosing brackets ([]) are optional and other separators may be specified. The sequence elements must have a StringTools:fromString method for their type T and each element must be castable to T using this method.

Return

Parameters

value:
separator: if separator other than the comma (,) is used

template <>

std::vector<unsigned char> fromString(const std::string &value, const std::string&)

Vectors of unsigned char elements can be constructed directly from strings where character of the string represents a byte of the vector. The second argument should be set to “”

Parameters

value:

template <class T>

std::vector<T> fromStringForSchemaOptions(const std::string &value, const std::string &sep)¶

XXX: This function is working around the surprising behavior of fromstring<unsigned char>(value, sep) seen above. The long-term solution should be to remove the base64 encoding/decoding in toString/fromString. However, we need to discover which code is expecting that behavior before making such a change.

In the meantime, we can use this simple version for schema options parsing.

template <>

std::vector<char> fromString(const std::string &value, const std::string&)

Vectors of char elements can be constructed directly from strings where character of the string represents a byte of the vector. The second argument should be set to “”

Parameters

value:

template <typename T, template< typename ELEM, typename=std::less< ELEM >, typename=std::allocator< ELEM >> class CONT>
CONT<T> fromStringToSortedCont(const std::string &value, const std::string &separator = ",")¶

template <>
std::vector<int> fromString(const std::string &value, const std::string &separator)

template <>
std::vector<unsigned int> fromString(const std::string &value, const std::string &separator)

template <>
std::vector<long long> fromString(const std::string &value, const std::string &separator)

template <>
std::vector<unsigned long long> fromString(const std::string &value, const std::string &separator)

template <>
template<> unsigned char fromString<unsigned char>(const std::string &value)¶

template <>
template<> signed char fromString<signed char>(const std::string &value)¶

template <>
template<> float fromString<float>(const std::string &value)¶

template <>
template<> double fromString<double>(const std::string &value)¶

template <>
template<> bool fromString<bool>(const std::string &value)¶

template <typename container>

void tokenize(const std::string &inputString, container &tokens, char const *delimiters)¶

Split a string into its components separated by any of the given delimiters

Parameters

inputString:
tokens: output container - will never be empty
delimiters: each char in this C-style string indicates the end of a substring

template <typename container>

void tokenize(const std::string &inputString, container &tokens, const char delimiter)¶

Split a string into its components separated by the given delimiter

Parameters

inputString:
tokens: output container - will never be empty
delimiter:

bool isBigEndian()¶

void non_implemented_since_TimeDuration_cannot_be_multiplied_with_signed_factor()¶

std::ostream &operator<<(std::ostream &os, const TimeDuration &duration)¶

std::ostream &operator<<(std::ostream &os, const TimeProfiler &profiler)¶

bool operator==(const Timestamp &lhs, const Timestamp &rhs)¶

Compare if the Epochstamp and Trainstamp of this Timestamp are the same as those of other

Return

Parameters

other:

bool operator!=(const Timestamp &lhs, const Timestamp &rhs)¶

Compare if the Epochstamp and/or Trainstamp of this Timestamp are not the same of other

Return

Parameters

other:

std::ostream &operator<<(std::ostream &out, const Timestamp &timestamp)¶

karabo::util::KARABO_MAP_TO_REFERENCE_TYPE(ToSize, INT64, sizeof(long long))

std::ostream &operator<<(std::ostream &out, const Trainstamp &trainstamp)¶

bool operator==(const Trainstamp &lhs, const Trainstamp &rhs)¶

bool operator!=(const Trainstamp &lhs, const Trainstamp &rhs)¶

template <class Processor>
bool templatize(Types::ReferenceType type, Processor &processor)¶

template <int MetricEnum>
std::pair<std::string, std::string> getMetricPrefix()¶

template <>
template<> std::pair<std::string, std::string> getMetricPrefix<MetricPrefix::NONE>()¶

std::pair<std::string, std::string> getMetricPrefix(const MetricPrefixType metricPrefix)¶

template <int UnitEnum>
std::pair<std::string, std::string> getUnit()¶

std::pair<std::string, std::string> getUnit(const UnitType unit)¶

bool isOutputChannelSchema(const karabo::util::Hash::Node &n)¶

bool onlyContainsEmptyHashLeafs(const karabo::util::Hash::Node &n)¶: Recursively checks if the given node strictly contains Hash nodes which ultimately ends in an empty Hash leaf.

bool operator==(const karabo::util::Version &v1, const karabo::util::Version &v2)¶

bool operator>(const karabo::util::Version &v1, const karabo::util::Version &v2)¶

bool operator!=(const karabo::util::Version &v1, const karabo::util::Version &v2)¶

bool operator>=(const karabo::util::Version &v1, const karabo::util::Version &v2)¶

bool operator<(const karabo::util::Version &v1, const karabo::util::Version &v2)¶

bool operator<=(const karabo::util::Version &v1, const karabo::util::Version &v2)¶

Variables

const std::string b64_char = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"¶

char const *const INFLUX_DURATION_UNIT = "u"¶

unsigned int const INFLUX_PRECISION_FACTOR = 1000000¶

char const *const DATALOGMANAGER_ID = "Karabo_DataLoggerManager_0"¶

char const *const DATALOGGER_PREFIX = "DataLogger-"¶

char const *const DATALOGREADER_PREFIX = "DataLogReader"¶

char const *const DATALOG_LINE_REGEX = "^([TZ0-9\\.]+)\\|([0-9\\.]+)\\|([0-9]+)\\|(.+)\\|([A-Z][0-9A-Z_]+)\\|(.*)\\|([a-z0-9_]*)\\|([A-Z]+)$"¶

char const *const DATALOG_LOGOUT_REGEX = "^([TZ0-9\\.]+)\\|([0-9\\.]+)\\|([0-9]+)\\|\\.\\|(![\\s\\S])\\|(.*)\\|([a-z0-9_]*)\\|([A-Z]+)$"¶

char const *const DATALOG_INDEX_LINE_REGEX = "^([A-Z=\\+\\-]+)[\\s]+([TZ0-9\\.]+)[\\s]+([0-9\\.]+)[\\s]+(.+)$"¶

char const *const DATALOG_INDEX_TAIL_REGEX = "^([0-9]+)[\\s]+([0-9]+)[\\s]+([a-z0-9_\\.]*)[\\s]+([0-9]+)$"¶

unsigned int const DATALOGREADERS_PER_SERVER = 2¶

char const *const DATALOG_NEWLINE_MANGLE = ".KRB_NEWLINE."¶

const unsigned int MAX_INFLUX_VALUE_LENGTH = 921600u¶

const std::locale formats[] = { std::locale(std::locale::classic(), new boost::posix_time::time_input_facet( "%Y%m%dT%H%M%S%.%f")), std::locale(std::locale::classic(), new boost::posix_time::time_input_facet("%Y-%m-%dT%H:%M:%S")) }¶

const size_t formats_n = sizeof(formats) / sizeof(formats[0])¶

const std::set<Types::ReferenceType> SUPPORTED_TBL_COL_TYPES = { Types::BOOL, Types::INT8, Types::UINT8, Types::INT16, Types::UINT16, Types::INT32, Types::UINT32, Types::INT64, Types::UINT64, Types::FLOAT, Types::DOUBLE, Types::STRING, Types::VECTOR_BOOL, Types::VECTOR_INT8, Types::VECTOR_UINT8, Types::VECTOR_INT16, Types::VECTOR_UINT16, Types::VECTOR_INT32, Types::VECTOR_UINT32, Types::VECTOR_INT64, Types::VECTOR_UINT64, Types::VECTOR_FLOAT, Types::VECTOR_DOUBLE, Types::VECTOR_STRING}¶

const karabo::util::Validator::ValidationRules tableValidationRules¶: Validation rules to be used when table elements in Hash are merged.

int key = 0¶

karabo::util::UINT64

class AlarmCondition¶

#include <AlarmConditions.hh>

A unified alarm condition class, which holds the alarm conditions known to Karabo.

Public Functions

const std::string &asString() const¶

Returns a stringified version of the alarm condition

Return

const std::string &asBaseString() const¶

Returns a stringified version of the alarm condition or its base if applicable

Return

operator std::string() const¶

Allows for direct assignment of conditions to strings

Return

bool isMoreCriticalThan(const AlarmCondition &other) const¶

Tests whether an alarm condition is more critical than this alarm condition

Return

true if this condition has a higher criticality than the other; false otherwise.

Parameters

other: the condition to test criticality against

bool isSameCriticality(const AlarmCondition &test) const¶

Tests whether two alarm conditions are similar, e.g. are subsets of the same basic condition

Return

true if the conditions are subsets of the same base; false otherwise.

Parameters

test: the condition to test similarity against

const AlarmCondition &returnMoreSignificant(const AlarmCondition &other) const¶

Returns the more significant of the two condtions

Return

Parameters

other:

Public Static Functions

AlarmCondition returnMostSignificant(const std::vector<AlarmCondition> &v)¶

Returns the most significant alarm condition out of a list of conditions

Return

the most significant condition in the list (it will return the parent condition where applicable) e.g. WARN_HIGH -> WARN

Parameters

v: the list of alarm conditions

const AlarmCondition &fromString(const std::string &condition)¶

Returns an alarm condition object matching to the stringified condition

Return

a reference to an alarm condition object

Parameters

condition: a known alarm condition

class AlarmConditionElement¶

#include <AlarmConditionElement.hh>

The AlarmConditionElement represents a leaf and needs to be of type AlarmCondition

Inherits from karabo::util::GenericElement< AlarmConditionElement >

Public Functions

AlarmConditionElement &initialValue(const AlarmCondition &a)¶

The initialValue method serves for setting up the initial value reported for this parameter.

Return

reference to the Element for proper methods chaining

Parameters

val: Initial value

template <class Element, class ValueType, class ReturnType>

class AlarmSpecific¶

#include <LeafElement.hh>

The AlarmSpecific Class assures acknowledgements are configured for alarm conditions

Public Functions

ReturnType &needsAcknowledging(const bool ack)¶

The needsAcknowledging method serves for setting up whether an alarm condition needs to be acknowledged to clear from alarm service devices

Return

reference to the Element for proper methods chaining

Parameters

ack: acknowledgement is needed if true.

AlarmSpecific<Element, ValueType, ReturnType> &info(const std::string &desc)¶

The info method allows for setting an optional description of the alarm

Return

reference to the Element for proper methods chaining

Parameters

description: optional description

class ByteArrayElement¶: Inherits from karabo::util::LeafElement< ByteArrayElement, ByteArray >

template <typename From, typename To, typename = void>
struct can_static_cast¶: Inherits from false_type

template <typename From, typename To>
template<> struct can_static_cast<From, To, std::void_t<decltype(static_cast<To>(std::declval<From>()))>>¶: Inherits from true_type

class CastException¶

#include <Exception.hh>

The CastException handles exceptions that are raised due to illegal type castings

Inherits from karabo::util::Exception

class ChoiceElement¶

#include <ChoiceElement.hh>

An element allowing choice-access to a list of factorized classes.

The ChoiceElement can be configured to allow a choice between factorized class registered with it. Two methods exist for adding classes to the list of choices the ChoiceElement knows of:

ChoiceElement::appendNodesOfConfigurationBase is used if another class of a type known to the factory system is to be added
ChoiceElement::appendAsNode is used to append the entries of a NodeElement defined in the same expectedParameter function as the choice element

In either case, the user can select from the options during configuration

Inherits from karabo::util::GenericElement< ChoiceElement >

Public Functions

template <class ConfigurationBase>

ChoiceElement &appendNodesOfConfigurationBase()¶

Append the expected parameters of another class of type ConfigurationBase. The class needs to be known by the factory system. It will be identified by its Karabo ClassId in the list of options.

Return

template <class T>

ChoiceElement &appendAsNode(const std::string &nodeName = "")¶

Append the entries found underneath a NodeElement identified by key. The node element needs to be defined prior to and in the same expected parameter function as the ChoiceElement.

Return

Parameters

nodeName: identifying the node, i.e. the key of the node.

virtual ChoiceElement &assignmentMandatory()¶

The assignmentMandatory method serves for setting up a mode that requires the value of the element always being specified. No default value is possible.

Return: reference to the Element (to allow method’s chaining)

virtual DefaultValue<ChoiceElement, std::string> &assignmentOptional()¶

The assignmentOptional method is used to indicate that this element can optionally be configured. It is followed by either specifying that noDefaulValue() exists, or the defaultValue() is a classId or node key registered in the list of choices using either ChoiceElement::appendAsNode or ChoiceElement::appendNodesOfConfigurationBase.

Return

virtual ChoiceElement &init()¶

The init method serves for setting up an access type property that allows the element to be included in initial schema.

Return: reference to the Element (to allow method’s chaining)

virtual ChoiceElement &reconfigurable()¶

The reconfigurable method serves for setting up an access type property that allows the element to be included in initial, reconfiguration and monitoring schemas.

Return: reference to the Element (to allow method’s chaining)

class ClassInfo¶

#include <ClassInfo.hh>

ClassInfo holds meta-data to a factorized class.

Public Functions

const std::string &getClassName() const¶

Return the C++ class name of this class

Return

const std::string &getNamespace() const¶

Return the C++ name space of this class

Return

const std::string &getClassId() const¶

Return the Karabo ClassId of this class

Return

const std::string &getLogCategory() const¶

Return the LogCategory for this class

Return

const std::string &getVersion() const¶

Return the version number of this class - currently does not convey much meaning.

Return

template <typename is_hash_base>

struct conditional_hash_cast¶

#include <MetaTools.hh>

Conditionally cast a type to Hash, if Hash is a base class, but disallow this for shared pointers of these types. Will result in a compiler error if this is attempted.

Any type not derived from Hash is simply returned as is.

template <class BaseClass>

class Configurator¶

#include <Configurator.hh>

The Configurator provides for creating and configuring factorized classes.

Public Static Functions

template <class DerivedClass>

static void registerClass(const std::string &classId)¶

Register a base class with standard Hash configuration constructor into the factory

Parameters

classId: identifying the class in the factory

template <class DerivedClass, typename A1>

static void registerClass(const std::string &classId)

Register a class having constructor with additional A1 type parameter (besides the standard Hash configuration) into the factory

Parameters

classId: identifying the class in the factory

template <class T>

static void registerSchemaFunction(const std::string &classId)¶

Register the schema decription function for classId in the factory

Parameters

classId: identifying the class in the factory

template <class… A>

static void registerSchemaFunctions(const std::string &classId)¶

Register the schema decription functions for classId in the factory

The parameter pack ‘A’ typically is the list of all the classes in the inheritance chain of ‘classId’, including itself at the end.

Parameters

classId: identifying the class in the factory

static void setDefault(const std::string &classId)¶

Set the default class id of the factory

Parameters

classId:

static Schema getSchema(const std::string &classId, const Schema::AssemblyRules &rules = Schema::AssemblyRules())¶

Get the schema defining a factorized class

Return

Parameters

classId: identifying the class in the factory
rules: defining how to assembly the returned Schema

static BaseClass::Pointer createDefault(const bool validate = true)¶

Create an Object of the default class of this factory

Return

a pointer to the created object

Parameters

validate:

static BaseClass::Pointer create(const karabo::util::Hash &configuration, const bool validate = true)¶

Create an object as described by configuration from the factory

Return

a pointer to the created object

Parameters

configuration: where the root-nodes key identifies the classId
validate: if true, validate the configuration against the classes Schema. Raises an exception if validation fails

static BaseClass::Pointer create(const std::string &classId, const karabo::util::Hash &configuration = Hash(), const bool validate = true)¶

Create an object of classId from the factory, assign default values as given by the class Schema

Return

a pointer to the created object

Parameters

configuration: Hash containing the configuration
validate: if true, validate the configuration against the classes Schema. Raises an exception if validation fails

template <typename A1>

static BaseClass::Pointer create(const karabo::util::Hash &configuration, const A1 &a1, const bool validate = true)¶

Create an object as described by configuration from the factory

Return

a pointer to the base class of created object

Parameters

configuration: where the root-nodes key identifies the classId
arbitrary: type parameter to be passed to the constructor
validate: if true, validate the configuration against the classes Schema. Raises an exception if validation fails

template <typename A1>

static BaseClass::Pointer create(const std::string &classId, const karabo::util::Hash &configuration, const A1 &a1, const bool validate = true)¶

Create an object of classId as described by configuration from the factory

Return

a pointer to the base class of created object

Parameters

configuration: Hash containing the configuration
arbitrary: type parameter to be passed to the constructor
validate: if true, validate the configuration against the classes Schema. Raises an exception if validation fails

static BaseClass::Pointer createNode(const std::string &nodeName, const std::string &classId, const karabo::util::Hash &input, const bool validate = true)¶

Use this function to create a configurable object as part of a parent one (aggregation).

The input configuration may contain regular Hash parameters under the key nodeName or an already instantiated object of type BaseClass::Pointer.

This signature of this function allows to specify a classId in case the Aggregate itself is a derivative of BaseClass.

Return

Shared pointer of the created object

Parameters

nodeName: The key name of the NODE_ELEMENT as defined by the parent class
classId: The factory key of the to be created object (must inherit the BaseClass template)
input: The input configuration of the parent class
validate: Whether to validate or not

static BaseClass::Pointer createNode(const std::string &nodeName, const karabo::util::Hash &input, const bool validate = true)¶

Use this function to create a configurable object of class template type as part of a parent one (aggregation).

The input configuration may contain regular Hash parameters under the key nodeName or an already instantiated object of type BaseClass::Pointer.

Return

Shared pointer of the created object

Parameters

nodeName: The key name of the NODE_ELEMENT as defined by the parent class
input: The input configuration of the parent class
validate: Whether to validate or not

static BaseClass::Pointer createChoice(const std::string &choiceName, const karabo::util::Hash &input, const bool validate = true)¶

Create object from a choice of factorized classes as defined by choiceName from input configuration

Return

Parameters

choiceName:
input:
validate:

static std::vector<typename BaseClass::Pointer> createList(const std::string &listName, const karabo::util::Hash &input, const bool validate = true)¶

Create a list of factorized classes as defined by input configuration. Classes need to be of the same Base class

Return

Parameters

choiceName:
input:
validate:

static std::vector<std::string> getRegisteredClasses()¶

Return a vector of classIds registered in this Configurator

Return

static void validateConfiguration(const std::string &classId, const Hash &configuration, Hash &validated)¶

Trigger a validation of class BaseClass (or a derivative) against the Schema as provided by the static expectedParameters function

NOTE: During regular factory construction validation already is done (if validate==true) *

Parameters

classId: The factory key of the to be created object (must inherit the BaseClass template)
configuration: A hash that is checked against the expectedParameters requirements
validated: The resultant validated hash (has defaults injected)

class CudaException¶

#include <Exception.hh>

The CudaException handles exceptions that are caused by the NVIDIA CUDA runtime

Inherits from karabo::util::Exception

template <class Derived, class Described>

class CustomNodeElement¶

#include <CustomNodeElement.hh>

Helper class to construct custom NODE_ELEMENTs for schemas. Usage is best explained by example, say you coded a custom data class (by inheriting protected Hash) describing it’s expected parameters like:

class MyData : protected Hash {
    static void expectedParameters(const Schema& s) {
        // parameter definition [...]
    }
};

Then you may generate a NODE_ELEMENT like this:

class MyDataElement : public CustomNodeElement<MyData> {

    MyDataElement(karabo::util::Schema& s) : CustomNodeElement<MyData>(s) {
    }

    // If you want to expose parameters for setting defaults do like:
    CustomNodeElement<ImageData>& setFoo(const std::string& bar) {
        return CustomNodeElement<ImageData >::setDefaultValue("foo", bar);
    }
};
typedef MyDataElement MYDATA_ELEMENT;

Public Functions

Derived &key(const std::string &key)¶

The key method serves for setting up a unique name for the element. Example:

SOME_ELEMENT(expected)
        .key("type")
        ...
        .commit();

Return

reference to the Element (to allow method’s chaining)

Parameters

name: Unique name for the key

Derived &displayedName(const std::string &name)¶

The displayedName method serves for setting up an user friendly name for the element to be used by GUI Example:

SOME_ELEMENT(expected)
        ...
        .displayedName("Connection Type")
        ...
        .commit();

Return

reference to the Element (to allow method’s chaining)

Parameters

name: User friendly name for the element

Derived &description(const std::string &desc)¶

The description method serves for setting up a description of the element Example:

SOME_ELEMENT(expected)
        ...
        .description("Decide whether the connection is used to implement a TCP Server or TCP Client")
        ...
        .commit();

Return

reference to the Element (to allow method’s chaining)

Parameters

desc: Short description of the element

Derived &init()¶

The init method serves for setting up an access type property that allows the element to be included in initial schema.

Return: reference to the Element (to allow method’s chaining)

Derived &reconfigurable()¶

The reconfigurable method serves for setting up an access type property that allows the element to be included in initial, reconfiguration and monitoring schemas.

Return: reference to the Element (to allow method’s chaining)

Derived &readOnly()¶

The readOnly method serves for setting up an access type property that allows the element to be included in monitoring schema only.

Return: reference to the Element (to allow method’s chaining)

Derived &observerAccess()¶

The observerAccess method serves for setting up the required access level attribute to be OBSERVER.

Return: reference to the Element (to allow method’s chaining)

Derived &userAccess()¶

The userAccess method serves for setting up the required access level attribute to be USER.

Return: reference to the Element (to allow method’s chaining)

Derived &operatorAccess()¶

The operatorAccess method serves for setting up the required access level attribute to be OPERATOR.

Return: reference to the Element (to allow method’s chaining)

Derived &expertAccess()¶

The expertAccess method serves for setting up the required access level attribute to be EXPERT.

Return: reference to the Element (to allow method’s chaining)

Derived &adminAccess()¶

The adminAccess method serves for setting up the required access level attribute to be ADMIN.

Return: reference to the Element (to allow method’s chaining)

Derived &setAllowedActions(const std::vector<std::string> &actions)¶

Specify one or more actions that are allowed on this node.

If a Karabo device specifies allowed actions for a node, that means that it offers a specific slot interface to operate on this node. Which allowed actions require which interface will be defined elsewhere.

Return: reference to the Element (to allow method’s chaining)

Derived &skipValidation()¶

Skip this element during validation of configuration against a Schema

Return

template <class T>

Derived &setDefaultValue(const std::string &subKey, const T &defaultValue)¶

Set the default value for a subkey of the CustomNodeElement

Return

Parameters

subKey:
defaultValue:

Derived &setMaxSize(const std::string &subKey, const unsigned int maxSize)¶

Set the maximum size of a subkey of the CustomNodeElement. This is required by the DAQ for all vector attributes if its not assigned automatically or just to use a different value then the DAQ’s default length of 1000.

Return

Parameters

subKey: Key of the vector attribute (like “pixels.shape”)
maxSize: Number as the maximum size (like 3)

Derived &setUnit(const std::string &subKey, const UnitType &unit)¶

Set the unit for a subkey of the CustomNodeElement

Return

Parameters

subKey:
unit:

Derived &setMetricPrefix(const std::string &subKey, const MetricPrefixType &metricPrefix)¶

Set the metric prefix for a subkey of the CustomNodeElement

Return

Parameters

subKey:
metricPrefix:

void commit()¶: Registers this element into the Schema

class DateTimeString¶

#include <DateTimeString.hh>

This class expresses a valid date and time information in the form of a char string. To be a valid date and time char string, it must respect:

ISO-8601:2000 Second Edition definition (docs available at http://www.qsl.net/g1smd/isopdf.htm)
Subset (of ISO-8601) defined as Karabo date and time API
- Compact version: yyyymmddThhmmss[.|,]ffffffZ|z|±hhmm
- Extended version: yyyy-mm-ddThh:mm:ss[.|,]ffffffZ|z|±hh:mm

The default constructor initializes a DateTimeString object with the Epoch values (“19700101T000000Z”).

Public Functions

DateTimeString()¶: Constructor without parameters, that creates a instance with epoch Timestamp (“19700101T000000Z”)

DateTimeString(const std::string &timePoint)¶

Constructor from string

Parameters

timePoint: String that represents a complete and valid date format using Karabo agreed ISO-8601 subset API

DateTimeString(const std::string &inputDate, const std::string &inputTime, const std::string &inputFractionSecond, const std::string &inputTimeZone)¶

Constructor from string

Parameters

inputDateStr: String that represents the date part of the Karabo agreed ISO-8601 subset API
inputTimeStr: String that represents the time part of the Karabo agreed ISO-8601 subset API
inputFractionSecondStr: String that represents the fractional part of the Karabo agreed ISO-8601 subset API
inputTimeZoneStr: String that represents the time zone part of the Karabo agreed ISO-8601 subset API

const std::string &getDate() const¶

Get string that represents the date part of the Karabo agreed ISO-8601 subset API (i.e. “2013-01-20”)

Return: string

const std::string &getTime() const¶

Get string that represents the time part of the Karabo agreed ISO-8601 subset API (i.e. “20:30:00”)

Return: string

template <typename T>

const T getFractionalSeconds() const¶

Get string or unsigned long long that represents the fractional part of the Karabo agreed ISO-8601 subset API (i.e. “123456”)

Return: string

const std::string &getTimeZone() const¶

Get string that represents the time zone part of the Karabo agreed ISO-8601 subset API (i.e. “Z”)

Return: string

const std::string &getDateTime() const¶

Get string that represents the date and time part of the Karabo agreed ISO-8601 subset API (i.e. “2013-01-20T20:30:00”)

Return: string

const unsigned long long getSecondsSinceEpoch()¶

Returns the number of seconds elapsed since epoch for this object

Return: unsigned long long (Seconds elapsed since Epoch)

Public Static Functions

const bool isStringValidIso8601(const std::string &timePoint)¶

Validates if a string representing a timestamp is valid according to ISO-8601 definition

Return

boolean (True is string is valid, False otherwise)

Parameters

timePoint: String that represents a Timestamp

const bool isStringValidIso8601TimeZone(const std::string &iso8601TimeZone)¶

Validates if a string representing a time zone is valid according to ISO-8601 definition

Return

boolean (True is string is valid, False otherwise)

Parameters

iso8601TimeZone: String that represents a Time Zone (i.e. “+01:00” or “-07:00”)

const bool isStringKaraboValidIso8601(const std::string &timePoint)¶

Validates if a string representing a timestamp is valid according to Karabo agreed ISO-8601 subset API definition Some examples: => Extended strings:

1985-01-20T23:20:50
1985-01-20T23:20:50,123
1985-01-20T23:20:50.123
1985-01-20T23:20:50.123z
1985-01-20T23:20:50.123Z
1985-01-20T23:20:50z
1985-01-20T23:20:50Z
1985-01-20T23:20:50+00:00
1985-01-20T23:20:50-07:00 => Compact strings:
19850120T232050
19850120T232050,123
19850120T232050.123
19850120T232050.123z
19850120T232050.123Z
19850120T232050z
19850120T232050Z
19850120T232050+0000
19850120T232050-0700

Return

boolean (True is string is valid, False otherwise)

Parameters

timePoint: String that represents a Timestamp

const std::string fractionalSecondToString(const TIME_UNITS precision = MICROSEC, const unsigned long long fractionalSeconds = 0, bool skipDot = false)¶

Converts a fractional second value into it’s value with a smaller precision Because fractional seconds are received as an UNSIGNED LONG LONG, this function assumes the algarisms are the right most algarisms. Due to this reason, if there are missing algarisms to perform the desired precision resolution, zeros will be added to this left of the fractional seconds number received.

Return

String started with a “.” (dot) (except skipDot is true) and followed by the fractional second till the desired precision

Parameters

precision: - Indicates the precision of the fractional seconds (e.g. MILLISEC, MICROSEC, NANOSEC, PICOSEC, FEMTOSEC, ATTOSEC) [Default: MICROSEC]
fractionalSeconds: - Fractional seconds to be return with the correct desired precision
skipDot: - if true, skip leading dot “.” in result [Default: false]

const std::string fractionalStringToAttoFractionalString(const std::string &fractionalSeconds)¶

Converts a STRING fractional second value into it’s value in ATTOSEC precision Because fractional seconds are received as a STRING, this function assumes the algarisms are the left most algarisms. Due to this reason, if there are missing algarisms to perform ATTOSEC resolution, zeros will be added to this right of the fractional seconds number received.

Return

String started with a “.” (dot) and followed by the fractional second till the desired precision

Parameters

fractionalSeconds: - Fractional seconds to be return with ATTOSEC precision

const karabo::util::Hash getTimeDurationFromTimeZone(const std::string &iso8601TimeZone = "Z")¶

Split an ISO-8601 valid Time Zone

Return

Hash containing the Time Zone information in three different keys (<std::string>(“timeZoneSignal”), <int>(“timeZoneHours”), <int>(“timeZoneMinutes”))

Parameters

iso8601TimeZone: String that represents a Time Zone (i.e. “Z” or “+01:00” or “-07:00”) [Default: “Z”]

Private Static Functions

const unsigned long long ptimeToSecondsSinceEpoch(boost::posix_time::ptime &pt)¶

Convert a specific boost ptime to the number of seconds since epoch (1970-Jan-1 00:00:00)

Return

number of seconds since epoch

Parameters

pt: specific boost ptime

const DateTimeString iso8601KaraboApiStringToDateTimeString(const std::string &timePoint)¶

Creates an DateTimeString from an ISO-8601 formatted string (string must be a complete and valid timestamp using Karabo agreed ISO-8601 subset API)

Return

DateTimeString object

Parameters

timePoint: ISO 8601 formatted string (see formats locale to more information)

template <class Element, class ValueType>

class DefaultValue¶

#include <LeafElement.hh>

The DefaultValue class defines a default value for element.

Public Functions

void setElement(Element *el)¶

Set the element this DefaultValue refers to

Parameters

el:

Element &defaultValue(const ValueType &defaultValue)¶

The defaultValue method serves for setting up the default value to be used when User configuration does not specify another value.

Return

reference to the Element for proper methods chaining

Parameters

val: Default value

Element &defaultValueFromString(const std::string &defaultValue)¶

The defaultValueFromString method enables setting up a default value in a form of a string. This may, for example, be convenient for vector elements.

Return

reference to the Element for proper methods chaining

Parameters

defaultValue: A string representation of the default value

Element &noDefaultValue()¶

The noDefaultValue serves for setting up the element that does not have a default value.

Return: reference to the Element for proper methods chaining

class Dims¶

#include <Dims.hh>

A class describing array dimensions.

Public Functions

std::size_t rank() const¶

Return the rank of the dimensions

Return

ull64 size() const¶

Return the total number of elements in the array

Return

ull64 extentIn(size_t idx) const¶

Return the extend of the array in the dimension identified by idx

Return

Parameters

idxneeds: to be >= 0 and , rank

const std::vector<ull64> &toVector() const¶

Return a std::vector holding the dimension sizes

Return

void fromVector(const std::vector<ull64> &vec)¶

Create a dimension object from a vector

Parameters

vec:

ull64 x1() const¶

Return size of first dimension

Return

ull64 x2() const¶

Return size of second dimension

Return

ull64 x3() const¶

Return size of third dimension

Return

ull64 x4() const¶

Return size of fourth dimension

Return

void reverse()¶: Reverse dimension sizes

Private Functions

void calculate()¶: calculate rank and number of elements in array.

class DoocsException¶

#include <Exception.hh>

DoocsException

Inherits from karabo::util::Exception

template <typename KeyType, typename AttributesType = bool>

class Element¶

#include <Element.hh>

Class representing leaf elements in a Hash which may have attributes.

Public Functions

Element()¶: Construct an empty Hash element

Element(const KeyType &key, const std::any &value)¶

Construct a Hash element from a std::any value

Parameters

key: identifies the element
value: of the element

Element(const KeyType &key, std::any &&value)¶

Construct a Hash element from a std::any value

Parameters

key: identifies the element
value: of the element

template <class ValueType>

Element(const KeyType &key, const ValueType &value)¶

Construct a Hash element from an arbitrary value type

Parameters

key: identifies the element
value: of the element

template <class ValueType>

Element(const KeyType &key, ValueType &&value)¶

Construct a Hash element from an arbitrary value type

Parameters

key: identifies the element
value: of the element

const KeyType &getKey() const¶

Return the key identifying this Element

Return

template <class ValueType>

void setValue(const ValueType &value)¶

Set a value of arbitrary type to this Element

Parameters

value:

template <class ValueType>

void setValue(ValueType &&value)¶

Set a value of arbitrary type to this Element

Parameters

value:

template <class ValueType>

void setValue(const std::shared_ptr<ValueType> &value)¶

Set the value to a std::shared_ptr of ValueType

Parameters

value:

void setValue(const std::shared_ptr<Hash> &value)¶: For downward compatibility we allow insertion of shared_ptr<Hash>. In general, we will create a compiler error for all objects deriving from Hash and wrapped as shared pointer.

void setValue(const char *value)¶

Overload for setting char pointers (c-strings). Internally, the element will hold a std::string.

Parameters

value:

void setValue(char *value)¶

Overload for setting char pointers (c-strings). Internally, the element will hold a std::string.

Parameters

value:

void setValue(const wchar_t *value)¶

Overload for setting wide char pointers (c-strings). Internally, the element will hold a std::wstring.

Parameters

value:

void setValue(wchar_t *value)¶

Overload for setting wide char pointers (c-strings). Internally, the element will hold a std::wstring.

Parameters

value:

void setValue(const std::any &value)¶

Set a std::any value to the Element

Parameters

value:

void setValue(std::any &&value)¶

Set a std::any value to the Element

Parameters

value:

void setValue(const Element<KeyType, AttributesType> &other)¶

Set the value of another element to this Element, key and attributes are unchanged.

Kept for backward compatibility, better use setValue(other.getValueAsAny()) instead.

Parameters

other:

void setValue(Element<KeyType, AttributesType> &&other)¶

Set the value of another element to this Element, key and attributes are unchanged.

Kept for backward compatibility, better use setValue(std::move(other.getValueAsAny())) instead.

Parameters

other:

template <class DestValueType, class SourceValueType, class… SourceValueTypes>

DestValueType getValue() const¶

Return the first successful cast to one of the ValueTypes (DestValueType, SourceValueType or one of the SourceValueTypes). Strict casting is applied, i.e. at least one of the ValueTypes needs to be of the exact type of inserted value (or implicitly castable)

Return: DestValueType by “copy”. Candidate for Return Value Optimization through copy elision.

template <class ValueType>

const ValueType &getValue() const

Return the value cast to ValueType. Strict casting is applied, i.e. the ValueType needs to be of the exact type of inserted value (or implicitly castable)

Return

template <class ValueType>

ValueType &getValue()¶

Return the value cast to ValueType. Strict casting is applied, i.e. the ValueType needs to be of the exact type of inserted value (or implicitly castable)

Return

std::any &getValueAsAny()¶

Return the value as std::any. Does not throw

Return

const std::any &getValueAsAny() const¶

Return the value as std::any. Does not throw

Return

template <typename ValueType>

ValueType getValueAs() const¶

Return the value cast to ValueType. Casting is performed via string literal casts, i.e. less strict.

Return

template <typename T, template< typename Elem, typename=std::allocator< Elem > > class Cont>

Cont<T> getValueAs() const

Return the value cast to ValueType. Casting is performed via string literal casts, i.e. less strict. Overload for vector-type values

Return

std::string getValueAsShortString(size_t maxNumVectorElements) const¶

Return the value cast to string. The only difference to getValueAs<string>() concerns elements of type Types::ReferenceType::VECTOR_*: Whereas getValueAs<string>() returns all vector elements, getValueAsShortString() shortens the string by leaving out vector elements in the middle, if the vector size exceeds the argument.

Return

Parameters

maxNumVectorElements: maximum number of vector elements taken into account

template <class T>

void setAttribute(const std::string &key, const T &value)¶

Set an attribute to this Element, identified by key

Parameters

key:
value:

template <class T>

void setAttribute(const std::string &key, T &&value)¶

Set an attribute to this Element, identified by key

Parameters

key:
value:

template <class T>

T &getAttribute(const std::string &key)¶

Return the attribute cast to ValueType. Strict casting is applied, i.e. the T needs to be of the exact type of inserted vale (or implicitly castable)

Return

Parameters

key: identifying the attribute

template <class T>

void getAttribute(const std::string &key, T &value) const¶

Return the attribute cast to ValueType. Strict casting is applied, i.e. the T needs to be of the exact type of inserted vale (or implicitly castable)

Return

Parameters

key: identifying the attribute
value: reference to insert value in

template <class T>

const T &getAttribute(const std::string &key) const¶

Return the attribute cast to ValueType. Strict casting is applied, i.e. the T needs to be of the exact type of inserted vale (or implicitly castable)

Return

Parameters

key: identifying the attribute

template <class T>

void getAttribute(const std::string &key, const T &value) const¶

Return the attribute cast to ValueType. Strict casting is applied, i.e. the T needs to be of the exact type of inserted vale (or implicitly castable)

Return

Parameters

key: identifying the attribute
value: reference to insert value in

const std::any &getAttributeAsAny(const std::string &key) const¶

Return the value as std::any. Does not throw

Return

Parameters

key: identifying the attribute

std::any &getAttributeAsAny(const std::string &key)¶

Return the value as std::any. Does not throw

Return

Parameters

key: identifying the attribute

template <class T>

T getAttributeAs(const std::string &key) const¶

Return the attribute cast to ValueType. Casting is performed via string literal casts, i.e. less strict. param key identifying the attribute

Return

template <typename T, template< typename Elem, typename=std::allocator< Elem > > class Cont>

Cont<T> getAttributeAs(const std::string &key) const

Return the attribute cast to ValueType. Casting is performed via string literal casts, i.e. less strict. Overload for vector-type values param key identifying the attribute

Return

Element<KeyType> &getAttributeNode(const std::string &key)¶

Return an attribute as a Node, e.g. an Element<T>

Return

Parameters

key:

const Element<KeyType> &getAttributeNode(const std::string &key) const¶

Return an attribute as a Node, e.g. an Element<T>

Return

Parameters

key:

bool hasAttribute(const std::string &key) const¶

Check if Element has an attribute identified by key

Return

true if the attribute exists, false if not

Parameters

key:

void setAttributes(const AttributesType &attributes)¶

Batch set attributes to this element

Parameters

attributes:

void setAttributes(AttributesType &&attributes)¶

Batch set attributes to this element

Parameters

attributes: to move from

const AttributeType &getAttributes() const¶

Batch get attributes of this element

Return

AttributeType &getAttributes()¶

Batch get attributes of this element

Return

template <typename T>

bool is() const¶

Check if element is of type T

Return: true if element is type T

Types::ReferenceType getType() const¶

Return the type of this element as a Karabo reference type

Return

const std::type_info &type() const¶

Return the std::type_info struct for this element’ type

Return

void setType(const Types::ReferenceType &tgtType)¶

Set the type of this Element to a different type. Requires that non-strict casting, as for getValueAs is possible. Otherwise throws and exception

Parameters

tgtType: type to set the element to

bool operator==(const Element<KeyType, AttributesType> &other) const¶

Compare two elements for equality: Checks if the elements have the same key

Return

Parameters

other:

bool operator!=(const Element<KeyType, AttributesType> &other) const¶

Compare two elements for inequality: Checks if the elements have the same key

Return

Parameters

other:

template <typename ValueType, typename isHashTheBase>

struct SetClassIdAttribute¶

Helper struct adding a classId attribute for classes inheriting (but not being) Hash. See also its specialisation for isHashTheBase and ValueType.

Public Functions

template<> SetClassIdAttribute(const ValueType &value, Element &e)¶

Set the classId attribute as given by value.getClassInfo()

Parameters

value: of classId to set
e: element to set classId to

template<> void resetHashDerivedMoved(ValueType &&value)¶: Helper to hack rvalue reference ‘value’ (which is Hash derived) back into a valid state

template<> void resetHashDerivedMoved(ValueType &value)¶: No-op for lvalue reference

template <typename isHashTheBase>

template<> struct SetClassIdAttribute<Hash, isHashTheBase>¶

Hashes are not touched.

Public Functions

template<> SetClassIdAttribute(const Hash &value, Element &e)¶

For the Hash itself (i.e. where std::is_base_of<Hash, Hash>::type is not std::false_type), this is a no-op as well.

Parameters

value:
e:

template <typename ValueType>

template<> struct SetClassIdAttribute<ValueType, std::false_type>¶

Types that are neither Hashes nor derived from Hashes are not touched.

Public Functions

template<> SetClassIdAttribute(const ValueType &value, Element &e)

For non Hash-derived types this is a no-op

Parameters

value:
e:

template<> void resetHashDerivedMoved(const ValueType &value)¶: No-op

class Epochstamp¶

#include <Epochstamp.hh>

This class expresses a point in time and holds its value in the form of two unsigned 64bit. The first expresses the total number of seconds elapsed since Unix epoch, i.e. 1970-01-01 00:00:00.00. The second expresses the number fractional of a seconds, in atto seconds, since the last time unit (in seconds).

The default constructor initializes a Epochstamp object with the current system time. To initialize using an arbitrary point in time the static from functions must be used (e.g. DateTimeString class)

Public Functions

Epochstamp()¶: The default constructor creates a timestamps using the current time

Epochstamp(const unsigned long long &seconds, const unsigned long long &fractions)¶

Constructor from seconds and fraction

Parameters

seconds: seconds past since the Unix epoch
fraction: attoSeconds past since the second under consideration

Epochstamp(const time_t &tm)¶

Constructor from implicit conversion from other system time structures,

Parameters

time_t:
timeval:
timespec:

const unsigned long long &getSeconds() const¶

Get the second (resp. fractional of a second) part,

Return: unsigned int 64bits

Epochstamp &operator=(const time_t &tm)¶

Portability operators to convert other system time structures to Epochstamp

Parameters

tm: time_t value
tv: timeval struct
ts: timespec struct

Epochstamp operator+(const TimeDuration &duration) const¶

Move a timestamp forward/backward with given time distance, expressed in terms of time duration

Return

Epochstamp object

Parameters

duration: TimeDuration object

TimeDuration operator-(const Epochstamp &other) const¶

Time duration is the difference between two timestamps

Return

TimeDuration object

Parameters

other: Epochstamp object

Epochstamp operator++(int)¶: Auto increment/decrement operators

time_t getTime() const¶

Portability functions to convert Epochstamp to other system time structures

Return: time_t value
Return: timeval struct
Return: timespec struct

void now()¶: Retrieve current time for the system. Highest resolution is Nano-seconds

TimeDuration elapsed(const Epochstamp &other = Epochstamp()) const¶

Calculate elapsed time duration between two timestamps

Return

TimeDuration object

Parameters

other: Epochstamp object (by default, current time point)

std::string toIso8601(TIME_UNITS precision = MICROSEC, bool extended = false) const¶

Generates a sting (respecting ISO-8601) for object time for INTERNAL usage (“%Y%m%dT%H%M%S%f” => “20121225T132536.789333[123456789123]”)

Return

ISO 8601 formatted string (extended or compact)

Parameters

precision: - Indicates the precision of the fractional seconds (e.g. MILLISEC, MICROSEC, NANOSEC, PICOSEC, FEMTOSEC, ATTOSEC) [Default: MICROSEC]
extended: - “true” returns ISO8601 extended string; “false” returns ISO8601 compact string [Default: false]

std::string toIso8601Ext(TIME_UNITS precision = MICROSEC, bool extended = false) const¶

Generates a sting (respecting ISO-8601) for object time for EXTERNAL usage (“%Y%m%dT%H%M%S%f%z” => “20121225T132536.789333[123456789123]Z”)

Return

ISO 8601 formatted string with “Z” in the string end (“Z” means the date time zone is using Coordinated Universal Time - UTC)

Parameters

precision: - Indicates the precision of the fractional seconds (e.g. MILLISEC, MICROSEC, NANOSEC, PICOSEC, FEMTOSEC, ATTOSEC) [Default: MICROSEC]
extended: - “true” returns ISO8601 extended string; “false” returns ISO8601 compact string [Default: false]

const double toTimestamp() const¶

Generates a timestamp as double with seconds.fractional format (fractional precision == MICROSEC) Function necessary to use in graphs plotting in Python code (MICROSEC precision is enough)

Return: A double value with the decimal point indicating fractions of seconds

std::string toFormattedString(const std::string &format = std::string("%Y-%b-%d %H:%M:%S"), const std::string &localTimeZone = std::string("Z")) const¶

Formats to specified format time stored in the object

Return

formated string in the specified Time Zone

Parameters

format: The format of the time point (visit strftime for more info: http://www.cplusplus.com/reference/ctime/strftime/) [Default: “%Y-%b-%d %H:%M:%S”]
localTimeZone: - String that represents an ISO8601 time zone [Default: “Z” == UTC]

std::string toFormattedStringLocale(const std::string &localeName = std::string(""), const std::string &format = std::string("%Y-%b-%d %H:%M:%S"), const std::string &localTimeZone = std::string("Z")) const¶

Formats to specified format time stored in the object

Return

formated string in the specified Time Zone

Parameters

localeName: - String that represents the locale to be used [Default: “” == System locale]
format: The format of the time point (visit strftime for more info: http://www.cplusplus.com/reference/ctime/strftime/) [Default: “%Y-%b-%d %H:%M:%S”]
localTimeZone: - String that represents an ISO8601 time zone [Default: “Z” == UTC]

void toHashAttributes(Hash::Attributes &attributes) const¶

Formats as Hash attributes

Parameters

attributes: container to which the time point information is added

Public Static Functions

Epochstamp fromHashAttributes(const Hash::Attributes &attributes)¶

Creates an EpochStamp from two Hash attributes This function throws in case the attributes do no provide the correct information

Return

EpochStamp object

Parameters

attributes: Hash attributes

Private Functions

std::string toFormattedStringInternal(const std::string &localeName, const std::string &format, const std::string &localTimeZone) const¶

Formats to specified format time stored in the object

Return

formated string in the specified Time Zone

Parameters

localeName: - String that represents the locale to be used [Default: “” == System locale]
format: The format of the time point (visit strftime for more info: http://www.cplusplus.com/reference/ctime/strftime/) [Default: “%Y-%b-%d %H:%M:%S”]
localTimeZone: - String that represents an ISO8601 time zone [Default: “Z” == UTC]

std::string toIso8601Internal(TIME_UNITS precision = MICROSEC, bool extended = false, const std::string &localTimeZone = std::string("Z")) const¶

Generates a sting (respecting ISO-8601) for object time for INTERNAL usage (“%Y%m%dT%H%M%S%f” => “20121225T132536.789333[123456789123]”)

Return

ISO 8601 formatted string (extended or compact)

Parameters

precision: - Indicates the precision of the fractional seconds (e.g. MILLISEC, MICROSEC, NANOSEC, PICOSEC, FEMTOSEC, ATTOSEC) [Default: MICROSEC]
extended: - “true” returns ISO8601 extended string; “false” returns ISO8601 compact string [Default: false]
localTimeZone: - String that represents an ISO8601 time zone [Default: “Z” == UTC]

template <typename To, typename PT1>

const To concatDateTimeWithFractional(const PT1 dateTime, const TIME_UNITS precision) const¶

Concatenates date and time information with instance fractional seconds within a specified precision

Return

Concatenation result

Parameters

dateTime: - Date and time information
precision: - Indicates the precision of the fractional seconds (e.g. MILLISEC, MICROSEC, NANOSEC, PICOSEC, FEMTOSEC, ATTOSEC) [Default: MICROSEC]

Private Static Functions

std::string getPTime2String(const boost::posix_time::ptime pt, const boost::posix_time::time_facet *facet, const std::string &localeName)¶

Returns timestamp string in “ANY SPECIFIED” format (format must be a valid format)

Return

The specified date/time formatted according to the specified time_facet

Parameters

pt: Boost ptime of a specific moment in time
facet: Boost time_facet to be applied
localeName: - String that represents the locale to be used

Friends

bool operator==(const Epochstamp &lhs, const Epochstamp &rhs)¶

Relational operations between timestamps

Return

bool

Parameters

other: Epochstamp object

class Exception¶

#include <Exception.hh>

Karabo’s main exception class. Inherits from std::exception.

Inherits from std::exception

Public Functions

Exception(const std::string &message, const std::string &type, const std::string &filename, const std::string &function, int lineNumber, const std::string &detailsMsg = std::string())¶: Constructor using message, exception type, filename, function name, line number and possible detailsMsg

virtual ~Exception()¶: Destructor

void msg(std::ostream &os = std::cerr) const¶: Explicit output function. In contrast to the inherited what() function this function also lists memorized/traced exceptions.

const char *what() const¶

Overrides std::exception.

Same as detailedMsg() except returning ‘const char*’, not ‘std::string’. The returned pointer is valid as long as exception object is alive or until what() is called again. Also clears the exception stack.

string userFriendlyMsg(bool clearTrace = true) const¶

This function is intended to be used for example in GUIs.

Parameters

clearTrace: Whether to clear the exception stack, default is true.

string detailedMsg() const¶

This function returns the full error stack with all information.

Clears the exception stack.

Return: The stack of exceptions as string, incl. source code line number.

const std::string &type() const¶: The type of the exception

const std::string &details() const¶

The details of the exception - without trace.

Some exceptions do not offer to provide details, then an empty string is returned. Stack is not touched/cleared.

Public Static Functions

void memorize()¶

Use this function if you want to just memorize the exception but keep on running. This function should be used for exceptions thrown in multi-threaded context, as C++’s intrinsic exception handling is not thread safe.

Example: TODO

void clearTrace()¶: Clears the trace of memorized messages for current thread

void showTrace(std::ostream &os = std::cerr)¶: Shows all memorized messages.

Protected Functions

template <class T>
std::string toString(const T &value)¶: Small helper function

Protected Static Functions

void format(std::ostream &os, const ExceptionInfo &exceptionInfo, const std::string &spacing)¶

Formats the exception content

See

ExceptionInfo stuct

Parameters

os: Any output stream to that the exception content will be added
exceptionInfo: Content of an exception,

void addToTrace(const ExceptionInfo &value)¶: Adds exception information to trace for current thread

Friends

KARABO_DECLSPEC friend std::ostream& operator<<(std::ostream & os, const Exception & Exception): Automatic output using the << operator

template <class AbstractClass>

class Factory¶

#include <Factory.hh>

A factory for managing Karabo classes.

The factory uses something like a hidden (private) Singleton-Pattern. This solves the problem of static initialization order but leaves a simple looking API to the user.

A single instance of a factory holds the function objects to all registered constructors. Constructors with zero or more parameters may be registered and directly called.

Public Static Functions

template <class ConcreteClass>

static void registerClass(const std::string &factoryKey)¶

Register a base class identified by a key in the factory system

Parameters

factoryKey:

template <class ConcreteClass, typename A1>

static void registerClass(const std::string &factoryKey)

Register a class A1 derived from ConcreteClass identified by a key in the factory system

Parameters

factoryKey:

static std::shared_ptr<AbstractClass> create(const std::string &factoryKey)¶

Create an Object of the class identified by factoryKey

Return

a shared pointer to the created object

Parameters

factoryKey:

template <typename A1>

static std::shared_ptr<AbstractClass> create(const std::string &factoryKey, const A1 &a1)¶

Create an Object of the class identified by factoryKey

Return

a shared pointer to the created object cast to A1

Parameters

factoryKey:

static std::vector<std::string> getRegisteredClasses()¶

Return the classIds registered in the factory

Return

static bool has(const std::string &factoryKey)¶

Check if a class identified by factoryKey is known to the factory

Return

Parameters

factoryKey:

class FileNotFoundIOException¶

#include <Exception.hh>

FileNotFoundIOException

Inherits from karabo::util::IOException

template <class Impl>
class FromType¶: #include <FromType.hh>
Returns a karabo::util::Types::ReferenceType from an alternate representation as specified by the template parameter, e.g. FromType<Literal>(“INT32”) will return karabo::util::Types::INT32.

template <class Derived>

class GenericElement¶

#include <GenericElement.hh>

The GenericElement class is a base class for various element types: simple, vector, choice, list and single.

Subclassed by karabo::util::LeafElement< Derived, ValueType >, karabo::xms::SlotElementBase< Derived >

Public Functions

virtual Derived &key(const std::string &name)¶

The key method serves for setting up a unique name for the element. Example:

SOME_ELEMENT(expected)
        .key("type")
        ...
        .commit();

Return

reference to the Element (to allow method’s chaining)

Parameters

name: Unique name for the key - can be a nested path if all but its last sub-key are added as node elements before. Must not be an empty string.

template <class AliasType>

Derived &alias(const AliasType &alias)¶

The alias method serves for setting up just another name for the element. Note: this another name may not be necessarily a string. Just any type!

Return

reference to the Element (to allow method’s chaining)

Parameters

alias: Another name for this element

Derived &tags(const std::vector<std::string> &tags)¶

The tags method allows to tag some expected parameters for later grouping/sorting

Return

reference to the Element (to allow method’s chaining)

Parameters

tags: a vector of strings

Derived &tags(const std::string &tags, const std::string &sep = " ,;")¶: The tags/b> method allows to tag some expected parameters for later grouping/sorting

Derived &displayedName(const std::string &name)¶

The displayedName method serves for setting up an user friendly name for the element to be used by GUI Example:

SOME_ELEMENT(expected)
        ...
        .displayedName("Connection Type")
        ...
        .commit();

Return

reference to the Element (to allow method’s chaining)

Parameters

name: User friendly name for the element

Derived &description(const std::string &description)¶

The description method serves for setting up a description of the element Example:

SOME_ELEMENT(expected)
        ...
        .description("Decide whether the connection is used to implement a TCP Server or TCP Client")
        ...
        .commit();

Return

reference to the Element (to allow method’s chaining)

Parameters

desc: Short description of the element

Derived &observerAccess()¶

The observerAccess method serves for setting up the required access level attribute to be OBSERVER.

Return: reference to the Element (to allow method’s chaining)

Derived &userAccess()¶

The userAccess method serves for setting up the required access level attribute to be USER.

Return: reference to the Element (to allow method’s chaining)

Derived &operatorAccess()¶

The operatorAccess method serves for setting up the required access level attribute to be OPERATOR.

Return: reference to the Element (to allow method’s chaining)

Derived &expertAccess()¶

The expertAccess method serves for setting up the required access level attribute to be EXPERT.

Return: reference to the Element (to allow method’s chaining)

Derived &adminAccess()¶

The adminAccess method serves for setting up the required access level attribute to be ADMIN.

Return: reference to the Element (to allow method’s chaining)

Derived &overwriteRestrictions(OverwriteElement::Restrictions &restrictions)¶

The overWriteRestrictions allows for setting restrictions to overwrite element. Any attributes specified here cannot be altered through use of overwrite element.

After execution restrictions contains the new applicable restrictions, e.g. those resulting from merging with previously existing restrictions. This means, one can add restrictions but not cancel existing ones.

Derived &setSpecialDisplayType(const std::string &displaytype)¶

The setSpecialDisplayType allows for setting modification of the displayType of the element

This attribute is a string and contains a hint to graphical user interfaces that a display mode is possible.

Return

reference to the Element (to allow method’s chaining)

Parameters

displayType:

virtual void commit()¶: The commit method injects the element to the expected parameters list. If not called the element is not usable. This must be called after the element is fully defined.

class HardwareException¶

#include <Exception.hh>

The HardwareException handles exceptions that are caused by any connected hardware

Inherits from karabo::util::Exception

class Hash¶

#include <Hash.hh>

A generic key value container that supports ordering and attributes.

Hash container:

The Hash is a heterogeneous generic key/value container that associates a string key to a value of any type.
The Hash is a core data structure in Karabo software framework, and is widely used in the karabo system.
For instance, exchanging data and configurations between two or more entities (devices, GUI), database interface (store and retrieval ), meta-data handling, etc.
The Hash class is much like a XML-DOM container with the difference of allowing only unique keys on a given tree-level.
Like and XML DOM object, the Hash provides a multi-level (recursive) key-value associative container, where keys are strings and values can be of any C++ type.

Concept:

Provide recursive key-value associative container (keys are strings and unique, values can be of any type)
Preserve insertion order, while optimized for random key-based lookup. Different iterators are available for each use case.
Like in XML, each hash key can have a list of (key-value) attributes (attribute keys are strings and unique, attribute values can be of any type).
Seamless serialization to/from XML, Binary, HDF5, etc.
Usage: configuration, device-state cache, database interface (result-set), message protocol, meta-data handling, etc.
Templated set, get for retrieving values from keys. Assumes recursursion on “.” characters in key by default. Seperator can be specified per function call.
Exposed iterators will a sequential iterator (insertion order) and a alpha-numeric order iterator.
Each iterator provides access to its key, value, and attributes in form of a Hash::Node and can thus be used for recursive traversal.
Insertion of a non-existing key leads to new entry whilst insertion of an existing key will only update (merge) the corresponding value/attributes.
Additional functionality include: list of paths, clear/erase, find, merge, comparison, etc.

Subclassed by karabo::util::NDArray, karabo::xms::Memory::MetaData

Public Functions

Hash::const_iterator begin() const¶: Insertion order iterator (i.e. list iterator)

Hash::const_map_iterator mbegin() const¶: Alpha-numeric order iterator (i.e. map iterator)

boost::optional<const Hash::Node&> find(const std::string &path, const char separator = k_defaultSep) const¶

Lookup for the hash element identified by “path”. If the node exists, it returns a reference to it wrapped in boost::optional object. Otherwise, uninitialized boost::optional object is returned.

Return

Hash::Node wrapped in boost::optional

Parameters

path: sequence of keys to the searched for element
separator: key separation char

Hash()¶

The default path separator for nested Hash.

Default constructor creates an empty hash

Example:

Hash hash;

Hash(const std::string &path)¶

Use this constructor to create a hash with one key/value pair where value is just an empty hash Example: The code like this …

Hash hash(myKey);

… is equivalent to …

Hash hash(myKey, Hash());

Parameters

key: Name of empty child

template <typename V1, typename… Args>

Hash(const std::string &path1, V1 &&value1, Args&&... args)¶

Constructor for different numbers of key-value pairs as arguments Create and initialize a hash with multiple key-value pairs in a single call, supporting also move semantics

Parameters

key1: A string hash key
value1: Any object as (r- or l-)value
key2: Optionally another key

value2: Optionally another object as (r- or l-)value … Example:

Hash hash("firstKey", 1, "secondKey", 2, "thirdKey", 3, "fourthKey", 4, "fifthKey", 5, "sixthKey", 6);

~Hash()¶: Destructor

Hash(const Hash &other)¶: Copy constructor

Hash &operator=(const Hash &other)¶: Assignment of “lvalue”

Hash(Hash &&other)¶: Move constructor

Hash &operator=(Hash &&other)¶: Assignment of “rvalue”

Hash &operator+=(const Hash &other)¶

Merge the current hash with another one

Parameters

other: Hash object

Hash &operator-=(const Hash &other)¶

Subtract another hash from the current one

Parameters

other: Hash object

size_t size() const¶

Return the number of key elements in the hash

Return: size_t

bool empty() const¶

Check if the hash contains any keys or not.

Return: true if hash is empty, false otherwise

void clear()¶

Remove all the keys from the hash

Return: No

bool erase(const std::string &path, const char separator = k_defaultSep)¶

Remove the element identified by ‘path’ if it exists. Otherwise, do nothing. If ‘path’ is a composite element, all its descendents are removed as well. The path up to the last part of ‘path’ is not removed. Example 1: erase (“a.b.c”) will remove “c”, but “a.b” should not be removed even if “c” is the only child of “a.b”. If ‘path’ refers to a Hash inside a vector<Hash>, that element of the vector is erased, i.e. the vector shrinks. Example 2: erase (“a.b[1]”) will remove element 1 of “b”. If “b” had a size above 2, the old element “b[2]” will now be referred to as “b[1]”.

Return: true if key exists, otherwise false

void erasePath(const std::string &path, const char separator = k_defaultSep)¶

Remove the element identified by ‘path’ if it exists. If ‘key’ is composite (e.g. “a.b.c”) and the last component (“c”) is the only child of its parent, the parent is removed as well. This removal is recursively continued to the root. Example 1: erasePath(“a.b.c”) will remove “c” and “b” will be removed as well if “c” is the only child of “a.b”. If “a.b.c” is the only element in the Hash, then erasePath(“a.b.c”) will result in an empty hash. If ‘path’ refers to a Hash inside a vector<Hash>, that element of the vector is erased, i.e. the vector shrinks. If the element was the only one in the vector, the vector will be removed as well Example 2: erase (“a.b[0]”) will remove element 0 of “b”. If “b” had a size of 1, b will be removed completely (and ‘a’ as well in case of no other child).

Return: No

template <template< class T, class All=std::allocator< T > > class container>

void getKeys(container<std::string> &result) const¶

Returns all the keys in the hash in the provided container (vector, list, set, …) Keys in inner-hashes are not included

Parameters

container:

template <template< class T, class All=std::allocator< T > > class container>

void getPaths(container<std::string> &result, const char separator = k_defaultSep) const¶

Returns all root-to-leaves paths in hash in the provided container (vector, list, set, …) This function goes recursively through the whole hash and should just be called for frequently lookup in log(n) ????????????????????

Return

std::vector<std::string> object

Parameters

container:

bool has(const std::string &path, const char separator = k_defaultSep) const¶

Check if the key ‘key’ exist in hash

Return

true if key exists, false otherwise

Parameters

key: A string hash key

template <typename ValueType, typename… Args>
void setMulti(const std::string &key, ValueType &&value, Args&&... args)¶: Set an arbitray number of key/value pairs, internally using Hash::set(..) with the default separator

Hash::Node &setNode(const Node &srcElement)¶: Clone the content (key, value, attributes) of another elements. This function use the source element’s key, NOT his full path.

template <typename ValueType>

ValueType *bindPointer(const std::string &path, const char separator = k_defaultSep)¶

Bind a (newly created) object in the map into and external variable Optimization: This is useful in order to avoid the later copy of the value into std::any, in the hash::set(key, value). This function provides a pointer to the object in the map where you can build your data directly.

Return

A pointer to the internal object Example:

Parameters

key: A string hash key

template <typename ValueType>

const ValueType &get(const std::string &path, const char separator = k_defaultSep) const¶

Retrieve a constant reference to the value of element identified by ‘key’

Return

The associated value

Note

Differently from Hash::getAs, Hash::get (and its overloads) doesn’t perform any conversion while retrieving a node value. If the node type specified on the get call doesn’t match the actual node type, a cast exception will be thrown.

Parameters

key: A string key

template <typename ValueType>

ValueType &get(const std::string &key, const char separator = k_defaultSep)¶

Retrieve a (non-const) reference to the stored value of a given key

Return

The associated value

Parameters

key: A string key

template <typename ValueType>

void get(const std::string &path, ValueType &value, const char separator = k_defaultSep) const¶

Retrieve (non-const) reference to the stored value into second parameter

Return

void

Parameters

key: A string key
value: Any object that will be filled by reference

template <typename ValueType>

ValueType getAs(const std::string &path, const char separator = k_defaultSep) const¶

Casts the the value of element identified by “path” from its original type to another different target type. Throws CastException if casting fails, i.e. not possible or unsafe

Return

value

Note

Hash::getAs (and its overload for vector elements) converts the node values to the target type specified by the caller. As an example, retrieval of unsigned integer values from nodes that are signed integers will perform the same implicit conversion performed by C/C++ (e.g., -1 assigned to an INT32 key will be retrieved as 4.294.967.295 when requested as an UINT32).

Parameters

path:
separator:

const Hash::Node &getNode(const std::string &path, const char separator = k_defaultSep) const¶

Return the internal Hash node element designated by “path”

Return

Hash::Node element

Parameters

path:
separator:

template <typename ValueType>

bool is(const std::string &path, const char separator = k_defaultSep) const¶

Predicate function calculating if the type of the value associated with the key is of a specific type in template parameter

Return

true or false

Parameters

key: The key having associated value and the type of this value we want to test against template parameter

bool is(const std::string &path, const Types::ReferenceType &type, const char separator = k_defaultSep) const¶

Predicate function calculating if the value associated with key is of type type.

Return

true or false

Parameters

key: Some string
type: Some type from Types::Type enumeration

Types::ReferenceType getType(const std::string &path, const char separator = k_defaultSep) const¶

Function to obtain value type information

Return

The typeId as defined in

See

Types.hh

Parameters

key: The key to the value of which type information should be returned

void merge(const Hash &other, const MergePolicy policy = REPLACE_ATTRIBUTES, const std::set<std::string> &selectedPaths = std::set<std::string>(), char separator = k_defaultSep)¶

Merges another hash into this one Creates new nodes, if they do not already exists. Creates new leaves, if they do not already exist. Existing leaves will be replaced by the new hash.

Parameters

hash: Another hash to be merged into current hash
policy: Whether to replace attributes by those merged in or to merge them
selectedPaths: If not empty, only merge these paths
separator: The separator for nested keys in selectedPaths

void subtract(const Hash &other, const char separator = k_defaultSep)¶

Subtracts from current hash all nodes that can be found in other hash given as argument.

Return

the current hash is shrinked in place, the other hash is untouched

Parameters

other: hash used for defining the candidates for subtraction
separator.: The default separator is k_defaultSep

void flatten(Hash &flat, const char separator = k_defaultSep) const¶

Flattens a hierarchical Hash into “one-level”, flat Hash object

Return: A Hash having keys that are all leaves

void unflatten(Hash &tree, const char separator = k_defaultSep) const¶

Arranges flat Hash object in a hierarchy using separator symbol (default: “.”) during parsing the keys to recognize a hierarchy

Return

A Hash object containing keys with no separator symbols

Parameters

sep: An optional separator symbol (default: “.”)

bool hasAttribute(const std::string &path, const std::string &attribute, const char separator = k_defaultSep) const¶

Check if the element identified by “path” has an attribute called “attribute”

Return

bool

Parameters

path:
attribute:
separator:

template <typename ValueType>

const ValueType &getAttribute(const std::string &path, const std::string &attribute, const char separator = k_defaultSep) const¶

Return the value of the attribute called “attribute” of the element identified by “path”

Return

bool

Parameters

path:
attribute:
separator:

template <typename T>

T getAttributeAs(const std::string &path, const std::string &attribute, const char separator = k_defaultSep) const¶

Casts the value of the attribute called “attribute” of the element identified by “path” from its original type to another different target type. Throws CastException if casting fails, i.e. not posible or unsafe

Return

value

Parameters

path:
attribute:
separator:

std::any &getAttributeAsAny(const std::string &path, const std::string &attribute, const char separator = k_defaultSep)¶

Return the value of the attribute called “attribute” of the element identified as std::any.

Return

std::any

Parameters

path:
attribute:
separator:

const Hash::Attributes &getAttributes(const std::string &path, const char separator = k_defaultSep) const¶

Return the list of attributes of the element identified by “path”

Return

Hash::Attributes

Parameters

path:
separator:

template <typename ValueType>

void setAttribute(const std::string &path, const std::string &attribute, const ValueType &value, const char separator = k_defaultSep)¶

Set the value of an attribute called “attribute” of the element identified by “path”

Parameters

path:
attribute:
value:
separator:

template <typename ValueType>

void setAttribute(const std::string &path, const std::string &attribute, ValueType &&value, const char separator = k_defaultSep)¶

Set the value of an attribute called “attribute” of the element identified by “path”

Parameters

path:
attribute:
value:
separator:

void setAttributes(const std::string &path, const Attributes &attributes, const char separator = k_defaultSep)¶

Assign of list of attributes (i.e. Hash::Attributes container) to the element identified by “path”

Parameters

path:
attributes:
separator:

void setAttributes(const std::string &path, Attributes &&attributes, const char separator = k_defaultSep)¶

Assign of list of attributes (i.e. Hash::Attributes container) to the element identified by “path”

Parameters

path:
attributes: to move from
separator:

bool operator==(const Hash &other) const¶

Checks if this Hash is similar to other.

A Hash is considered similar to another if both have the same number of elements, of the same type and in the same order.

Return

true if both hashes are similar.

Note

: this is not the full equality operator as the values of the elements are not considered.

Parameters

other: the Hash this Hash will be compared to.

bool fullyEquals(const Hash &other, bool orderMatters = true) const¶

Checks if this Hash is equal to other.

A Hash is considered fully equal to another if both are similar and their corresponding elements have the same keys, values and attributes.

Return

bool

Parameters

other: Hash to compare with
orderMatters: if true (default) order of keys is relevant as well

template <class Visitor>

bool visit(Visitor &visitor)¶

Implement the visitor pattern

Return

bool

Parameters

visitor:

Private Functions

template <typename HashType>

Hash::Node &setHash(const std::string &path, HashType value, const char separator = k_defaultSep)¶

Internal helper to avoid code duplication for template specialisations of set(path, hashValue, separator).

HashType shall be const reference or lvalue reference of Hash or Hash derived classes: ‘const Hash&’, ‘Hash&&’, ‘const NDArray&’, etc.

void setMulti() const¶: End point for setMulti(..) with variadic templates

Private Static Functions

std::set<std::string> selectChildPaths(const std::set<std::string> &paths, const std::string &childKey, char separator)¶: Out of ‘paths’ select those that belong to child with ‘childKey’, e.g. out of [“a”, “b.c”, “b.d.e”] return [“c”, “d.e”] if childKey == “b” and separator == k_defaultSep.

bool keyIsPrefixOfAnyPath(const std::set<std::string> &paths, const std::string &key, char separator, unsigned int size)¶: True if the first key (separated by ‘separator’) of any of ‘paths’ matches ‘key’. A first key that contains an index also matches (indirectly) ‘key’ without index if index < ‘size’, i.e. path “a[0].g” matches key “a” if ‘size’ >= 1, but not if ‘size’ == 0.

std::set<unsigned int> selectIndicesOfKey(unsigned int targetSize, const std::set<std::string> &paths, const std::string &key, char separator)¶: For all ‘paths’, check whether their first key matches ‘key’ (as in keyIsPrefixOfAnyPath). If it does indirectly (see keyIsPrefixOfAnyPath), append the index specified behind it to the result, except if there is also a direct match - then the result is empty: Paths = {a[0], b, a[2]} and key = a ==> return [0,2] Paths = {a[0], b, a} and key = a ==> return [] Indices >= ‘targetSize’ are ignored.

void mergeAttributes(Hash::Node &targetNode, const Hash::Attributes &attrs, Hash::MergePolicy policy)¶: Merge ‘attrs’ to ‘targetNode’ according to merge ‘policy’.

void mergeTableElement(const Hash::Node &source, Hash::Node &target, const std::set<std::string> &selectedPaths, char separator)¶: Merge two vector<Hash> nodes that represent table elements, i.e. the content of ‘source’ replaces the content of ‘target’. The ‘selectedPaths’ with their ‘separator’ are respected. Note that the ‘selectedPaths’ are those that selected ‘source’ for merging, i.e. begin with the key of ‘source’, possibly suffixed by indices.

void mergeVectorHashNodes(const Hash::Node &source, Hash::Node &target, Hash::MergePolicy policy, const std::set<std::string> &selectedPaths, char separator)¶: Merge two ordinary vector<Hash> nodes, respecting the ‘selectedPaths’ with their ‘separator’. Note that the ‘selectedPaths’ are those that selected ‘source’ node for merging, i.e. begin with the key of ‘source’, possibly suffixed by some indices.

Friends

std::ostream &operator<<(std::ostream &os, const Hash &hash)¶

Serialize a hash to standard std::ostream object

Parameters

visitor:

class HashFilter¶

#include <HashFilter.hh>

This class provides methods to filter a configuration Hash by properties of the Schema describing it.

Public Static Functions

void byTag(const Schema &schema, const Hash &config, Hash &result, const std::string &tags, const std::string &sep = ",")¶

Filter a configuration Hash by the tags defined in the Schema describing it and return the filtered result

Parameters

schema: describing the configuration Hash
config: input Hash to be filtered
result: filtered output Hash
tags: stringified list of tags. Elements in the schema having any of the tags in this list are included in the output Hash
sep: separator used in the list of tags

void byAccessMode(const Schema &schema, const Hash &config, Hash &result, const AccessType &value)¶

Filter a configuration Hash by the access mode defined in the Schema describing it and return the filtered result

Parameters

schema: describing the configuration Hash
config: input Hash to be filtered
result: filtered output Hash
value: AccessMode to filter against

class HdfIOException¶: Inherits from karabo::util::IOException

class ImageDimensionException¶

#include <Exception.hh>

The ImageDimensionException handles exceptions raised due to illegal image dimensions

Inherits from karabo::util::ImageException

class ImageException¶

#include <Exception.hh>

The ImageException handles an generic image exception

Inherits from karabo::util::Exception

Subclassed by karabo::util::ImageDimensionException, karabo::util::ImageFormatException, karabo::util::ImageTypeException

class ImageFormatException¶

#include <Exception.hh>

The ImageFormatException handles exceptions raised due to unsupported image formats

Inherits from karabo::util::ImageException

class ImageTypeException¶

#include <Exception.hh>

The ImageTypeException handles exceptions raised due to imcompatible image types

Inherits from karabo::util::ImageException

class InitException¶

#include <Exception.hh>

The InitException handles exceptions raised during any initialization procedures

Inherits from karabo::util::Exception

Subclassed by karabo::util::MemoryInitException

class IOException¶

#include <Exception.hh>

The IOException handles exceptions raised related to Input/Output routines

Inherits from karabo::util::Exception

Subclassed by karabo::util::FileNotFoundIOException, karabo::util::HdfIOException

template <class T>
struct is_shared_ptr¶: Inherits from false_type

template <class T>
template<> struct is_shared_ptr<std::shared_ptr<T>>¶: Inherits from true_type

template <typename Base, typename Derived>
struct is_virtual_base_of¶: Inherits from std::conjunction< std::is_base_of< Base, Derived >, std::negation< can_static_cast< Base *, Derived *> > >

template <class Derived, typename ValueType>

class LeafElement¶

#include <LeafElement.hh>

The LeafElement represents a leaf and can be of any (supported) type

Inherits from karabo::util::GenericElement< Derived >

Public Functions

Derived &unit(const UnitType &unit)¶

The unit method serves for setting up a name for units

Return

reference to the Element (to allow method’s chaining)

Parameters

unitName: The name describing units

Derived &metricPrefix(const MetricPrefixType &metricPrefix)¶

The metricPrefix describes the metric for the unit (e.g. milli, mega, femto, etc.)

Return

reference to the Element (to allow method’s chaining)

Parameters

metricPrefix: The metric prefix

Derived &allowedStates(const std::vector<karabo::util::State> &value)¶

The allowedStates method serves for setting up allowed states for the element

Return

reference to the Element (to allow method’s chaining)

Parameters

states: A string describing list of possible states.
sep: A separator symbol used for parsing previous argument for list of states

virtual Derived &assignmentMandatory()¶

The assignmentMandatory method serves for setting up a mode that requires the value of the element always being specified. No default value is possible.

Return: reference to the Element (to allow method’s chaining)

virtual DefaultValue<Derived, ValueType> &assignmentOptional()¶

The assignmentOptional method serves for setting up a mode that allows the value of element be optional, so it can be omitted in configuration. Default value is injected if defined. If you chain functions for definition of expected parameters the next function may be only defaultValue or noDefaultValue. When the default value is not specified (noDefaultValue) you must always check if the parameter has a value set in delivered User configuration. Example:

SOME_ELEMENT(expected)
        ...
        .assignmentOptional().defaultValue("client")
        ...
        .commit();

Return: reference to DefaultValue object allowing proper defaultValue method chaining.

virtual DefaultValue<Derived, ValueType> &assignmentInternal()¶

The assignmentInternal method serves for setting up the element to be internal. In the code it behaves like optional parameter but it is not exposed to the user. It is omitted when the schema is serialized to XSD. The value of this parameter should be defined programmatically. Conceptually, internal parameter with internal flag can be treated as an argument to the constructor.

Return: reference to DefaultValue (to allow method’s chaining)

virtual Derived &init()¶

The init method serves for setting up an access type property that allows the element to be included in initial schema.

Return: reference to the Element (to allow method’s chaining)

virtual Derived &reconfigurable()¶

The reconfigurable method serves for setting up an access type property that allows the element to be included in initial, reconfiguration and monitoring schemas.

Return: reference to the Element (to allow method’s chaining)

virtual ReadOnlySpecific<Derived, ValueType> &readOnly()¶

The readOnly method serves for setting up an access type property that allows the element to be included in monitoring schema only.

Return: reference to the Element (to allow method’s chaining)

virtual Derived &daqPolicy(const DAQPolicy &policy)¶

The daqPolicy sets the DAQ policy for a parameter.

Return: reference to the Element (to allow method’s chaining)

class ListElement¶

#include <ListElement.hh>

An element allowing choice-access to a list of factorized classes.

The ListElement can be configured to hold a number of factorized classes. Two methods exist for adding classes to the list of choices the ChoiceElement knows of:

ListElement::appendNodesOfConfigurationBase is used if another class of a type known to the factory system is to be added
ListElement::appendAsNode is used to append the entries of a NodeElement defined in the same expectedParameter function as the choice element

In either case, it will add a configuration entry to a Node List

Inherits from karabo::util::GenericElement< ListElement >

Public Functions

ListElement &min(const int minNumNodes)¶

Minimum number of nodes the list element should hold - inclusive

Return

Parameters

minNumNodes:

ListElement &max(const int maxNumNodes)¶

Maximum number of nodes the list element should hold - inclusive

Return

Parameters

maxNumNodes:

template <class ConfigurationBase>

ListElement &appendNodesOfConfigurationBase()¶

Append the expected parameters of another class of type ConfigurationBase. The class needs to be known by the factory system. It will be identified by its Karabo ClassId in the list.

Return

template <class T>

ListElement &appendAsNode(const std::string &nodeName = "")¶

Append the entries found underneath a NodeElement identified by key. The node element needs to be defined prior to and in the same expected parameter function as the ListElement.

Return

Parameters

nodeName: identifying the node, i.e. the key of the node.

virtual ListElement &assignmentMandatory()¶

The assignmentMandatory method serves for setting up a mode that requires the value of the element always being specified. No default value is possible.

Return: reference to the Element (to allow method’s chaining)

virtual DefaultValue<ListElement, std::vector<std::string>> &assignmentOptional()¶

The assignmentOptional method serves for setting up a mode that allows the value of element be optional, so it can be omitted in configuration. Default value is injected if defined. If you chain functions for definition of expected parameters the next function may be only defaultValue or noDefaultValue. When the default value is not specified (noDefaultValue) you must always check if the parameter has a value set in delivered User configuration.

Return: reference to DefaultValue object allowing proper defaultValue method chaining.

virtual ListElement &init()¶

The init method serves for setting up an access type property that allows the element to be included in initial schema.

Return: reference to the Element (to allow method’s chaining)

virtual ListElement &reconfigurable()¶

The reconfigurable method serves for setting up an access type property that allows the element to be included in initial, reconfiguration and monitoring schemas.

Return: reference to the Element (to allow method’s chaining)

class LockException¶

#include <Exception.hh>

The LockException handles exceptions that result from not being able to acquire a lock

Inherits from karabo::util::Exception

class LogicException¶

#include <Exception.hh>

The LogicException handles exceptions that are raised by any unexpected logical behaviour

Inherits from karabo::util::Exception

class MemoryInitException¶

#include <Exception.hh>

The MemoryInitException handles exceptions raised during any memory initializations

Inherits from karabo::util::InitException

class MessageException¶

#include <Exception.hh>

The MessageException handles exceptions that are caused during messaging

Inherits from karabo::util::Exception

struct MetaData¶: #include <DataLogUtils.hh>
A structure defining meta data as used by the data loggers

struct MetaSearchResult¶: #include <DataLogUtils.hh>
A structure defining meta data as used by the data logger’s search results

class NDArray¶

#include <NDArray.hh>

A class representing multi-dimensional data in Karabo that seaminglessy converts to numpy.NDArray.

The NDArray class is intended to store any multidimensional data occurring in Karabo. Internally it holds the data in a ByteArray. It is a Hash-derived structure, which means it serializes into a karabo::util::Hash. Its meta-data is chosen such that it can be seamlessly converted into a numpy.NDArray

Inherits from karabo::util::Hash

Public Functions

NDArray(const Dims &shape = Dims(), const karabo::util::Types::ReferenceType &type = karabo::util::Types::DOUBLE, const bool isBigEndian = karabo::util::isBigEndian())¶

This constructor creates an empty NDArray

Parameters

shape:
type:
isBigEndian:

template <typename T>

NDArray(const Dims &shape, const T &fill, const bool isBigEndian = karabo::util::isBigEndian())¶

This constructor creates an NDArray where all values are initialized with a fill value

Parameters

shape:
fill:
isBigEndian:

template <typename T>

NDArray(const T *dataPtr, const size_t numElems, const Dims &shape = Dims(), const bool isBigEndian = karabo::util::isBigEndian())¶

This constructor copies data from the provided memory location. Internally the data is kept as shared pointer.

Parameters

dataPtr: Typed address to a stretch of contiguous memory
numElems: Number of elements (of type T)
shape: Shape information
isBigEndian: Endianess flag

template <typename InputIterator>

NDArray(InputIterator first, InputIterator last, const Dims &shape = Dims(), const bool isBigEndian = karabo::util::isBigEndian())¶

This constructor copies data from the provided iterator range. Data type is deduced from the value_type of the InputIterator. The range from ‘first’ (included) to ‘last’ (excluded) has to be valid range.

Parameters

first: Begin of range
last: End of range (i.e. points one behind as vector.end())
shape: Shape information
isBigEndian: Endianess flag

template <typename T, typename D>

NDArray(const T *dataPtr, const size_t numElems, const D &deleter, const Dims &shape = Dims(), const bool isBigEndian = karabo::util::isBigEndian())¶

This constructor does NOT copy data. Only a view on the external memory is established. A functor for dealing with the viewed on memory must be provided in case this object gets destructed.

Parameters

dataPtr: Typed address to a stretch of contiguous memory
numElems: Number of elements (of type T)
deleter: A functor defining the deletion behavior
shape: Shape information
isBigEndian: Endianess flag

NDArray(const DataPointer &ptr, const karabo::util::Types::ReferenceType &type, const size_t &numElems, const Dims &shape = Dims(), const bool isBigEndian = karabo::util::isBigEndian(), bool copy = false)¶

Non-templated copy/no-copy construction depending on ‘copy’ flag (default is false).

Parameters

ptr: Shared_ptr to external memory location
type: Type of provided data
numElems: Number of elements of provided type
shape: Shape information
isBigEndian: Endianess flag

void setShape(const Dims &shape)¶

Set the schape of the array

Parameters

shape:

size_t size() const¶: The number of items in the array.

size_t byteSize() const¶: The total size of the array, in bytes.

size_t itemSize() const¶: The size of each item, in bytes.

template <typename T>

const T *getData() const¶

Get the data contained in the array as a pointer

Return

const NDArray::DataPointer &getDataPtr() const¶

Get a shared pointer to the underlying ByteArray data

Return

ByteArray getByteArray()¶

Return the underlying ByteArray

Return

Dims getShape() const¶

Return the shape of the array as a karabo::util::Dins object

Return

bool isBigEndian() const¶

Evaluate if the data contained in the array is big endian

Return: true if big endian, false if little ednian

void toLittleEndian()¶: Convert data to little endian

void toBigEndian()¶: Convert data to big endian

class NDArrayElement¶: Inherits from karabo::util::CustomNodeElement< NDArrayElement, NDArray >

class NetworkException¶

#include <Exception.hh>

The NetworkException handles exceptions that are caused by network protocol related libraries (BoostAsio, SNMP, …)

Inherits from karabo::util::Exception

class NodeElement¶

#include <NodeElement.hh>

The NodeElement groups other elements into a hierarchy.

The NodeElement can be used to create hierarchies in the expected parameter section of a device.

Example:

NODE_ELEMENT(expected).key("myNode")
         .displayedName("This is a Node")
         .commit();

SOME_ELEMENT(expected).key("myNode.myKeyA")
        ...
        .assignmentOptional().defaultValue("client")
        ...
        .commit();

SOME_ELEMENT(expected).key("myNode.myKeyB")
        ...
        .assignmentOptional().defaultValue("client")
        ...
        .commit();

creates the following hierarchy:

MyNode -> myKeyA -> myKeyB

NodeElements may contain subnodes so that arbitrary compley hierarchies up to a maximum aggregated key-length of 120 characters are possible

NodeElements may further be used to provide options for karabo::util::ChoiceElement and list entries for karabo::util::ListElement

Inherits from karabo::util::GenericElement< NodeElement >

Public Functions

template <class ConfigurableClass>

NodeElement &appendParametersOfConfigurableClass(const std::string &classId)¶

Insert the expected parameters of another class of type ConfigurationBase. The class needs to be known by the factory system.

Return

Parameters

classId: identifying the clas

template <class T>

NodeElement &appendParametersOf()¶

Insert the expected parameters of another class of type ConfigurationBase. The class needs to be known by the factory system.

Return

NodeElement &appendSchema(const Schema &schema)¶

Append the elements specified in a Schema to the node

Return

Parameters

schema:

NodeElement &setAllowedActions(const std::vector<std::string> &actions)¶

Specify one or more actions that are allowed on this node.

If a Karabo device specifies allowed actions for a node, that means that it offers a specific slot interface to operate on this node. Which allowed actions require which interface will be defined elsewhere.

Return: reference to the Element (to allow method’s chaining)

class NotImplementedException¶

#include <Exception.hh>

The NotImplementedException handles exceptions that are raised due to unimplemented functions/class calls

Inherits from karabo::util::Exception

class NotSupportedException¶

#include <Exception.hh>

The NotImplementedException handles exceptions that are raised by requesting unsupported features

Inherits from karabo::util::Exception

template <class KeyType, class MappedType>

class OrderedMap¶

#include <OrderedMap.hh>

a associative key-value container maintaining insertion order

The OrderedMap provides for an insertion-order aware key-value container which has similar access, modification and query methods as std::map. The differences are that knowledge of insertion order is maintained, values may be of different and any type and iterator for both key and insertion order are provided.

Public Functions

iterator begin()¶

Return an iterator to the first element of the OrderedMap

Return

iterator end()¶

Return an iterator past the last element of the OrderedMap

Return

OrderedMap()¶: Construct an empty OrderedMap

OrderedMap(const OrderedMap<KeyType, MappedType> &other)¶

OrderedMap copy constructr

Parameters

other:

template <typename T>

OrderedMap(const KeyType &key1, const T &value1)¶

Construct an ordered map with one element in it identified by key

Parameters

key1:
value1:

template <typename T, typename U>

OrderedMap(const KeyType &key1, const T &value1, const KeyType &key2, const U &value2)¶

Construct an ordered map with two elements in it identified by keys

Parameters

key1:
value1:
key2:
value2:

template <typename T, typename U, typename V>

OrderedMap(const KeyType &key1, const T &value1, const KeyType &key2, const U &value2, const KeyType &key3, const V &value3)¶

Construct an ordered map with three elements in it identified by keys

Parameters

key1:
value1:
key2:
value2:
key3:
value3:

template <typename T, typename U, typename V, typename X>

OrderedMap(const KeyType &key1, const T &value1, const KeyType &key2, const U &value2, const KeyType &key3, const V &value3, const KeyType &key4, const X &value4)¶

Construct an ordered map with four elements in it identified by keys

Parameters

key1:
value1:
key2:
value2:
key3:
value3:
key4:
value4:

template <typename T, typename U, typename V, typename X, typename Y>

OrderedMap(const KeyType &key1, const T &value1, const KeyType &key2, const U &value2, const KeyType &key3, const V &value3, const KeyType &key4, const X &value4, const KeyType &key5, const Y &value5)¶

Construct an ordered map with five elements in it identified by keys

Parameters

key1:
value1:
key2:
value2:
key3:
value3:
key4:
value4:
key5:
value5:

template <typename T, typename U, typename V, typename X, typename Y, typename Z>

OrderedMap(const KeyType &key1, const T &value1, const KeyType &key2, const U &value2, const KeyType &key3, const V &value3, const KeyType &key4, const X &value4, const KeyType &key5, const Y &value5, const KeyType &key6, const Z &value6)¶

Construct an ordered map with six elements in it identified by keys

Parameters

key1:
value1:
key2:
value2:
key3:
value3:
key4:
value4:
key5:
value5:
key6:
value6:

OrderedMap<KeyType, MappedType> &operator=(const OrderedMap<KeyType, MappedType> &other)¶

Assignment operator. Clears this map and then assigns the entries of other to it

Return

Parameters

other:

OrderedMap(OrderedMap<KeyType, MappedType> &&other)¶

Move constructor. Moves the entries of other to this map, other is then empty

Return

Parameters

other:

OrderedMap<KeyType, MappedType> &operator=(OrderedMap<KeyType, MappedType> &&other)¶

Move assignment. Moves the entries of other to this map, other is then empty

Return

Parameters

other:

OrderedMap<KeyType, MappedType>::list_iterator lbegin()¶

Return an iterator iterating from the first element over elements in insertion order

Return

OrderedMap<KeyType, MappedType>::list_iterator lend()¶

Return an iterator past the last element in insertion order

Return

OrderedMap<KeyType, MappedType>::map_iterator mbegin()¶

Return an iterator iterating from the first element over elements in key sorting order

Return

OrderedMap<KeyType, MappedType>::map_iterator mend()¶

Return an iterator past the last element in key sorting order

Return

OrderedMap<KeyType, MappedType>::map_iterator find(const KeyType &key)¶

Return a key-sorted iterator to the element identified by key. Returns OrderedMap::mend if the element is not found

Return

Parameters

key:

bool has(const KeyType &key) const¶

Query if the element identified by key exists in the OrderedMap

Return

Parameters

key:

size_t erase(const KeyType &key)¶

Erase element identified by key if key exists.

Return

number of elements erased, i.e. 0 or 1.

Parameters

key:

void erase(const map_iterator &it)¶

Erase element identified by map_iterator.

Return

no

Parameters

it: - a valid map_iterator

size_t size() const¶

Return the number or elements in this map

Return

bool empty() const¶

Query if this map is empty

Return

void clear()¶: Empty or clear the map

template <class T>

Node &set(const KeyType &key, const T &value)¶

Set the element identified by key to value

Return

Parameters

key:
value:

template <class T>

const T &get(const KeyType &key) const¶

Return the element identified by key. Raises an exception if T is not of the type of the inserted element

Return

Parameters

key:

template <class T>

void get(const KeyType &key, T &value) const¶

Fill the reference value with the element identified by key. Raises an exception if T is not of the type of the inserted element

Return

Parameters

key:
value:

template <class T>

const T &get(const const_map_iterator &it) const¶

Return the element for the key-associative iterator to the OrderedMap Raises an exception if T is not of the type of the inserted element

Return

Parameters

key:

template <typename ValueType>

ValueType getAs(const KeyType &key) const¶

Return the element identified by key. Raises an exception if T is not of the type of the inserted element or the value cannot be casted to T

Return

Parameters

key:

const MappedType &getNode(const KeyType &key) const¶

Get the Element identified by key as a Node

Return

Parameters

key:

const std::any &getAny(const KeyType &key) const¶

Get the Element identified by key as a std::any value

Return

Parameters

key:

template <typename T>

bool is(const KeyType &key) const¶

Check if the element at key is of type T

Return

Parameters

key:

template <typename T>

bool is(const const_map_iterator &it) const¶

Check if the element the iterator refers to is of type T

Return

Parameters

key:

bool is(const KeyType &key, const Types::ReferenceType &type) const¶

Check if the element at key is of the given Karabo reference type

Return

Parameters

key:

class OverwriteElement¶

#include <OverwriteElement.hh>

The OverwriteElement allows to overwrite/redefine Element properties of an existing Element of a base class in a derived class.

Public Functions

OverwriteElement &key(std::string const &name)¶

Specify the key to be overwritten

Return

reference to the Element

Parameters

name: unique key name

OverwriteElement &setNewDisplayedName(const std::string &name)¶

Set a new displayed name

Return

Parameters

name:

OverwriteElement &setNewDescription(const std::string &description)¶

Set a new description

Return

Parameters

description:

template <class AliasType>

OverwriteElement &setNewAlias(const AliasType &alias)¶

Set a new alias

Return

Parameters

alias:

OverwriteElement &setNewTags(const std::vector<std::string> &tags)¶

Set new tags

Return

Parameters

tags:

OverwriteElement &setNewAssignmentMandatory()¶

Set to now mandatory assignment

Return

OverwriteElement &setNewAssignmentOptional()¶

Set to now optional assignment

Return

OverwriteElement &setNewAssignmentInternal()¶

Set to now internal assignment

Return

OverwriteElement &setNowInit()¶

Set to now being configurable only upon init

Return

OverwriteElement &setNowReconfigurable()¶

Set to now being reconfigurable

Return

OverwriteElement &setNowReadOnly()¶

Set to now being read-only

Return

OverwriteElement &setNowValidate()¶

Set to now needing validation

Return

OverwriteElement &setNowSkipValidation()¶

Set to now needing skipping validation for this element

Return

template <class ValueType>

OverwriteElement &setNewDefaultValue(const ValueType &value)¶

Set a new default value for this element

Return

Parameters

value:

template <class ValueType>

OverwriteElement &setNewMinInc(const ValueType &value)¶

Set a new minimum inclusive restriction for values set to the element

Return

Parameters

value:

template <class ValueType>

OverwriteElement &setNewMaxInc(const ValueType &value)¶

Set a new maximum inclusive restriction for values set to the element

Return

Parameters

value:

template <class ValueType>

OverwriteElement &setNewMinExc(const ValueType &value)¶

Set a new minimum exclusive restriction for values set to the element

Return

Parameters

value:

template <class ValueType>

OverwriteElement &setNewMaxExc(const ValueType &value)¶

Set a new maximum exclusive restriction for values set to the element

Return

Parameters

value:

template <class ValueType>

OverwriteElement &setNewMin(const ValueType &value)¶

Set a new minimum restriction for values set to the element

Return

Parameters

value:

template <class ValueType>

OverwriteElement &setNewMax(const ValueType &value)¶

Set a new maximum restriction for values set to the element

Return

Parameters

value:

template <class ValueType>

OverwriteElement &setNewMinSize(const ValueType &value)¶

Set a new minimum size restriction for values set to the element

Return

Parameters

value:

template <class ValueType>

OverwriteElement &setNewMaxSize(const ValueType &value)¶

Set a new maximum size restriction for values set to the element

Return

Parameters

value:

OverwriteElement &setNewOptions(const std::string &opts, const std::string &sep = " ,;")¶

Set new allowed options for this element

Return

Parameters

opts:
sep:

OverwriteElement &setNewAllowedStates(const karabo::util::State &s1)¶

Set new allowed States for this element

Return

Parameters

s1-6:
sep:

OverwriteElement &setNowUserAccess()¶

Set the element to now have user access

Return

OverwriteElement &setNowOperatorAccess()¶

Set the element to now have operator access

Return

OverwriteElement &setNowExpertAccess()¶

Set the element to now have expert access

Return

OverwriteElement &setNowAdminAccess()¶

Set the element to now have admin access

Return

OverwriteElement &setNewUnit(const UnitType &unit)¶

Set a new unit to use for values of this element

Return

Parameters

unit:

OverwriteElement &setNewMetricPrefix(const MetricPrefixType &metricPrefix)¶

Set a new metric prefix to use for values of this element

Return

Parameters

unit:

OverwriteElement &setNewOverwriteRestrictions(OverwriteElement::Restrictions &restrictions)¶

Adds new restrictions to the element by merging with existing restrictions

Return

Parameters

restrictionscontains: the new set of restrictions as determined after merging with existing ones

void commit()¶

The commit method injects the element to the expected parameters list. If not called the element is not usable. This must be called after the element is fully defined.

Return: reference to the GenericElement

Private Functions

void checkIfRestrictionApplies(const Restrictions::Restriction &restriction) const¶

Throws an exemption if the restriction in question is set

Parameters

restriction:

template <typename T>
void checkTypedBoundaries()¶: Check default/max/min value consistency, after the value type is known Requires that m_node is not NULL

class Restrictions¶

#include <OverwriteElement.hh>

This class allows to define restrictions for the OVERWRITE_ELEMENT, i.e. which attributes of a different element may not be altered through OVERWRITE. The TABLE_ELEMENT e.g. has no notion of minInc or maxInc, and these should thus not be settable to it via overwrites.

The class “serializes” its options to a vector<bool> which can be passed as an attribute to the node describing the element. It works by making use of the ordered nature of the hash, allowing it to reconstruct itself from a vector<bool>.

Public Functions

std::vector<bool> toVectorAttribute() const¶

Returns the set of a restrictions as a vector<bool> to be set to as an attribute.

Return

Restrictions &merge(const Restrictions &rhs)¶

Merges two sets of restrictions. Set restrictions from either element are preserved during the merge

Return

: the merged element.

Parameters

rhs: element to be merged

void assignFromAttrVector(const std::vector<bool> &attrs)¶

Assigns from a vector<bool> indicating restrictions. Order of entries is in declaration order of restrictions.

Parameters

attrs:

struct Restriction¶

The Restriction struct resembles an individual restriction on the OVERWRITE_ELEMENT While restrictions are set through boolean assignment, its internal data structure is a Karabo Hash.

This struct is fully private on purpose.

class ParameterException¶

#include <Exception.hh>

The ParameterException handles exceptions that result from missing or out-of-bounds parameter

Inherits from karabo::util::Exception

class PathElement¶

#include <PathElement.hh>

The PathElement represents a leaf and can be of any (supported) type

Inherits from karabo::util::LeafElement< PathElement, std::string >

Public Functions

PathElement &options(const std::string &opts, const std::string &sep = " ,;")¶

The options method specifies values allowed for the parameter.

Return

reference to the PathElement

Parameters

opts: A string with space separated values. The values are casted to the proper type.
sep: A separator symbols. Default values are ” ,;”

PathElement &options(const std::vector<std::string> &opts)¶

The options method specifies values allowed for this parameter. Each value is an element of the vector. This function can be used when space cannot be used as a separator.

Return

reference to the PathElement

Parameters

opts: vector of strings. The values are casted to the proper type.

PathElement &isInputFile()¶

Set this element as an input file

Return

PathElement &isOutputFile()¶

Set this element as an output file

Return

PathElement &isDirectory()¶

Set this element as a directory

Return

class PluginLoader¶: #include <PluginLoader.hh>
The PluginLoader class.

class PropagatedException¶

#include <Exception.hh>

The PropagatedException handles exceptions that reflect anonymous nodes within a exception trace

Inherits from karabo::util::Exception

class PythonException¶

#include <Exception.hh>

PythonException

Inherits from karabo::util::Exception

template <class Element, class ValueType>

class ReadOnlySpecific¶

#include <LeafElement.hh>

The ReadOnlySpecific class defines specific values for ‘readOnly’-element.

Public Functions

ReadOnlySpecific &initialValue(const ValueType &initialValue)¶

The initialValue method serves for setting up the initial value reported for this parameter.

Return

reference to the Element for proper methods chaining

Parameters

val: Initial value

ReadOnlySpecific &defaultValue(const ValueType &initialValue)¶

The defaultValue method is the same as initialValue

Return

reference to the Element for proper methods chaining

Parameters

val: Initial value

ReadOnlySpecific &initialValueFromString(const std::string &initialValue)¶

The initialValueFromString method enables setting up a default value in a form of a string. DEPRECATED! For vectors use list initialisation: initialValue({1, 2, 3})

Return

reference to the Element for proper methods chaining

Parameters

defaultValue: A string representation of the default value

AlarmSpecific<Element, ValueType, Self> &warnLow(const ValueType &value)¶

Set lower warning threshold for this value

Return

Parameters

value:

AlarmSpecific<Element, ValueType, Self> &warnHigh(const ValueType &value)¶

Set upper warning threshold for this value

Return

Parameters

value:

AlarmSpecific<Element, ValueType, Self> &alarmLow(const ValueType &value)¶

Set lower alarm threshold for this value

Return

Parameters

value:

AlarmSpecific<Element, ValueType, Self> &alarmHigh(const ValueType &value)¶

Set upper alarm threshold for this value

Return

Parameters

value:

RollingStatsSpecific<Element, ValueType> &enableRollingStats()¶

Enable rolling window statistics for this element. Allows to set variance alarms.

Return

ReadOnlySpecific &archivePolicy(const Schema::ArchivePolicy &value)¶

Set the archiving policy for this element. Available settings are:

EVERY_EVENT, EVERY_100MS, EVERY_1S, EVERY_5S, EVERY_10S, EVERY_1MIN, EVERY_10MIN, NO_ARCHIVING

Return

Parameters

value:

void commit()¶: Registers this element into the Schema

ReadOnlySpecific &observerAccess()¶

The observerAccess method serves for setting up the required access level attribute to be OBSERVER.

Return: reference to the Element (to allow method’s chaining)

ReadOnlySpecific &userAccess()¶

The userAccess method serves for setting up the required access level attribute to be USER.

Return: reference to the Element (to allow method’s chaining)

ReadOnlySpecific &operatorAccess()¶

The operatorAccess method serves for setting up the required access level attribute to be OPERATOR.

Return: reference to the Element (to allow method’s chaining)

ReadOnlySpecific &expertAccess()¶

The expertAccess method serves for setting up the required access level attribute to be EXPERT.

Return: reference to the Element (to allow method’s chaining)

ReadOnlySpecific &adminAccess()¶

The adminAccess method serves for setting up the required access level attribute to be ADMIN.

Return: reference to the Element (to allow method’s chaining)

class ReconfigureException¶

#include <Exception.hh>

The HardwareException handles exceptions that are caused by any connected hardware

Inherits from karabo::util::Exception

class RemoteException¶

#include <Exception.hh>

The RemoteException represents an exception originating in a different device. The parameters are refering to the exception on the other end.

Inherits from karabo::util::Exception

template <class Element, class ValueType>

class RollingStatsSpecific¶

#include <LeafElement.hh>

The RollingStatsSpecific Class configures alarms on rolling statistics

Public Functions

AlarmSpecific<Element, ValueType, Self> &warnVarianceLow(const double value)¶

Set lower warning threshold for rolling window variance

Return

Parameters

value:

AlarmSpecific<Element, ValueType, Self> &warnVarianceHigh(const double value)¶

Set upper warning threshold for rolling window variance

Return

Parameters

value:

AlarmSpecific<Element, ValueType, Self> &alarmVarianceLow(const double value)¶

Set lower alarm threshold for rolling window variance

Return

Parameters

value:

AlarmSpecific<Element, ValueType, Self> &alarmVarianceHigh(const double value)¶

Set upper alarm threshold for rolling window variance

Return

Parameters

value:

ReadOnlySpecific<Element, ValueType> &evaluationInterval(const unsigned int interval)¶

Set the size/interval for the rolling window the variance is evaluated over.

Return

Parameters

value:

class RollingWindowStatistics¶

Public Functions

RollingWindowStatistics(unsigned int evalInterval)¶

A rolling window statistics evaluator

Parameters

evalInterval: rolling window interval to evaluate for

void update(double v)¶

Updates evaluated value list. If the new calculated rolling mean deviates from the currently used estimate of the mean by more than five sigma the estimate is updated as well.

Parameters

v:

double getRollingWindowVariance() const¶

Returns the rolling variance

Return

double getRollingWindowMean() const¶

Returns the rolling mean

Return

unsigned long long getInterval() const¶

Return the interval for these statistics

Return

class Schema¶

#include <Schema.hh>

The Schema class correlates to the Hash class like an XML Schema document correlates to an XML document. The Schema object is a description of type of Hash objects, expressed in terms of constraints on the structure and content of Hash objects of that type. Because generally the Hash object is a collection of key/value pairs of quite a common nature (std::string, std::any), the constraints applied by Schema object may define which keys has to be in Hash, some rules for the value range, access type, assignment type, existence of additional attributes associated with some particular key like description, visual representation, aliases, default value and so on. The Schema object is the place where one can enter all these informations.

Public Types

enum NodeType¶

An enum specifying the type of Node-like elements (NodeElement, ChoiceElement, ListElement)

Values:

LEAF¶

NODE¶

CHOICE_OF_NODES¶

LIST_OF_NODES¶

enum LeafType¶

An enum specifying the type of Leaf-like elements

Values:

PROPERTY¶

COMMAND¶

STATE¶

ALARM_CONDITION¶

enum AssignmentType¶

An enum specifying assignment restrictions for elements

Values:

OPTIONAL_PARAM¶

MANDATORY_PARAM¶

INTERNAL_PARAM¶

enum ArchivePolicy¶

An enum specifying the archiving interval for updates to elements

Values:

EVERY_EVENT¶

EVERY_100MS¶

EVERY_1S¶

EVERY_5S¶

EVERY_10S¶

EVERY_1MIN¶

EVERY_10MIN¶

NO_ARCHIVING¶

enum AccessLevel¶

An enum specifying the access-level needed to view or alter elements.

Values:

OBSERVER = 0¶

USER¶

OPERATOR¶

EXPERT¶

ADMIN¶

Public Functions

Schema(const std::string &classId = "", const Schema::AssemblyRules &rules = Schema::AssemblyRules())¶

Constructs empty schema for given classId

Parameters

classId: The factory key of the configurable class (will be stored outside the inner hash)
rules: Assembly rules if the schema is assembled from a class configurations (filters access modes, states and access rights)

void setAssemblyRules(const Schema::AssemblyRules &rules)¶

Set the assembly rules for this schema

Parameters

rules:

Schema::AssemblyRules getAssemblyRules() const¶

Get the assembly rules of this schema

Return

const std::string &getRootName() const¶

Get the schema’s root element’s name

Return

void setRootName(const std::string &rootName)¶

St the schema’s root element’s name

Parameters

rootName:

const karabo::util::Hash &getParameterHash() const¶

Get a Hash representation of this Schema. It will have the same hierarchical structure as the schema. Each keys attributes map to the attributes/modifiers of the respective schema element. The value types to not match up with the schema but are all of type INT32. If you need a Hash holding empty values of correct data types use the karabo::DeviceClient::getDataSchema method instead

Return

void setParameterHash(const karabo::util::Hash &parameterDescription)¶

Set the parameter hash of the schema. Implicitly alters the schema as this Hash is its underlying description.

Parameters

parameterDescription: - must match the structure of the Schema internal Hash

void setParameterHash(karabo::util::Hash &&parameterDescription)¶

Set (with move semantics) the parameter hash of the schema. Implicitly alters the schema as this Hash is its underlying description.

Parameters

parameterDescription: - must match the structure of the Schema internal Hash

void updateAliasMap()¶: This function updates the internal mapping between keys and their aliases The function must be called after de-serialization in order to construct the proper inner structure

std::vector<std::string> getKeys(const std::string &path = "") const¶

Returns all keys in the schema (no recursion) Keys in inner-structures are not provided

Return

array of strings

Parameters

level: from which to start the traversal

std::vector<std::string> getPaths() const¶

Returns all root-to-leaves paths of the schema

Return: array of strings

bool has(const std::string &path) const¶

Check if a given path exists in the Schema

Return

Parameters

path:

void merge(const Schema &schema)¶

Merges another schema into the current one

Parameters

schema: Another schema to be merged

bool empty() const¶

Check if the Schema is empty

Return

bool isCommand(const std::string &path) const¶

Check if the element at path is a command

Return

Parameters

path:

bool isProperty(const std::string &path) const¶

Check if the element at path is a property

Return

Parameters

path:

bool isLeaf(const std::string &path) const¶

Check if the element at path is of Leaf-type

Return

Parameters

path:

bool isNode(const std::string &path) const¶

Check if the element at path is of Node-Element-type

Return

Parameters

path:

bool isChoiceOfNodes(const std::string &path) const¶

Check if the element at path is of Choice-of-Nodes type

Return

Parameters

path:

bool isListOfNodes(const std::string &path) const¶

Check if the element at path is of List-of-Nodes type

Return

Parameters

path:

bool hasNodeType(const std::string &path) const¶

Check if the element at path has one of the node element types (NodeElement, ListElement, ChoiceElement)

Return

Parameters

path:

int getNodeType(const std::string &path) const¶

Get the node type of the element identified by path. You should check if it is of Node-type first with Schema::hasNodeType()

Return

a value mapping to the Schema::NodeType enum

Parameters

path:

Types::ReferenceType getValueType(const std::string &path) const¶

Get the valuetype of the element at path. You should check that it is of LeafType first using Schema::isLeaf

Return

Parameters

path:

void setAccessMode(const std::string &path, const AccessType &value)¶

Set the access mode for the element identified by path

Parameters

path:
value:

bool hasAccessMode(const std::string &path) const¶

Check if the element identified by path has an access mode set

Return

Parameters

path:

bool isAccessInitOnly(const std::string &path) const¶

Check if the element identified by path is init-only

Return

Parameters

path:

bool isAccessReadOnly(const std::string &path) const¶

Check if the element identified by path is read-only

Return

Parameters

path:

bool isAccessReconfigurable(const std::string &path) const¶

Check if the element identified by path is reconfigurable

Return

Parameters

path:

int getAccessMode(const std::string &path) const¶

Get the access mode for the element identified by path

Return

maps to the Schema::AccessMode enum

Parameters

path:

void setDisplayedName(const std::string &path, const std::string &value)¶

Set the displayed name for the element identified by path

Parameters

path:
value:

bool hasDisplayedName(const std::string &path) const¶

Check if the element identified by path has a displayed name set

Return

Parameters

path:

const std::string &getDisplayedName(const std::string &path) const¶

Set the displayed name for the element identified by path

Return

Parameters

path:

void setDescription(const std::string &path, const std::string &value)¶

Set the description for the element identified by path

Parameters

path:
value:

bool hasDescription(const std::string &path) const¶

Check if the element identified by path has a description set

Return

Parameters

path:

const std::string &getDescription(const std::string &path) const¶

Get the description for the element identified by path

Return

Parameters

path:

void setTags(const std::string &path, const std::string &value, const std::string &sep = " ,;")¶

Set the tags for the element identified by path

Parameters

path:
value:

bool hasTags(const std::string &path) const¶

Check if the element identified by path has tags set

Return

Parameters

path:

const std::vector<std::string> &getTags(const std::string &path) const¶

Get the tags for the element identified by path

Return

Parameters

path:

bool hasClassId(const std::string &path) const¶

Check if the element identified by path has a classId

Return

Parameters

path:

const string &getClassId(const std::string &path) const¶

Get the classId for the element identified by path

Return

Parameters

path:

void setDisplayType(const std::string &path, const std::string &value)¶

Set the display type for the element identified by path

Parameters

path:
value:

bool hasDisplayType(const std::string &path) const¶

Check if the element identified by path has a display type set

Return

Parameters

path:

const string &getDisplayType(const std::string &path) const¶

Get the display type for the element identified by path

Return

Parameters

path:

void setAssignment(const std::string &path, const AssignmentType &value)¶

Set the assignment type for the element identified by path

Parameters

path:
value:

bool hasAssignment(const std::string &path) const¶

Check if the element identified by path has a assignment type set

Return

Parameters

path:

bool isAssignmentMandatory(const std::string &path) const¶

Check if the element identified by path is assignment mandatory

Return

Parameters

path:

bool isAssignmentOptional(const std::string &path) const¶

Check if the element identified by path is assignment optional

Return

Parameters

path:

bool isAssignmentInternal(const std::string &path) const¶

Check if the element identified by path is assignment internal

Return

Parameters

path:

const int getAssignment(const std::string &path) const¶

Get the assignment type for the element identified by path

Return

Parameters

path:

void setSkipValidation(const std::string &path, const bool value)¶

Set the element identified by path to skip validation

Parameters

path:
value:

bool getSkipValidation(const std::string &path)¶

Check if the element identified by path is set to skip validation

Return

Parameters

path:

void setOptions(const std::string &path, const std::string &value, const std::string &sep)¶

Set options for the element identified by path.

Parameters

path:
value: a stringified list of options, separated by sep
sep:

bool hasOptions(const std::string &path) const¶

Check if the element identified by path has options set

Return

Parameters

path:

template <class T>

const std::vector<T> &getOptions(const std::string &path) const¶

Get the options set for the element identified by path

Return

Parameters

path:

void setAllowedStates(const std::string &path, const karabo::util::State &s1)¶

Set new allowed states for the element identified by path

Parameters

path:
s1:

bool hasAllowedStates(const std::string &path) const¶

Check if the element identified by path has allowed states set

Return

Parameters

path:

const vector<State> getAllowedStates(const std::string &path) const¶

Get the allowed states set for the element identified by path

Return

Parameters

path:

void setRequiredAccessLevel(const std::string &path, const AccessLevel &value)¶

Set the required access level for the element identified by path

Parameters

path:
value:

const int getRequiredAccessLevel(const std::string &path) const¶

Get the required access level for the element identified by path

Return

maps to the Schema::AccessLevel enum

Parameters

path:

template <class ValueType>

void setDefaultValue(const std::string &path, const ValueType &value)¶

Set the new default value for the element identified by path

Parameters

path:
value:

bool hasDefaultValue(const std::string &path) const¶

Check if the element identified by path has a default value set

Parameters

template <class ValueType>

const ValueType &getDefaultValue(const std::string &path) const¶

Get the default value set for the element identified by path. Use Schema::hasDefaultValue first to check if one is set. Will throw an Exception if ValueType does not match the type of the default value set (it will be of the Element’s value type)

Return

Parameters

path:

template <class T>

T getDefaultValueAs(const std::string &path) const¶

Get the default value set for the element identified by path. Use Schema::hasDefaultValue first to check if one is set. Will throw an Exception if the type of the default value set (it will be of the Element’s value type) cannot be casted to T

Return

Parameters

path:

template <typename T, template< typename Elem, typename=std::allocator< Elem > > class Cont>

Cont<T> getDefaultValueAs(const std::string &path) const

Get the default value set for the element identified by path. Use Schema::hasDefaultValue first to check if one is set. Will throw an Exception if the type of the default value set (it will be of the Element’s value type) cannot be casted to T. Overload for sequence types.

Return

Parameters

path:

bool keyHasAlias(const std::string &path) const¶

Check if an alias has been set for path

Return

Parameters

path:

template <class AliasType>

bool aliasHasKey(const AliasType &alias) const¶

Check if a key with alias exists

Return

Parameters

alias:

template <class AliasType>

const AliasType &getAliasFromKey(const std::string &path) const¶

Get the alias mapping to the key at path. Check if an alias has been set first by using Schema::keyHasAlias

Return

Parameters

path:

template <class AliasType>

const std::string &getKeyFromAlias(const AliasType &alias) const¶

Get the key the alias maps to. Check if the alias maps to a key first by using Schema::aliasHasKey

Return

Parameters

path:

string getAliasAsString(const std::string &path) const¶

Get the alias for path as string. Check if an alias has been set first by using Schema::keyHasAlias

Return

Parameters

path:

template <class AliasType>

void setAlias(const std::string &path, const AliasType &value)¶

Set an alias for path

Parameters

path:
value:

void setUnit(const std::string &path, const UnitType &value)¶

Set the unit for the element identified by path

Parameters

path:
value:

bool hasUnit(const std::string &path) const¶

Check if the element identified by path has an unit set

Return

Parameters

path:

const int getUnit(const std::string &path) const¶

Get the unit set for the element identified by path. Check if the element has an unit set first using Schema::hasUnit()

Return

maps to a karabo::util::UnitType enum

Parameters

path:

const std::string &getUnitName(const std::string &path) const¶

Get the unit name for the element identified by path. Check if the element has an unit set first using Schema::hasUnit()

Return

Parameters

path:

const std::string &getUnitSymbol(const std::string &path) const¶

Get the unit symbol for the element identified by path. Check if the element has an unit set first using Schema::hasUnit()

Return

Parameters

path:

void setMetricPrefix(const std::string &path, const MetricPrefixType &value)¶

Set the metric prefix for the element identified by path

Parameters

path:
value:

bool hasMetricPrefix(const std::string &path) const¶

Check if the element identified by path has an metric prefix set

Return

Parameters

path:

const int getMetricPrefix(const std::string &path) const¶

Get the metric prefix set for the element identified by path. Check if the element has an metric prefix set first using Schema::hasMetricPrefix()

Return

maps to a karabo::util::UnitType enum

Parameters

path:

const std::string &getMetricPrefixName(const std::string &path) const¶

Get the metric prefix name for the element identified by path. Check if the element has an metric prefix set first using Schema::hasMetricPrefix()

Return

Parameters

path:

const std::string &getMetricPrefixSymbol(const std::string &path) const¶

Get the metric prefix symbol for the element identified by path. Check if the element has an metric prefix set first using Schema::hasMetricPrefix()

Return

Parameters

path:

template <class ValueType>

void setMinInc(const std::string &path, const ValueType &value)¶

Set the minimum inclusive restriction for setting values to the element identified by path

Parameters

path:
value:

template <class ValueType>

const ValueType &getMinInc(const std::string &path) const¶

Get the minimum inclusive restriction for setting values to the element identified by path. Will throw an exception if ValueType is not of the type of the bound (usually the Element’s data type)

Parameters

path:

template <class T>

T getMinIncAs(const std::string &path) const¶

Get the minimum inclusive restriction for setting values to the element identified by path. Will throw an exception if T is not of the type of the bound (usually the Element’s data type) or cannot be casted to T.

Parameters

path:

bool hasMinInc(const std::string &path) const¶

Check if a minimum inclusive restriction for setting values to the element identified by path has been set

Return

Parameters

path:

template <class ValueType>

void setMaxInc(const std::string &path, const ValueType &value)¶

Set the maximum inclusive restriction for setting values to the element identified by path

Parameters

path:
value:

template <class ValueType>

const ValueType &getMaxInc(const std::string &path) const¶

Get the maximum inclusive restriction for setting values to the element identified by path. Will throw an exception if ValueType is not of the type of the bound (usually the Element’s data type)

Parameters

path:

template <class T>

T getMaxIncAs(const std::string &path) const¶

Get the maximum inclusive restriction for setting values to the element identified by path. Will throw an exception if T is not of the type of the bound (usually the Element’s data type) or cannot be casted to T.

Parameters

path:

bool hasMaxInc(const std::string &path) const¶

Check if a maximum inclusive restriction for setting values to the element identified by path has been set

Return

Parameters

path:

template <class ValueType>

void setMinExc(const std::string &path, const ValueType &value)¶

Set the minimum exclusive restriction for setting values to the element identified by path

Parameters

path:
value:

template <class ValueType>

const ValueType &getMinExc(const std::string &path) const¶

Get the minimum exclusive restriction for setting values to the element identified by path. Will throw an exception if ValueType is not of the type of the bound (usually the Element’s data type)

Parameters

path:

template <class T>

T getMinExcAs(const std::string &path) const¶

Get the minimum exclusive restriction for setting values to the element identified by path. Will throw an exception if T is not of the type of the bound (usually the Element’s data type) or cannot be casted to T.

Parameters

path:

bool hasMinExc(const std::string &path) const¶

Check if a minimum exclusive restriction for setting values to the element identified by path has been set

Return

Parameters

path:

template <class ValueType>

void setMaxExc(const std::string &path, const ValueType &value)¶

Set the maximum exclusive restriction for setting values to the element identified by path

Parameters

path:
value:

template <class ValueType>

const ValueType &getMaxExc(const std::string &path) const¶

Get the maximum exclusive restriction for setting values to the element identified by path. Will throw an exception if ValueType is not of the type of the bound (usually the Element’s data type)

Parameters

path:

template <class T>

T getMaxExcAs(const std::string &path) const¶

Get the maximum exclusive restriction for setting values to the element identified by path. Will throw an exception if T is not of the type of the bound (usually the Element’s data type) or cannot be casted to T.

Parameters

path:

bool hasMaxExc(const std::string &path) const¶

Check if a maximum exclusive restriction for setting values to the element identified by path has been set

Return

Parameters

path:

void setMinSize(const std::string &path, const unsigned int &value)¶

Set the minimum size restriction for setting sequence values to the element identified by path

Parameters

path:
value:

bool hasMinSize(const std::string &path) const¶

Check if a minimum size restriction for setting sequence values to the element identified by path has been set

Return

Parameters

path:

const unsigned int &getMinSize(const std::string &path) const¶

Get the minimum size restriction for setting sequence values to the element identified by path.

Parameters

path:

void setMaxSize(const std::string &path, const unsigned int &value)¶

Set the maximum size restriction for setting sequence values to the element identified by path

Parameters

path:
value:

bool hasMaxSize(const std::string &path) const¶

Check if a maximum size restriction for setting sequence values to the element identified by path has been set

Return

Parameters

path:

const unsigned int &getMaxSize(const std::string &path) const¶

Get the maximum size restriction for setting sequence values to the element identified by path.

Parameters

path:

template <class ValueType>

void setWarnLow(const std::string &path, const ValueType &value)¶

Set the lower warning limit for the element identified by path

Parameters

path:
value:

template <class ValueType>

const ValueType &getWarnLow(const std::string &path) const¶

Get the lower warning limit for the element identified by path. Will throw an exception if ValueType is not of the type of the bound (usually the Element’s data type)

Parameters

path:

template <class T>

T getWarnLowAs(const std::string &path) const¶

Get the lower warning limit for the element identified by path. Will throw an exception if T is not of the type of the bound (usually the Element’s data type) or cannot be casted to T.

Parameters

path:

bool hasWarnLow(const std::string &path) const¶

Check if a lower warning limit for the element identified by path has been set

Return

Parameters

path:

template <class ValueType>

void setWarnHigh(const std::string &path, const ValueType &value)¶

Set the upper warning limit for the element identified by path

Parameters

path:
value:

template <class ValueType>

const ValueType &getWarnHigh(const std::string &path) const¶

Get the upper warning limit for the element identified by path. Will throw an exception if ValueType is not of the type of the bound (usually the Element’s data type)

Parameters

path:

template <class T>

T getWarnHighAs(const std::string &path) const¶

Get the upper warning limit for the element identified by path. Will throw an exception if T is not of the type of the bound (usually the Element’s data type) or cannot be casted to T.

Parameters

path:

bool hasWarnHigh(const std::string &path) const¶

Check if a upper warning limit for the element identified by path has been set

Return

Parameters

path:

template <class ValueType>

void setAlarmLow(const std::string &path, const ValueType &value)¶

Set the lower alarm limit for the element identified by path

Parameters

path:
value:

template <class ValueType>

const ValueType &getAlarmLow(const std::string &path) const¶

Get the lower alarm limit for the element identified by path. Will throw an exception if ValueType is not of the type of the bound (usually the Element’s data type)

Parameters

path:

template <class T>

T getAlarmLowAs(const std::string &path) const¶

Get the lower alarm limit for the element identified by path. Will throw an exception if T is not of the type of the bound (usually the Element’s data type) or cannot be casted to T.

Parameters

path:

bool hasAlarmLow(const std::string &path) const¶

Check if a lower alarm limit for the element identified by path has been set

Return

Parameters

path:

template <class ValueType>

void setAlarmHigh(const std::string &path, const ValueType &value)¶

Set the upper alarm limit for the element identified by path

Parameters

path:
value:

template <class ValueType>

const ValueType &getAlarmHigh(const std::string &path) const¶

Get the upper alarm limit for the element identified by path. Will throw an exception if ValueType is not of the type of the bound (usually the Element’s data type)

Parameters

path:

template <class T>

T getAlarmHighAs(const std::string &path) const¶

Get the upper alarm limit for the element identified by path. Will throw an exception if T is not of the type of the bound (usually the Element’s data type) or cannot be casted to T.

Parameters

path:

bool hasAlarmHigh(const std::string &path) const¶

Check if a upper alarm limit for the element identified by path has been set

Return

Parameters

path:

void setWarnVarianceLow(const std::string &path, const double value)¶

Set the lower rolling window variance warning limit for the element identified by path

Parameters

path:
value:

double getWarnVarianceLow(const std::string &path) const¶

Get the lower rolling window variance warning limit for the element identified by path.

Parameters

path:

bool hasWarnVarianceLow(const std::string &path) const¶

Check if a lower rolling window variance warning limit for the element identified by path has been set

Return

Parameters

path:

void setWarnVarianceHigh(const std::string &path, const double value)¶

Set the upper rolling window variance warning limit for the element identified by path

Parameters

path:
value:

double getWarnVarianceHigh(const std::string &path) const¶

Get the upper rolling window variance warning limit for the element identified by path.

Parameters

path:

bool hasWarnVarianceHigh(const std::string &path) const¶

Check if a upper rolling window variance warning limit for the element identified by path has been set

Return

Parameters

path:

void setAlarmVarianceLow(const std::string &path, const double value)¶

Set the lower rolling window variance alarm limit for the element identified by path

Parameters

path:
value:

double getAlarmVarianceLow(const std::string &path) const¶

Get the lower rolling window variance alarm limit for the element identified by path.

Parameters

path:

bool hasAlarmVarianceLow(const std::string &path) const¶

Check if a lower rolling window variance alarm limit for the element identified by path has been set

Return

Parameters

path:

void setAlarmVarianceHigh(const std::string &path, const double value)¶

Set the upper rolling window variance alarm limit for the element identified by path

Parameters

path:
value:

double getAlarmVarianceHigh(const std::string &path) const¶

Get the upper rolling window variance alarm limit for the element identified by path.

Parameters

path:

bool hasAlarmVarianceHigh(const std::string &path) const¶

Check if a upper rolling window variance alarm limit for the element identified by path has been set

Return

Parameters

path:

bool hasInterlock(const std::string &path) const¶

Check if the element identified by path has interlocks defined

Return

Parameters

path:

void setRollingStatistics(const std::string &path, unsigned int interval)¶

Set/enable rolling window statistics for the element identified by path

Parameters

path:
interval: or window size of the rolling window

bool hasRollingStatistics(const std::string &path) const¶

Check if the element identified by path has rolling window statistics enabled

Return

Parameters

path:

unsigned int getRollingStatsEvalInterval(const std::string &path) const¶

Get the rolling window statistics interval for the element identified by path

Return

Parameters

path:

const std::string getInfoForAlarm(const std::string &path, const karabo::util::AlarmCondition &condition) const¶

Get additional information for the alarm condition present on the element identified by path

Return

Parameters

path:
condition:

const bool doesAlarmNeedAcknowledging(const std::string &path, const karabo::util::AlarmCondition &condition) const¶

Check if alarms of a specified condition need acknowledging for the element identified by path

Return

Parameters

path:
condition:

void setArchivePolicy(const std::string &path, const ArchivePolicy &value)¶

Set the archive policy for the element identified by path

Parameters

path:
value:

bool hasArchivePolicy(const std::string &path) const¶

Check if the element identified by path has an archive policy set

Return

Parameters

path:

const int &getArchivePolicy(const std::string &path) const¶

Get the archive policy for the element identified by path.

Return

maps to the Schema::ArchivePolicy enum

Parameters

path:

void setMin(const std::string &path, const int &value)¶

Set the minimum number of nodes needed in a list element

Parameters

path:
value:

bool hasMin(const std::string &path) const¶

Check if the element identified by path has a minimum number of Nodes set

Return

Parameters

path:

const int &getMin(const std::string &path) const¶

Get the minimum number of nodes needed for the element identified by path

Return

Parameters

path:

void setMax(const std::string &path, const int &value)¶

Set the maximum number of nodes needed in a list element

Parameters

path:
value:

bool hasMax(const std::string &path) const¶

Check if the element identified by path has a maximum number of Nodes set

Return

Parameters

path:

const int &getMax(const std::string &path) const¶

Set the maximum number of nodes needed in a list element

Parameters

path:
value:

void help(const std::string &classId = "", std::ostream &os = std::cout)¶: Help function to show all parameters

bool applyRuntimeUpdates(const std::vector<karabo::util::Hash> &updates)¶

Update attribute for schema.

Return

true if all updates succeeded, false otherwise. If any update fails, the schema is restored to the state it was in before the call to applyRuntimeUpdates.

Parameters

updates: updated attributes, expected to be of form Hash(“instanceId”, str, “updates”, vector<Hash>) where each entry in updates is of the form Hash(“path”, str, “attribute”, str, “value”, valueType).

Schema subSchema(const std::string &subNodePath, const std::string &filterTags = std::string()) const¶

Retrieve a sub-schema of the schema

Return

a sub-schema of this schema.

Parameters

subNodePath: path of the node element to retrieve sub schema from
filterTags: optional tags to filter sub schema by

Schema subSchemaByRules(const AssemblyRules &rules) const¶

Retrieve a sub-schema of those paths that fulfill given rules

Parameters

rules: assemby rules: - if their state field is emtpy, accept all states
- similarly, default accessLevel -1 means do not care

Schema subSchemaByPaths(const std::set<std::string> &paths) const¶

Retrieves a sub-schema with given paths

A path to a node means that all further nested paths are kept

Return

reduced schema

Parameters

paths: in the schema whose information should be copied to the resulting sub schema

void setDaqDataType(const std::string &path, const DaqDataType &dataType)¶

Set the DAQ data type for a given node element.

Data types may only be set for node elements

Parameters

path: at which the node is located
dataType: of this node

DaqDataType getDaqDataType(const std::string &path) const¶

Get the DAQ data type for a given node element

Parameters

path:

bool hasDaqDataType(const std::string &path) const¶

Check if a DAQ data type has been set for a given element.

Parameters

path:

bool isCustomNode(const std::string &path) const¶

Check if given element is a custom node like IMAGEDATA or NDARRAY_ELEMENT.

Parameters

path:

const std::string &getCustomNodeClass(const std::string &path) const¶

Get the class name for a given custom node element Result is undefined if path does not point to a custom node element (may e.g. throw or not), so better check isCustomNode before.

Parameters

path: of custom node element

void setAllowedActions(const std::string &path, const std::vector<std::string> &actions)¶

Specify one or more actions that are allowed on the element.

If a Karabo device specifies allowed actions, that means that it offers a specific slot interface to operate on this element. Which allowed actions require which interface will be defined elsewhere.

Parameters

path: to element
actions: vector of strings of allowed actions

bool hasAllowedActions(const std::string &path) const¶

Check if given element has allowed actions.

Parameters

path: to element

const std::vector<std::string> &getAllowedActions(const std::string &path) const¶

Get allowed actions of given element if available. Pre-requisite: hasAllowedActions(path) has to return true.

Return

specified allowed actions

Parameters

path: to element

void setDAQPolicy(const std::string &path, const DAQPolicy &value)¶

Set the DAQ policy for the element identified by path

Parameters

path:
value:

bool hasDAQPolicy(const std::string &path) const¶

Check if the element identified by path has an DAQ policy set

Return

Parameters

path:

DAQPolicy getDAQPolicy(const std::string &path) const¶

Get the DAQ policy for the element identified by path.

Return

maps to the Schema::DAQPolicy enum

Parameters

path:

void setDefaultDAQPolicy(const DAQPolicy &value)¶

Set the default DAQ policy to use if not specified per element. Needs to be called at the very beginning of the expected parameter section.

Parameters

policy:

DAQPolicy getDefaultDAQPolicy() const¶: Get the default DAQ policy to use if not specified per element

Private Functions

bool isOrphaned(const Hash::Node &node) const¶: True if node’s key points to a subnode whose parent does not exist or is of inappropriate node type.

Friends

KARABO_DECLSPEC friend std::ostream& operator<<(std::ostream & os, const Schema & schema)

Default output using help function

Return

Parameters

key:

struct AssemblyRules¶: #include <Schema.hh>
The AssemblyRules specify how the karabo::util::Configurator assembles the configuration

class SchemaException¶

#include <Exception.hh>

The SchemaException handles exceptions that are raised whilst constructing a Schema

Inherits from karabo::util::Exception

class SignalSlotException¶

#include <Exception.hh>

The HardwareException handles exceptions that are caused by any connected hardware

Inherits from karabo::util::Exception

template <typename ValueType>

class SimpleElement¶

#include <SimpleElement.hh>

The SimpleElement represents a leaf and can be of any (supported) type.

Inherits from karabo::util::LeafElement< SimpleElement< ValueType >, ValueType >

Public Functions

SimpleElement &options(const std::string &opts, const std::string &sep = " ,;")¶

The options method specifies values allowed for the parameter.

Return

reference to the SimpleElement

Parameters

opts: A string with space separated values. The values are casted to the proper type.
sep: A separator symbols. Default values are ” ,;”

SimpleElement &options(const std::vector<ValueType> &opts)¶

The options method specifies values allowed for this parameter. Each value is an element of the vector. This function can be used when space cannot be used as a separator.

Return

reference to the SimpleElement

Parameters

opts: vector of strings. The values are casted to the proper type.

SimpleElement &minInc(ValueType const &value)¶

The minInc method sets the lowest value accepted for this parameter. Defines the left-closed interval.

Return

reference to the SimpleElement

Parameters

val: minimum value

SimpleElement &maxInc(ValueType const &value)¶

The maxInc sets the highest value accepted for this parameter. Defines the right-closed interval.

Return

reference to the SimpleElement

Parameters

val: maximum value

SimpleElement &minExc(ValueType const &value)¶

The minExc sets the upper limit for this parameter. Defines the left-open interval.

Return

reference to the SimpleElement

Parameters

val: upper limit

SimpleElement &maxExc(ValueType const &value)¶

The maxExc sets the lower limit for this parameter. Defines the right-open interval.

Return

reference to the SimpleElement

Parameters

val: lower limit

SimpleElement &relativeError(double error)¶: The relativeError sets the relative error of this parameter. Ideally, |x * relativeError| > |x - x0| with x the measured value and x0 the real value

SimpleElement &absoluteError(double error)¶: the absoluteError sets the absolute error of this parameter Ideally, absoluteError > |x - x0| with x the measured value and x0 the real value

SimpleElement &hex()¶

The hex tells the GUI to interpret the numeric value as a hex string.

Return: reference to the SimpleElement to use chaining

SimpleElement &oct()¶

The oct tells the GUI to interpret the numeric value as a hex string.

Return: reference to the SimpleElement to use chaining

SimpleElement &bin()¶

The bin tells the GUI to interpret the numeric value as a bit string.

Return: reference to the SimpleElement to use chaining

SimpleElement &bin(const std::string &meaning)¶

The bin tells the GUI to interpret the numeric value as a bit string.

Return

reference to the SimpleElement to use chaining

Parameters

meaning: A string which describes the meaning of each bit, the format is 0:isError,1:isMoving,31:isOff NOTE: bits can be described randomly (no need mentioning them all)

class StackTrace¶

#include <StackTrace.hh>

StackTrace prints out the exception stack, symbols are, in the best case, C++ demangled.

Public Static Functions

static std::string demangle(const char *symbol)¶

Demangle symbol into a string

Return

Parameters

symbol:

void print(std::ostream &os)¶

Print trace to an output stream

Parameters

os:

class State¶

#include <State.hh>

A class representing unified states accross the Karabo system.

This class holds all states known to Karabo as static data members. States should always be accessed through this class. It’s constructors are fully private, meaning that no additional States can be constructed outside of this class

Public Functions

virtual const std::string &operator()() const¶

Implicit conversion to strings is allowed

Return

const std::string &name() const¶

Return the name of the state

Return

const State *parent() const¶

Return the states parent in the state hierarchy in case it is a derived state

Return

bool operator==(const State &state) const¶

Check if two states are identical

Return

Parameters

state:

bool operator!=(const State &state) const¶

Check if two states are not identical

Return

Parameters

state:

bool isDerivedFrom(const State &s) const¶

Evaluate if this state is derived from another State s

Return

Parameters

s:

Public Static Functions

const State &fromString(const std::string &state)¶

Create a state from its string representation

Return

Parameters

state:

class StateElement¶

#include <StateElement.hh>

The StateElement represents a leaf and needs to be of type State.

Inherits from karabo::util::GenericElement< StateElement >

Public Functions

StateElement &options(const karabo::util::State &s1)¶

The options method specifies values allowed for the parameter.

Return

reference to the StateElement

Parameters

one: to eight States or a vector of States

StateElement &initialValue(const karabo::util::State &s)¶

The initialValue method serves for setting up the initial value reported for this parameter.

Return

reference to the Element for proper methods chaining

Parameters

val: Initial value

class StateSignifier¶

#include <StateSignifier.hh>

The StateSignifier is used to evaluate the most significant State from a set of States.

Public Functions

StateSignifier(const std::vector<karabo::util::State> &trumpList = std::vector<karabo::util::State>(), const karabo::util::State &staticMoreSignificant = karabo::util::State::PASSIVE, const karabo::util::State &changingMoreSignificant = karabo::util::State::DECREASING)¶

Create a StateSignifier

Parameters

trumpList: if set use this list to deviate from the standard signification order
staticMoreSignificant: identify if in the State::STATIC regime State::PASSIVE or State::ACTIVE is more significant
changingMoreSignificant: identify if in the State::CHANGING regime State::INCREASING or State::DECREASING is more significant

StateSignifier(const karabo::util::State &staticMoreSignificant, const karabo::util::State &changingMoreSignificant)¶

Create a StateSignifier

Parameters

staticMoreSignificant: identify if in the State::STATIC regime State::PASSIVE or State::ACTIVE is more
changingMoreSignificant: identify if in the State::CHANGING regime State::INCREASING or State::DECREASING is more significant

State returnMostSignificant(const std::vector<karabo::util::State> &listOfStates)¶

Return the most significant State from a list of States

Return

Parameters

listOfStates:

Private Functions

void fillAncestorNames(const karabo::util::State &s, std::vector<std::string> &all)¶

Fill full list of ancestors for state, starting from state name itself: state_name, parent_name, grand_parent_name, grand_grand_parent_name, …

Parameters

s: input state
all: vector for accumulating of output list of ancestors

void completeChangingSubstates(const karabo::util::State &changingMoreSignificant)¶

Completes a non default trump list with some substates of CHANGING if that list contains CHANGING.

Parameters

changingMoreSignificant: which CHANGING substate is more significant between INCREASING and DECREASING?

void completeStaticSubstates(const karabo::util::State &staticMoreSignificant)¶

Completes a non default trump list with some substates of STATIC if that list contains STATIC.

Parameters

staticMoreSignificant: which STATIC substate is more significant between ACTIVE and PASSIVE?

void completeKnownSubstates(const karabo::util::State &staticMoreSignificant, const karabo::util::State &changingMoreSignificant)¶

Completes a non default trump list with some substates of KNOWN if that list contains KNOWN.

Parameters

staticgMoreSignificant: which STATIC substate is more significant between ACTIVE and PASSIVE?
changingMoreSignificant: which CHANGING substate is more significant between INCREASING and DECREASING?

template <typename, typename>
struct static_or_dyn_cast¶: #include <MetaTools.hh>
Helper functions to compile-time distinguish if a dynamic_cast is needed.

class SystemException¶

#include <Exception.hh>

The SystemException handles exceptions raised related to Input/Output routines

Inherits from karabo::util::Exception

template <typename Element>

class TableDefaultValue¶

#include <TableElement.hh>

The TableDefaultValue class defines a default value for the TableElement.

Public Functions

Element &defaultValue(const std::vector<Hash> &defaultValue)¶

The defaultValue method serves for setting up the default value to be used when User configuration does not specify another value.

Return

reference to the Element for proper methods chaining

Parameters

val: Default value

Element &noDefaultValue()¶

The noDefaultValue serves for setting up the element that does not have a default value.

Return: reference to the Element for proper methods chaining

class TableElement¶

#include <TableElement.hh>

The TableElement represents a vector<Hash> with fixed entries and types.

The TableElement represents a vector<Hash> with fixed entries and types. This means that each entry in the vector is expected to be a Hash with the same keys and same types, except for those which are set to assignment optional and have a default value.

Tables are defined by assigning a rowSchema to them, hence specifying how the Hash entries in the vector should look like. The Schema::Validator is aware of these specifications and will perform validation on these elements.

Inherits from karabo::util::GenericElement< TableElement >

Public Functions

TableElement &allowedStates(const std::vector<karabo::util::State> &value)¶

The allowedStates method serves for setting up allowed states for the element

Return

reference to the Element (to allow method’s chaining)

Parameters

states: A string describing list of possible states.
sep: A separator symbol used for parsing previous argument for list of states

virtual TableElement &assignmentMandatory()¶

The assignmentMandatory method serves for setting up a mode that requires the value of the element always being specified. No default value is possible.

Return: reference to the Element (to allow method’s chaining)

virtual TableDefaultValue<TableElement> &assignmentOptional()¶

The assignmentOptional method serves for setting up a mode that allows the value of element be optional, so it can be omitted in configuration. Default value is injected if defined. If you chain functions for definition of expected parameters the next function may be only defaultValue or noDefaultValue. When the default value is not specified (noDefaultValue) you must always check if the parameter has a value set in delivered User configuration. Example:

SOME_ELEMENT(expected)
        ...
        .assignmentOptional().defaultValue("client")
        ...
        .commit();

Return: reference to DefaultValue object allowing proper defaultValue method chaining.

virtual TableDefaultValue<TableElement> &assignmentInternal()¶

The assignmentInternal method serves for setting up the element to be internal. In the code it behaves like optional parameter but it is not exposed to the user. It is omitted when the schema is serialized to XSD. The value of this parameter should be defined programmatically. Conceptually, internal parameter with internal flag can be treated as an argument to the constructor.

Return: reference to DefaultValue (to allow method’s chaining)

virtual TableElement &init()¶

The init method serves for setting up an access type property that allows the element to be included in initial schema.

Return: reference to the Element (to allow method’s chaining)

virtual TableElement &reconfigurable()¶

The reconfigurable method serves for setting up an access type property that allows the element to be included in initial, reconfiguration and monitoring schemas.

Return: reference to the Element (to allow method’s chaining)

KARABO_DEPRECATED TableElement& karabo::util::TableElement::setNodeSchema(const Schema & schema)

This method is deprecated. Use setColumns instead.

Return

reference to the Element (chaining)

Parameters

schema:

TableElement &setColumns(const Schema &schema)¶

This method establishes content of the table, i.e. table columns and their types

Return

reference to the Element (chaining)

Parameters

schema:

TableElement &addColumns(const Schema &schema)¶

This method appends additional columns to the right side of the table.

Return

reference to the Element (chaining)

Parameters

schema:

template <class T>

TableElement &addColumnsFromClass()¶

This method appends additional columns to the table taken from some class. The class is template parameter.

Return: reference to the Element (chaining)

Private Functions

void sanitizeRowSchema(karabo::util::Schema &rowSchema)¶

Controlling method for row schema sanitization.

Exceptions

karabo::util::ParameterException: can be throw by some specific sanitization methods.

void sanitizeColumnsAccessModes(karabo::util::Schema &rowSchema)¶: Turns reconfigurable and init columns into read-only columns when the hosting table is read-only. When the hosting table is init or reconfigurable, turns every init column into a reconfigurable column.

void sanitizeNoDefaultColumns(karabo::util::Schema &rowSchema)¶

Makes sure that every non read-only column in a non read-only table has a default value set.

Default values are synthesized for the columns that don’t have a default value. The synthesized values correspond to the default initializer of the column type (e.g. 0 for int columns, false for bool columns and empty vectors for vector<..> columns).

Exceptions

karabo::util::ParameterException: if the synthesized column default values are incompatible with any attribute that already existed in the schema, like ‘minInc’ or ‘minSize’ or if the type of the column lacking a default value is not supported for table columns.

std::pair<std::string, Types::ReferenceType> findUnsupportedColumnType(const karabo::util::Schema &rowSchema)¶

Finds, in the TableElement rowSchema, a column of an unsupported type - the TableElement supports a subset of the Leaf types for valid column types.

Return: std::pair<std::string, karabo::util::Types::ReferenceType> ‘first’ is the name of the column of the invalid type (empty string if all columns are of supported types) and ‘second’ is the type of the column with the invalid type (UNKNOWN if there is no column of an invalid type).

class TimeDuration¶

#include <TimeDuration.hh>

This class represents the time duration (length) between two time points The value is hold in form of two unsigned 64bit values. The first expresses the total number of seconds, and the seconds the fractional of a second.

The default constructor create a time duration of length zero, i.e. empty.

Public Functions

TimeDuration()¶: Default constructor creates an empty time duration

TimeDuration(const karabo::util::Hash &hash)¶

Constructs a time duration from Hash. Seconds and fractions are stored as unsigned integer 64bits under the keys “seconds” and “fractions”, respectively.

Parameters

hash: Hash object (“seconds”, unsigned int 64bits, “fractions”, unsigned int 64bits)

TimeDuration(const TimeValue seconds, const TimeValue fractions)¶

Construct a time duration from separate seconds and fractions of seconds.

Parameters

seconds:
fractions: in Atto seconds

TimeDuration(const int days, const int hours, const int minutes, const TimeValue seconds, const TimeValue fractions)¶

Construct a time duration that expand over days, hours, …

Parameters

days:
hours:
minutes:
seconds:
fractions:

TimeDuration &set(const TimeValue seconds, const TimeValue fractions)¶

Set new length of, expand, or shrink a time duration

Parameters

days:
hours:
minutes:
seconds:
fractions:

bool operator==(const TimeDuration &other) const¶

Relational operations between time duration objects

Return

bool

Parameters

other: TimeDuration

TimeDuration operator+(const TimeDuration &other) const¶

Arithmetic operations over time durations

Return

TimeDuration

Parameters

other: TimeDuration

TimeDuration operator*(TimeValue factor) const¶

Create a multiple of the TimeDuration by multiplication with an unsigned, i.e. non-negative number.

Return

the new TimeDuration

Parameters

factor: that the time duration should be multiplied with

TimeDuration &operator*=(TimeValue factor)¶

Multiply by an unsigned, i.e. non-negative number.

Return

reference to *this after multiplication

Parameters

factor: that the time duration should be multiplied with

TimeDuration operator*(long long illegalSignedFactor) const¶: These multiplications with a signed value create a linker error: TimeDuration cannot be negative.

long double operator/(const TimeDuration &other) const¶

Division, i.e. how many times one time duration is bigger/smaller than another one

Return

long double

Parameters

other: TimeDuration

bool isNull() const¶

Check if the time duration is empty, i.e. of zero length.

Return: bool

uint64_t getDays() const¶

In the standard mixed format DD::HH::MM::SS::FF, How many days, hours, minutes, and seconds are in the time duration.

Return: unsigned int 64bits

TimeValue getTotalHours() const¶

Express the total length of a time duration in hours, minutes, or seconds.

Return: unsigned int 64bits

TimeValue getFractions(const TIME_UNITS unit = NANOSEC) const¶

Number of fractions of a second, default resolution is Nano seconds

Return: unsigned int 64bits

std::string format(const std::string &fmt) const¶

Serialize time duration to string/std::ostream

Return

string/ostream object holding the string representation of the time period

Parameters

format:

void fromHash(const karabo::util::Hash &hash)¶

Serialize time duration to and from Hash

Parameters

Hash:

Public Static Functions

void setDefaultFormat(const std::string &fmt)¶

Set the output format. This parameter is class variable, thus, having a global effect on future output. The default format is seconds[dot]fractions, with nanoseconds resolution. CAVEAT: ‘seconds’ is the total number of seconds modulo 60, i.e. anything that goes beyond a full minute is ignored!

Parameters

format: string object

void sanitize(TimeValue &sec, TimeValue &frac)¶: Sanitize, i.e. take care that ‘frac’ is below 1 second and adjust ‘sec’ accordingly.

Public Static Attributes

const TimeValue m_oneSecondInAtto = 1000000000000000000ULL¶: One second expressed in attoseconds.

class TimeoutException¶

#include <Exception.hh>

The TimeoutException handles exceptions that are caused by time out events

Inherits from karabo::util::Exception

class TimePeriod¶

#include <TimePeriod.hh>

This class models a time period expressed by two time points, i.e. start and stop.

The default constructor create a time period of length zero, i.e. start=stop.

Public Functions

TimePeriod()¶: Default constructor creates and empty time period

TimePeriod(const karabo::util::Hash &hash)¶

Constructs a time period from Hash. Start and stop timestamps are stored under the two reserved keys “KRB_start” and “KRB_stop”, respectively.

Parameters

hash: Hash object (“KRB_start”, any, “KRB_stop”, any)

TimePeriod(const Epochstamp &start, const Epochstamp &stop)¶

Constructs a time period from two given timestamps

Parameters

start: Epochstamp object
stop: Epochstamp object

TimeDuration getDuration() const¶

Return the time duration (i.e. length) of a time period.

Return: TimeDuration object

Epochstamp getStart() const¶

Get the start (resp. stop) timestamp

Return: Epochstamp object

void start(const Epochstamp &tm = Epochstamp())¶

Set the start (resp. stop) timestamp. By default, it set it to the current system epoch timestamp.

Parameters

tm: Epochstamp (by default, use the current system timestamp)

bool isOpen() const¶

Check if period is still open (i.e. not yet stopped)

Return: bool

bool before(const Epochstamp &tm) const¶

Check if time point (timestamp) is before, within, or after a time period.

Return

bool

Parameters

tm: Epochstamp object

void fromHash(const karabo::util::Hash &hash)¶

Serialize time period to and from Hash object.

Parameters

hash: Hash object

class TimeProfiler¶

Public Functions

TimeProfiler(const std::string &name)¶

Constructor creates a profiler with a given name

Parameters

name: profiler’s name

const std::string &getName() const¶

Returns the profiler name

Return: std::string profiler’s name

void open()¶: Initialize the profiler internal structure

void close()¶: Finalize the profiler internal structure

void startPeriod()¶: Start a new unnamed period (i.e. detail) and append it to the current open period. Unnamed periods are leaves, thus do cover other sub-periods.

void startPeriod(const std::string &periodname)¶

Start an new period with the given name. Named periods can be nested, i.e. named periods can cover other named and anonymous periods

Parameters

periodname: period’s name

void stopPeriod()¶: Close the last open period

void stopPeriod(const std::string &periodname)¶

Stops period “periodname” and all nested periods

Parameters

periodname: period’s name

const TimePeriod getPeriod(const std::string &periodname) const¶

Return the time period period “periodname” as Hash

Return

TimePeriod object

Parameters

periodname: period’s name

const TimePeriod getPeriod() const¶

Returns the overall profiler period, i.e. from open to close.

Return: TimePeriod object

const Hash &getPeriodAsHash(const std::string &periodname) const¶

Return the time period period “periodname” as Hash

Return

Hash object

Parameters

periodname: period’s name

const Hash &getPeriodAsHash() const¶

Returns the overall profiler period.

Return: Hash object

operator karabo::util::Hash()¶: Serialize the profiler into Hash object.

std::string format(const std::string &fmt, int level = std::numeric_limits<int>::max()) const¶

Serialize the profiler into string using specific time format.

Return

string object holding the string representation

Parameters

format: time format
level: deepest level

std::string sql() const¶

Serialize the profiler as SQL insert query, in preparation to be inserted into database.

Return: string object holding the SQL query string

void serialize(std::ostream &os, int level = std::numeric_limits<int>::max()) const¶

Serialize the profiler into ostream object using default time format, i.e X.Y (where X is total seconds, and Y is fraction in nanoseconds)

Parameters

os: output stream object
format: time format
level: deepest level

class Timestamp¶

#include <Timestamp.hh>

This class expresses a time point and holds it in form of an Epochstamp and Trainstamp

Public Functions

Epochstamp getEpochstamp() const¶

Return Epochstamp part of the timestamp

Return

Trainstamp getTrainstamp() const¶

Return Trainstamp part of the timestamp

Return

const unsigned long long &getSeconds() const¶

Return the seconds entry of the timestamp

Return

const unsigned long long &getFractionalSeconds() const¶

Return the fractional seconds entry of the timestamp

Return

const unsigned long long &getTrainId() const¶

Return the train id entry of the timestamp

Return

std::string toIso8601(TIME_UNITS precision = MICROSEC, bool extended = false) const¶

Generates a sting (respecting ISO-8601) for object time for INTERNAL usage (“%Y%m%dT%H%M%S%f” => “20121225T132536.789333[123456789123]”)

Return

ISO 8601 formatted string (extended or compact)

Parameters

precision: - Indicates the precision of the fractional seconds (e.g. MILLISEC, MICROSEC, NANOSEC, PICOSEC, FEMTOSEC, ATTOSEC) [Default: MICROSEC]
extended: - “true” returns ISO8601 extended string; “false” returns ISO8601 compact string [Default: false]

std::string toIso8601Ext(TIME_UNITS precision = MICROSEC, bool extended = false) const¶

Generates a sting (respecting ISO-8601) for object time for EXTERNAL usage (“%Y%m%dT%H%M%S%f%z” => “20121225T132536.789333[123456789123]Z”)

Return

ISO 8601 formatted string with “Z” in the string end (“Z” means the date time zone is using Coordinated Universal Time - UTC)

Parameters

precision: - Indicates the precision of the fractional seconds (e.g. MILLISEC, MICROSEC, NANOSEC, PICOSEC, FEMTOSEC, ATTOSEC) [Default: MICROSEC]
extended: - “true” returns ISO8601 extended string; “false” returns ISO8601 compact string [Default: false]

std::string toFormattedString(const std::string &format = std::string("%Y-%b-%d %H:%M:%S"), const std::string &localTimeZone = std::string("Z")) const¶

Formats to specified format time stored in the object

Return

formated string in the specified Time Zone

Parameters

format: The format of the time point (visit strftime for more info: http://www.cplusplus.com/reference/ctime/strftime/) [Default: “%Y-%b-%d %H:%M:%S”]
localTimeZone: - String that represents an ISO8601 time zone [Default: “Z” == UTC]

std::string toFormattedStringLocale(const std::string &localeName = std::string(""), const std::string &format = std::string("%Y-%b-%d %H:%M:%S"), const std::string &localTimeZone = std::string("Z")) const¶

Formats to specified format time stored in the object

Return

formated string in the specified Time Zone

Parameters

localeName: - String that represents the locale to be used [Default: “” == System locale]
format: The format of the time point (visit strftime for more info: http://www.cplusplus.com/reference/ctime/strftime/) [Default: “%Y-%b-%d %H:%M:%S”]
localTimeZone: - String that represents an ISO8601 time zone [Default: “Z” == UTC]

double toTimestamp() const¶

Generates a timestamp as double with seconds.fractional format (fractional precision == MICROSEC) Function necessary to use in graphs plotting in Python code (MICROSEC precision is enough)

Return: A double value with the decimal point indicating fractions of seconds

void toHashAttributes(Hash::Attributes &attributes) const¶

Formats as Hash attributes

Parameters

attributes: container to which the time point information is added

Public Static Functions

Timestamp fromHashAttributes(const Hash::Attributes &attributes)¶

Creates an Timestamp from three Hash attributes This function throws in case the attributes do no provide the correct information

Return

Timestamp object

Parameters

attributes: Hash attributes

Friends

bool operator==(const Timestamp &lhs, const Timestamp &rhs)¶

Compare if the Epochstamp and Trainstamp of this Timestamp are the same as those of other

Return

Parameters

other:

bool operator!=(const Timestamp &lhs, const Timestamp &rhs)¶

Compare if the Epochstamp and/or Trainstamp of this Timestamp are not the same of other

Return

Parameters

other:

class Trainstamp¶

#include <Trainstamp.hh>

This class expresses a time point and holds it in form of one unsigned 64bit value. The value is the European XFEL trainId which clocks in regular interval (initially 10Hz)

Public Functions

Trainstamp()¶: Default constructor creates invalid trainId (=0)

Trainstamp(const unsigned long long trainId)¶: Constructor from trainId

void toHashAttributes(Hash::Attributes &attributes) const¶

Formats as Hash attributes

Parameters

attributes: container to which the time point information is added

Public Static Functions

Trainstamp fromHashAttributes(const Hash::Attributes &attributes)¶

Creates an TrainStamp from a Hash attribute This function throws in case the attributes do no provide the correct information

Return

TrainStamp object

Parameters

attributes: Hash attributes

class Types¶

#include <Types.hh>

This class contains the types knonw to the Karabo framework as members and conversion tools for these.

Public Static Functions

template <class From, class To>

static To::ReturnType convert(const typename From::ArgumentType &type)¶

Convert one type representation to another, e.g.

size_t size = convert<FromLiteral, ToSize>("INT32");
# size is 4

Return

Parameters

type:

template <class From>

static ReferenceType from(const typename From::ArgumentType &type)¶

Return a Types::ReferenceType from an alternate representation

Types::ReferenceType r = from<FromLiteral>("INT64");

Return

Parameters

type:

template <class To>

static To::ReturnType to(const ReferenceType type)¶

Return an alternate representation of a Types::ReferenceType

Return

Parameters

type:

static bool isPointer(int type)¶

Check if the passed Types::ReferenceType is a pointer

Return

Parameters

type:

static bool isVector(int type)¶

Check if the passed Types::ReferenceType is a vector

Return

Parameters

type:

static bool isNumericPod(int type)¶

Check if the passed Types::ReferenceType is numeric plain old data type (POD)

Return

Parameters

type:

static bool isSimple(int type)¶

Check if the passed Types::ReferenceType is a type representable by a karabo::util::SimpleElement

Return

Parameters

type:

class Validator¶

#include <Validator.hh>

The Validator valididates configurations against Schemata.

The Validator class validates configurations stored in a Hash against a Schema describing the Hash. If the schema defines default values these are inserted into the Hash, depending on the assignment policy. Validation will either be successful, if the configuration Hash fullfils the requirements specified in the schema, or fail.

Public Functions

Validator()¶: Construct a Validator with default, i.e. least-restrictive ValidationRules

Validator(const Validator &other)¶

Copy constructor will just take over other’s validation rules

Parameters

other:

Validator(const ValidationRules rules)¶

Construct a Validator with given rules

Parameters

rules:

void setValidationRules(const Validator::ValidationRules &rules)¶

Set the ValidationRules for this Validator

Parameters

rules:

Validator::ValidationRules getValidationRules() const¶

Get the currrent ValidationRules for this Validator

Return

std::pair<bool, string> validate(const Schema &schema, const Hash &unvalidatedInput, Hash &validatedOutput, const Timestamp &timestamp = Timestamp())¶

Validate an unvalidated input against a schema and write the validated output to a reference. If the rules define to inject timestamp inject the current timestamp or the provided one During validation the following input is checked to fulfill the following characteristics

Return

a std::pair where the first entry is a Boolean indicating if validation was successful (true), and the second entry contains a string identifying the first validation failure encountered if validation has failed.

Parameters

schema: against which to validate
unvalidatedInput: which should be validated
validatedOutput: validated and altered according to current ValidationRules
timestamp:

all elements as defined by the Schema are present, if the validation rules do not allow for default injection missing keys. In the first case validation of a missing element only passes if a default value for the element has been defined in the schema
no elements in addition to those defined by the Schema are present, if the rules define that no additional keys are allowed
that the root element of the input Hash stands alone and represents the class id of a factorizable class if an unrooted configuration is not allowed by the validation rules

In addition for the above “sanity” checks, the Validator performs the following tasks:

for sequence values validate that they fulfill their minimum and maximum size requirements if defined by the Schema
inject timestamps for leaf elements of validatedOutput - details depending on ValidationRules:
- if injectTimestamps is false: no injection, but timestamp attributes present in unvalidatedInput are transferred to validatedOutput
- if injectTimestamps is true and forceInjectedTimestamp is false: timestamp is injected, but timestamp attributes present in unvalidatedInput are not overwritten, but are transferred to validatedOutput
- if injectTimestamps and forceInjectedTimestamp are both true: timestamp is injected even if another timestamp is in attributes of unvalidatedInput

bool hasReconfigurableParameter() const¶

Check if reconfigurable parameters exist in the last provided Schema

Return

RollingWindowStatistics::ConstPointer getRollingStatistics(const std::string &scope) const¶

Get the rolling window statistics for the element identified by scope

Return

Parameters

scope:

struct ValidationRules¶

#include <Validator.hh>

ValidationRules specify the behavior of the Validator if it encounters differences between the input Hash and the Schema defining it. The following rules may be set

injectDefaults: inject default values if a value for an element defined in the Schema is missing from the input Hash.
allowUnrootedConfiguration: allow for unrooted input Hash, i.e. one that doesn’t have a classId as the key of the root node
allowAdditionalKeys: allow additional keys in the input Hash that do not map to elements specified in the schema
allowMissingKeys: allow for keys missing in the input Hash even if an element for this key is present in the schema
injectTimestamps for leaf elements:
- if injectTimestamps is false: no injection
- if injectTimestamps is true and forceInjectedTimestamp is false: timestamp is injected, but timestamp attributes present are not overwritten
- if injectTimestamps and forceInjectedTimestamp are both true: timestamp is injected and may overwrite previous timestamp attributes

If any of the above scenarios are encountered during validation and the option is not set to true, i.e. the Validator is not allowed to resolve the issue, validation will fail.

Public Functions

ValidationRules()¶: The default constructor of validation rules is least restrictive, i.e. all resolution options are set to true.

template <typename T, template< typename ELEM, typename=std::allocator< ELEM >> class CONT = std::vector>

class VectorElement¶

#include <VectorElement.hh>

The VectorElement can be used to hold a sequence of SimpleElements.

Inherits from karabo::util::LeafElement< VectorElement< T, CONT >, CONT< T > >

Public Functions

VectorElement &minSize(const unsigned int &value)¶

Specify a minimum number of entries the vector element needs to have to pass validation

Return

Parameters

value:

VectorElement &maxSize(const unsigned int &value)¶

Specify a maximum number of entries the vector element needs to have to pass validation

Return

Parameters

value:

virtual ReadOnlySpecific<VectorElement, CONT<T>> &readOnly()¶

The readOnly method serves for setting up an access type property that allows the element to be included in monitoring schema only.

Return: reference to the Element (to allow method’s chaining)

class Version¶

#include <Version.hh>

A class providing versioning information for the Karabo framework.

Public Functions

Version(const std::string &version)¶

Creates an Version object from a string.

The version string should match a Major.Minor.Patch flavor Alpha, Beta, Release Candidates and Post-releases should be labeled following the PEP440 guidelines.

Parameters

version:

Public Static Functions

const Version &getKaraboVersion()¶

Gets a Version object of the curent Karabo’s Framework

Return: Version object

std::string getVersion()¶

Returns a string describing the current version of the Framework Equivalent of calling. karabo::util::Version::getKaraboVersion().getString();

Return: std::string

template <class E, class T = std::char_traits<E>, class Sub1 = std::allocator<E>>

class Widen¶

#include <StringTools.hh>

This class is taken from http://www.c-plusplus.de/forum/168607

Inherits from std::unary_function< const std::string &, std::basic_string< E, T, Sub1 > >

namespace confTools¶

Typedefs

typedef void (*PointerToSchemaDescriptionFunction)(Schema&)¶

using karabo::util::confTools::NthTypeOf = typedef typename std::tuple_element<N, std::tuple<Ts...> >::type

Functions

template <class Class>

PointerToSchemaDescriptionFunction getSchemaDescriptionFunction(VoidArg1FunctionExists<Class, Schema, &Class::_KARABO_SCHEMA_DESCRIPTION_FUNCTION> *)¶

Return a pointer to a valid schema description function

Parameters

template <class Class>

PointerToSchemaDescriptionFunction getSchemaDescriptionFunction(...)¶

Return a NULL-Pointer if no schema description function exists

Return

Parameters

...:

std::pair<std::string, karabo::util::Hash> splitIntoClassIdAndConfiguration(const karabo::util::Hash &rootedConfiguration)¶

Split a configuration into classId and configuration Hash

Return

a pair of class id and configuration Hash

Parameters

rootedConfiguration:

template <class… Classes>

std::string getLastClassId()¶

classId of last class - Classes must not be empty

This last class must have the static method classInfo() as provided when using the macro ‘KARABO_CLASSINFO’ in the public section of class declaration

Return: classId of the last class of the parameter pack ‘Classes’

namespace detail¶

Functions

void unpack_r(const Hash &hash, char i)¶

template <class Tfirst, class… Trest>
void unpack_r(const Hash &hash, char i, Tfirst &first, Trest&... rest)¶

void pack_r(Hash &hash, char i)¶

template <class Tfirst, class… Trest>
void pack_r(Hash &hash, char i, const Tfirst &first, const Trest&... rest)¶

namespace MetricPrefix¶

Enums

enum MetricPrefixType¶

Values:

YOTTA¶

ZETTA¶

EXA¶

PETA¶

TERA¶

GIGA¶

MEGA¶

KILO¶

HECTO¶

DECA¶

NONE¶

DECI¶

CENTI¶

MILLI¶

MICRO¶

NANO¶

PICO¶

FEMTO¶

ATTO¶

ZEPTO¶

YOCTO¶

namespace Unit¶

Enums

enum UnitType¶

Values:

NUMBER¶

COUNT¶

METER¶

GRAM¶

SECOND¶

AMPERE¶

KELVIN¶

MOLE¶

CANDELA¶

HERTZ¶

RADIAN¶

DEGREE¶

STERADIAN¶

NEWTON¶

PASCAL¶

JOULE¶

ELECTRONVOLT¶

WATT¶

COULOMB¶

VOLT¶

FARAD¶

OHM¶

SIEMENS¶

WEBER¶

TESLA¶

HENRY¶

DEGREE_CELSIUS¶

LUMEN¶

LUX¶

BECQUEREL¶

GRAY¶

SIEVERT¶

KATAL¶

MINUTE¶

HOUR¶

DAY¶

YEAR¶

BAR¶

PIXEL¶

BYTE¶

BIT¶

METER_PER_SECOND¶

VOLT_PER_SECOND¶

AMPERE_PER_SECOND¶

PERCENT¶

NOT_ASSIGNED¶