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 boost::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 boost::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

boost::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 boost::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 boost::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 boost::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

boost::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 boost::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 boost::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 = boost::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 boost::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 boost::function<void(const std::string&, const std::string&, const ValueType&, const karabo::util::Timestamp&, const boost::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 boost::any userData.
  • userData: to be passed to the callback as boost::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 boost::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 for configuration changes monitoring.

In order to receive notifications about configuration changes for any of the monitored devices, one must connect a handler for those changes by calling DeviceClient::connectDevicesMonitor.

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 boost::function<void(const std::string&, const karabo::util::Hash&, const boost::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 boost::any userData.
  • userData: to be passed to the callback as boost::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 boost::function<void (const karabo::util::Hash&, const MetaData&)> to be called whenever data arrives
    • inputHandler boost::function<void (const InputChannel::Pointer&)> to be called whenever data arrives
    • eosHandler boost::function<void (const InputChannel::Pointer&)> called for EOS
    • statusTracker boost::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: boost::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: boost::function<void (const InputChannel::Pointer&)> called for EOS if given
  • inputHandler: boost::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: boost::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: boost::function<void (const InputChannel::Pointer&)> called for EOS if given
  • inputHandler: boost::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::deadline_timer m_signalsChangedTimer

defines whether aging is running or not

boost::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 boost::function<void(karabo::net::ConnectionStatus)> &status = boost::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 boost::function<void(karabo::net::ConnectionStatus)> &status = boost::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

boost::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 boost::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

boost::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(boost::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 boost::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 boost::function<void(const BeginTemporarySessionResult&)>
using karabo::devices::ExpirationHandler = typedef boost::function<void(const ExpiredTemporarySessionInfo&)>

Handler for expired temporary session events.

using karabo::devices::EminentExpirationHandler = typedef boost::function<void(const EminentExpirationInfo&)>

Handler for “temporary session about to expire” events.

using karabo::devices::AsyncHandler = typedef boost::function<void()>
using karabo::devices::InfluxResponseHandler = typedef boost::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 boost::shared_ptr<std::atomic<unsigned int>> &counter)

Helper for connecting to both signalChanged and signalStateChanged.

void updateTableAndFlush(const boost::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 boost::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:

  1. 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;
  2. 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;
  3. 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 boost::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 boost::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 boost::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 boost::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 boost::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 boost::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 boost::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 boost::shared_ptr<PropertyHistoryContext> &ctxt)

Triggers the retrieval of the property values in an ongoing GetPropertyHistory process.

Parameters
  • context:

void asyncGetPropertyValuesMean(const boost::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 boost::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 boost::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 boost::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 boost::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 boost::any &ioEventHandler)

Register a handler to be called for I/O events

void registerEndOfStreamEventHandler(const boost::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

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

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 boost::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 boost::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 boost::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 boost::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

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 boost::function objects.

Inherits from karabo::io::InputHandler

Public Functions

void registerIOEventHandler(const boost::any &eventHandler)

Register an input handler for I/O events. The handler must be of a callable type.

Parameters
  • eventHandler:

void registerEndOfStreamEventHandler(const boost::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

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 boost::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 boost::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 boost::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 boost::function<void(const HttpResponse&)>
using karabo::net::InfluxConnectedHandler = typedef boost::function<void(bool)>
typedef boost::shared_ptr<std::vector<char>> VectorCharPointer
typedef boost::shared_ptr<Channel> ChannelPointer
using karabo::net::AuthOneTimeTokenHandler = typedef boost::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 boost::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(boost::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

boost::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

boost::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 boost::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

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

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 boost::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

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(boost::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<boost::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 boost::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 boost::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 boost::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

virtual void readAsyncHashPointer(const ReadHashPointerHandler &handler)

Asynchronously reads data into a hash. All memory management is done by the API.

Parameters

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

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

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, boost::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 boost::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 boost::function which takes const boost::system::error_code& as its only argument.

virtual void writeAsyncVectorPointer(const boost::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 boost::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 boost::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 boost::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 boost::function which takes const boost::system::error_code& as its only argument.

virtual void writeAsyncHashVectorPointer(const karabo::util::Hash &header, const boost::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 boost::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 boost::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 boost::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 boost::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 boost::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 boost::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 boost::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, boost::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

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(boost::mutex::scoped_lock &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 boost::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 boost::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(boost::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

boost::function<void()> wrap(boost::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(boost::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, boost::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

void readAsyncHashPointer(const ReadHashPointerHandler &handler)

Asynchronously reads data into a hash. All memory management is done by the API.

Parameters

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

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

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 boost::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 boost::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 boost::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 boost::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 boost::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 boost::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 boost::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 boost::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 boost::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 boost::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

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 boost::function<void(karabo::util::Hash::Pointer, karabo::util::Hash::Pointer)>
using karabo::net::consumer::ErrorNotifier = typedef boost::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 boost::function<void(const std::vector<karabo::util::Hash>&)> ShowConnectionsHandler
typedef boost::function<void(const std::vector<unsigned long long>&, const std::vector<unsigned long long>&)> ShowStatisticsHandler
typedef boost::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 boost::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 boost::function<void(const karabo::net::ErrorCode&)> &handler = boost::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, boost::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 boost::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

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

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, boost::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(boost::function<void()> &&readyForNextHandlerboost::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 which happens when sending data to all connected InputChannels that should receive the written data (note that for other InputChannels data may be dropped or queued) has

  • started: ‘readyForNextHandler’
  • finished, as confirmed by Tcp, or stopped due to disconnection: ‘writeDoneHandler’

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 maye be called again
  • writeDoneHandler: callback when sending is finished, i.e. 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.

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(boost::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

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(boost::mutex::scoped_lock &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, boost::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 boost::enable_shared_from_this< SignalSlotable >

Subclassed by karabo::core::BaseDevice, karabo::core::BaseFsm, karabo::core::DeviceServer, karabo::core::StartStopInterface

Public Types

typedef boost::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 boost::function<void()> &successHandler = boost::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 boost::function<void()> &successHandler = boost::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 boost::function<void()> &successHandler = boost::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 boost::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 boost::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(boost::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 boost::shared_ptr<boost::mutex> &mut, const boost::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 boost::shared_ptr<boost::asio::deadline_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<boost::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

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

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 boost::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 boost::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)
void byteArrayDeleter(const char *dataPtr)
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 >

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:

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:

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 boost::any &value)

Construct a Hash element from a boost::any value

Parameters
  • key: identifies the element
  • value: of the element

Element(const KeyType &key, boost::any &&value)

Construct a Hash element from a boost::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 boost::shared_ptr<ValueType> &value)

Set the value to a boost::shared_ptr of ValueType

Parameters
  • value:

void setValue(const boost::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 boost::any &value)

Set a boost::any value to the Element

Parameters
  • value:

void setValue(boost::any &&value)

Set a boost::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

boost::any &getValueAsAny()

Return the value as boost::any. Does not throw

Return

const boost::any &getValueAsAny() const

Return the value as boost::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 boost::any &getAttributeAsAny(const std::string &key) const

Return the value as boost::any. Does not throw

Return
Parameters
  • key: identifying the attribute

boost::any &getAttributeAsAny(const std::string &key)

Return the value as boost::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 boost::is_base_of<Hash, Hash>::type is not boost::false_type), this is a no-op as well.

Parameters
  • value:
  • e:

template <typename ValueType>
template<>
struct SetClassIdAttribute<ValueType, boost::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

TimeDuration operator-(const Epochstamp &other) const

Time duration is the difference between two timestamps

Return
TimeDuration object
Parameters

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

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

class Exception
#include <Exception.hh>

Karabo’s main exception class. Inherits from std::exception.

Inherits from std::exception

Subclassed by karabo::util::CastException, karabo::util::CudaException, karabo::util::DoocsException, karabo::util::HardwareException, karabo::util::ImageException, karabo::util::InitException, karabo::util::IOException, karabo::util::LockException, karabo::util::LogicException, karabo::util::MessageException, karabo::util::NetworkException, karabo::util::NotImplementedException, karabo::util::NotSupportedException, karabo::util::ParameterException, karabo::util::PropagatedException, karabo::util::PythonException, karabo::util::ReconfigureException, karabo::util::RemoteException, karabo::util::SchemaException, karabo::util::SignalSlotException, karabo::util::SystemException, karabo::util::TimeoutException

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 boost::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 boost::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 boost::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:

boost::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 boost::any.

Return
boost::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<boost::shared_ptr<T>>

Inherits from true_type

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:

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 boost::any &getAny(const KeyType &key) const

Get the Element identified by key as a boost::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, boost::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

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

TimeDuration operator+(const TimeDuration &other) const

Arithmetic operations over time durations

Return
TimeDuration
Parameters

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

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

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

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

void fromHash(const karabo::util::Hash &hash)

Serialize time period to and from Hash object.

Parameters

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

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