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)¶
-
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 idsec
: current system secondsfrac
: current fractional secondsperiod
: 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 idsec
: unix secondsfrac
: 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 idsec
: unix secondsfrac
: fractional seconds (i.e. attoseconds)period
: interval between ids in microseconds
-
virtual void
-
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 periodicallytimeout
: time in milliseconds auxiliary thread is waiting on the request queue; 0 means nowait mode; ,-1 means waiting foreverrepetition
: -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 expirationtimeout
: timeout for receiving from queuerepetition
: 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 ×tamp)¶ 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 updateupdates
: 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 ×tamp)¶ 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 namedata
: Hash with the data
-
void
writeChannel
(const std::string &channelName, const karabo::util::Hash &data, const karabo::util::Timestamp ×tamp, 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 namedata
: Hash with the datatimestamp
: 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 ×tamp)¶ 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 updatevalue
: updated value
- template <class ValueType>
-
void
setNoValidate
(const std::string &key, const ValueType &value, const karabo::util::Timestamp ×tamp)¶ 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 updatevalue
: updated valuetimestamp
: 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 ×tamp)¶ 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 filtertags
: 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 ¤tState)¶ 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 ¤tState, 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 toother
: 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 ¤tState, const karabo::util::Timestamp ×tamp)¶ 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 totimestamp
: 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 ¤tState, karabo::util::Hash other, const karabo::util::Timestamp ×tamp)¶ 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 toother
: 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 messagedetailedMessage
: 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 setneedsAcknowledging
: if this condition will require acknowledgment on the alarm servicedescription
: 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 forsep
: 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 idsec
: current system secondsfrac
: current fractional secondsperiod
: 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 TableElementvalue
: is the new maximum size of the parameteremitFlag
: 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 ×tamp)¶ Internal method for set(Hash, Timestamp), requiring m_objectStateChangeMutex to be locked
-
void
setNoValidateNoLock
(const karabo::util::Hash &hash, const karabo::util::Timestamp ×tamp)¶ 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 slotcallee
: 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
-
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 devicebroker
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_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.
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 lassimplicitInit
: 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.
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 lassserviceDeviceIds
: 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 deviceServerclassId
: 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 deviceServerclassId
: 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 fromclassId
: 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 availableclassId
: of the device to be instantiateconfiguration
: 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 availableconfiguration
: 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 availableclassId
: of the device to be instantiateconfiguration
: 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 availableconfiguration
: 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 killtimeoutInSeconds
: 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 killtimeoutInSeconds
: 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 ofhash
: 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 onkey
: path to the property to check if it has a given attributeattribute
: to check forkeySep
: 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 fromkey
: identifying the propertykeySep
: 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 fromkey
: identifying the propertyvalue
: reference to write the property value tokeySep
: 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 fromkey
: identifying the propertykeySep
: 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 fromkey
: identifying the propertykeySep
: 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 propertykey
: path to the property on the devicefrom
: karabo::util::Epochstamp in Iso8601 format signifying the start of the time interval to get the history fromto
: karabo::util::Epochstamp in Iso8601 format signifying the end of the time interval to get the history from. If left empty default to nowmaxNumData
: 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 propertykey
: path to the property on the devicefrom
: karabo::util::Epochstamp in Iso8601 format signifying the start of the time interval to get the history fromto
: karabo::util::Epochstamp in Iso8601 format signifying the end of the time interval to get the history from. If left empty default to nowmaxNumData
: 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 fortimepoint
: 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 monitoredkey
: path to the property to be monitoredcallbackFunction
: 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 monitoredkey
: path to the property to be monitoredcallbackFunction
: 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 fromkey
: 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 tocallbackFunction
: 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 tocallbackFunction
: 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 channelchannel
: is name of the output channeldataHandler
: boost::function<void (const karabo::util::Hash&, const MetaData&) to be called whenever data arrivesinputChannelCfg
: configures via InputChanel::create(..) - use default except you know what your are doing for the expert: “connectedOutputChannels” will be overwritteneosHandler
: boost::function<void (const InputChannel::Pointer&)> called for EOS if giveninputHandler
: 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 arrivesinputChannelCfg
: configures via InputChanel::create(..) - use default except you know what your are doing for the expert: “connectedOutputChannels” will be overwritteneosHandler
: boost::function<void (const InputChannel::Pointer&)> called for EOS if giveninputHandler
: 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 channelchannel
: 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 devicekey
: The parameter key (can be nested using “.” as separator)attributeKey
: The attribute keyattributeValue
: The attribute valuetimeoutInSeconds
: 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 onkey
: path to the property to setvalue
: to settimeoutInSeconds
: maximum timeout until set operation fails, set to -1 to wait foreverkeySep
: 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 onkey
: path to the property to setvalue
: to setkeySep
: 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 onvalues
: a Hash containing the to be set value in a path structure indicating which properties to settimeoutInSeconds
: 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 onvalues
: 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 deviceIdcommand
: 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 devideIdcommand
: The commandtimeoutInSeconds
: 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 lockedrecursive
: if true, recursive locks on this device are allowedtimeout
: 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 instanceInfoinstanceInfo
: 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 §ion) 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.
-
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
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 idsec
: current system secondsfrac
: current fractional secondsperiod
: 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 cancelledid
: 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.
-
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 devicedeviceId
: the deviceId of the device to lockrecursive
: allow recursive locking if true
-
~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 argumentsargv
: String array of commandline options
-
DeviceServer::Pointer
-
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
:
-
-
enum
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
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 removevectorProp
: 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 addvectorProp
: 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
Helper for connecting to both signalChanged and signalStateChanged.
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
“Flush” data accumulated in the internal cache to the external storage (file, database,…)
-
bool
allowLock
() const¶ This device may not be locked
- Return
- false
-
void
-
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 loggedaddIfNotYetInMap
: 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/classesnewList
: new configuration for blocked devices/classes
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.
-
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 ¶ms)¶ 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 forproperty
: path to the property for which to get the history fromparams
: Hash containing optional limitations for the query:- from: iso8601 timestamp indicating the start of the interval to get history from
- to: iso8601 timestamp indicating the end of the interval to get history from
- maxNumData: maximum number of data points to retrieve starting from start
-
void
slotGetConfigurationFromPast
(const std::string &deviceId, const std::string &timepoint)¶ Request the configuration Hash and schema of a device at a given point at time. Depending on the device status and on the availability of logged data, the configuration and schema returned will be:
- If the device was online and logging data at the given timepoint, the configuration and the schema will be the ones that were active at the timepoint;
- If the device was offline at the given timepoint, but there is data logged for it before the timepoint, the last active configuration and schema before that timepoint will be returned;
- If the device was offline at the given timepoint and there’s no data logged before the timepoint, an empty configuration and an empty schema will be returned.
The slot replies with a tuple of 4 values. The first two are the Hash and Schema objects containing the configuration Hash and the corresponding device schema for timepoint. The third is a boolean whose true value indicates the device was online and actively logging data at the timepoint. The fourth value is the string form of the timepoint for the configuration returned and will be the latest timestamp among the timestamps of the properties in the configuration returned.
- Parameters
deviceId
: of the device to get the configuration fromtimepoint
: 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
-
void
-
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 timestampsthe
: 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 onestamp
: - 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.
-
virtual void
-
class
FileDataLogger
¶ Inherits from karabo::devices::DataLogger
Private Functions
“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 timestampsthe
: 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
-
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 ×tamp, 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
-
void
-
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 ¤tSuspects)¶ 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 slotchannel
:
-
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 clientchannel
: the TCP channel for the connection being registereduserId
: the ID of the user logged in the connected GUI ClientoneTimeToken
: 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 closedchannel
: the TCP channel for the recently established connection with a GUI clientinfo
: 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 serverinfo
: 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
fromchannel
. The further actions are determined by the contents of thetype
property ininfo
. Valid types and there mapping to methods are given in the following table:¶ 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 closedchannel
: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 succeededchannel
: who requested the callinput
: will be copied to the keyinput
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 succeededchannel
: who requested the callinfo
: the input info Hashreply
: 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 originatesinfo
: 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 otherwiserequestGeneric
- 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 typereconfigureReply
that containsinput
: the Hash given here asinfo
success
: bool whether reconfiguration succeededfailureReason
: string with failure reason
- optional int at
timeout
: if a reply should be reported back, defines seconds of timeout. In casetimeout
is missing, timeout errors will reportsuccess
as true but provides afailureReason
mentioning the timeout
- Parameters
channel
: to potentially send “reconfigureReply”info
:
- string at
-
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 succeededchannel
: who requested the callinput
: will be copied to the keyinput
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 typeexecuteReply
that containsinput
: the Hash given here asinfo
success
: bool whether execution succeededfailureReason
: string with failure reason
- optional int at
timeout
: if a reply should be reported back, defines seconds of timeout. In casetimeout
is missing, timeout errors will reportsuccess
as true but provides afailureReason
mentioning the timeout- Parameters
channel
:info
:
- string at
-
void
onInitDevice
(WeakChannelPointer channel, const karabo::util::Hash &info)¶ Enqueues a future device instantiation. The relevant information will be stored in
m_pendingDeviceInstantiations
andinitSingleDevice
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 atdeviceId
as given ininfo
. The reply from the device server is registered to theinitReply
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 callingchannel
in form of a hash message withtype=initReply
,deviceId
,success
andmessage
fields.- Parameters
channel
:givenDeviceId
:givenConfig
:success
:message
:
-
void
onGetDeviceConfiguration
(WeakChannelPointer channel, const karabo::util::Hash &info)¶ requests the current device configuration for
deviceId
specified ininfo
and sends it back in a hash message onchannel
. The message contains the following fields:type=deviceConfiguration
,deviceId
andconfiguration
. 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
ininfo
to shutdown.- Parameters
info
:
-
void
onKillDevice
(WeakChannelPointer channel, const karabo::util::Hash &info)¶ instructs the device specified by
deviceId
ininfo
to shutdown.- Parameters
info
:
-
void
onStartMonitoringDevice
(WeakChannelPointer channel, const karabo::util::Hash &info)¶ Registers a monitor on the device specified by
deviceId
ininfo
Upon changes of device properties they will be forwarded tochannel
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
forchannel
.- Parameters
channel
:info
:
-
void
onStopMonitoringDevice
(WeakChannelPointer channel, const karabo::util::Hash &info)¶ De-registers the client connected by
channel
from the device specified bydeviceId
ininfo
. If this is the last channel monitoringdeviceId
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 byserverId
ininfo
. This is done through the device client. A hash reply is sent out overchannel
containingtype=classSchema
,serverId
,classId
andschema
.- Parameters
channel
:info
:
-
void
onGetDeviceSchema
(WeakChannelPointer channel, const karabo::util::Hash &info)¶ requests a device schema for the device specified by
deviceId
ininfo
. This is done through the device client. A hash reply is sent out overchannel
containingtype=deviceSchema
,deviceId
, andschema
.- Parameters
channel
:info
:
-
void
onGetPropertyHistory
(WeakChannelPointer channel, const karabo::util::Hash &info)¶ requests the history for a
property
ondeviceId
in the time ranget0
andt1
as specified ininfo
. Additional the maximum number of data points may be specified inmaxNumData
. The request is asynchronously sent to the device logger logging information fordeviceId
. The reply from the logger is then forwarded to the client onchannel
using thepropertyHistory
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 indata
for theproperty
ondeviceId
to the client connected onchannel
. The hash reply is of the formattype=propertyHistory
,deviceId
,property
,success
,data
andfailureReason
which states the failure reason if any.- Parameters
channel
:success
: whether the request succeededdeviceId
:property
:data
:
-
void
onGetConfigurationFromPast
(WeakChannelPointer channel, const karabo::util::Hash &info)¶ Request configuration for a
device
at point in timetime
as specified ininfo
. Theinfo
hash can as well have apreview
boolean which is send back to the client. The request is asynchronously sent to the device logger logging information fordeviceId
. The reply from the logger is then forwarded to the client onchannel
using theconfigurationFromPast
history callback in case of success orconfigurationFromPastError
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 bychannelName
ininfo
in casesubscribe
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 thedelayOnInput
property of the gui server. Network data from the pipe-lined processing connection is handled by theonNetworkData
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 apriority
string and ainstanceId
string.- Parameters
channel
:info
:
-
void
forwardSetLogReply
(bool success, WeakChannelPointer channel, const karabo::util::Hash &input)¶ Callback helper for
onSetLogPriority
- Parameters
success
: whether call succeededchannel
: who requested the callinput
: will be copied to the keyinput
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 anddata
holding the data.- Parameters
channelName
: name of the InputChannel that provides these datadata
: the data coming from channelNamemeta
: corresponding meta data
-
void
sendSystemTopology
(WeakChannelPointer channel)¶ sends the current system topology to the client connected on
channel
. The hash reply containstype=systemTopology
and thesystemTopology
.- Parameters
channel
:
-
void
instanceNewHandler
(const karabo::util::Hash &topologyEntry)¶ sends the current system topology to the client connected on
channel
. The hash reply containstype=systemVersion
and thesystemVersion
.- 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 byonStartMonitoringDevice
.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 projectsinstanceId
: 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 devicetype
: the type of the update: can be alarmUpdate, alarmInitupdateRows
: 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 toinfo
: 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 toinfo
: 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 fieldsreplyToAllClients
: 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 updateinfo
: 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 updatereply
: 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 formattype
: string which will afterwards contain typeinstanceId
: 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 originatesinfo
: 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 originatesinfo
: 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 originatesinfo
: 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 originatesinfo
: 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 originatesinfo
: 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 originatesinfo
: 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 originatesinfo
: 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 originatesinfo
: 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 toreplyType
: type of replyreply
: 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 notdeviceId
: of the project manager devicetype
: 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.
-
void
-
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
-
void
-
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
“Flush” data accumulated in the internal cache to the external storage (file, database,…)
-
void
-
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 timestampsthe
: 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 startssortedPaths
: 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 onestamp
: - 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.
-
void
-
class
InfluxLogReader
¶ Inherits from karabo::devices::DataLogReader
Private Functions
Triggers the retrieval of the number of data points for a given device property during a time interval.
- Parameters
context
:
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
:
Triggers the retrieval of the property values in an ongoing GetPropertyHistory process.
- Parameters
context
:
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
:
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
:
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
:
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.
-
void
-
struct
PropFileInfo
¶ - #include <FileLogReader.hh>
A compound structure holding data on an logger archive file.
-
using
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
- 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 intofilename
: 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 savefilename
: 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::stringgetIODataType
<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 PYTHOninputType
: 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
-
virtual void
-
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 >
- 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
Private Functions
-
void
update
()¶ Calling update tells that the output channel should cycle its state to be ready for new data written to it.
-
void
- template <class T>
-
class
BinarySerializer
¶ Public Functions
-
virtual void
save
(const T &object, std::vector<char> &archive) = 0¶ Save an object to a binary archive
- Parameters
object
: to savearchive
: to save to - some implementations clear() it before appending (e.g. in HashBinarySerializer), some do not (e.g. in SchemaBinarySerializer)
-
virtual void
save2
(const T &object, std::vector<char> &archive) = 0¶ Save an object by appending it to a binary archive
- Parameters
object
: to savearchive
: 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 intoarchive
: binary archive containing the datanBytes
: 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 intoarchive
: binary archive containing the data
-
virtual void
load
(T &object, const karabo::io::BufferSet &archive)¶ Load an object from BufferSet archive
- Parameters
object
:archive
: BufferSet object
-
void
loadLastFromSequence
(T &object, const char *archive, const std::size_t nBytes)¶ Loads the last object from a sequence of concatenated binary serialized objects of the same type. Sequences with only one object are also supported.
- Parameters
object
: to load the last instance into.archive
: sequence containing 1 or more objects of type T in binary serialized form.
Save an object to a binary archive
- Parameters
object
: to savearchive
: to save to
Load an object from a binary archive.
- Return
- number of processed bytes in archive
- Parameters
object
: to load data intoarchive
: binary archive containing the datanBytes
: size in bytes of the data archive
Load an object from a binary archive.
- Return
- number of processed bytes in archive
- Parameters
object
: to load data intoarchive
: 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 datanBytes
: 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 intoarchive
: binary archive containing the datanBytes
: 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 intoarchive
: binary archive containing the data
-
virtual void
-
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 buffertype
: - 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
-
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
Emplace a shared pointer to a vector at the end of the BufferSet
-
void
appendTo
(BufferSet &other, bool copy = true) const¶ Append the contents of this BufferSet to another BufferSet
- Parameters
other
: the BufferSet to append tocopy
:
-
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
-
- 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
-
void
-
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 savearchive
: 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 savearchive
: 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 intoarchive
: binary archive containing the datanBytes
: size in bytes of the data archive
-
void
load
(karabo::util::Hash &object, const BufferSet &archive)¶ Load an object from BufferSet archive
- Parameters
object
:archive
: BufferSet object
-
void
save
(const std::vector<karabo::util::Hash> &objects, std::vector<char> &archive)¶ Save a vector of objects into a binary archive
- Parameters
objects
:archive
:
-
size_t
load
(std::vector<karabo::util::Hash> &objects, const char *archive, const size_t nBytes)¶ Load a vector of objects from a binary archive.
- Return
- number of processed bytes in archive
- Parameters
objects
: to load data intoarchive
: binary archive containing the datanBytes
: size in bytes of the data archive
-
virtual
~HashBinarySerializer
()¶ Destructor.
-
void
-
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 savearchive
: 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 intoarchive
: 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 intoarchive
: to load the object from
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
-
void
- 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 >
-
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)
-
virtual InputElement &
-
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
-
virtual void
- 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.
-
virtual void
-
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)
-
virtual OutputElement &
-
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 savearchive
: to append to - no clear() called
-
void
-
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 >
- 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 >
- 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
Private Functions
-
void
update
()¶ Calling update tells that the output channel should cycle its state to be ready for new data written to it.
-
void
- 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 savearchive
: 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 savearchive
: 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 intoarchive
: 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 intoarchive
: 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 intoarchive
: 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 intoarchive
: to load the object fromnBytes
: 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 savearchive
: 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 savearchive
: 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 datanBytes
: size in bytes of the data archive
-
-
typedef std::vector<char>
The karabo::net Namespace¶
-
namespace
karabo
::
net
¶ Namespace for package net
Typedefs
-
typedef boost::system::error_code
ErrorCode
¶
-
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
¶
-
using
karabo::net::AuthOneTimeTokenHandler = typedef boost::function<void(const OneTimeTokenAuthorizeResult&)>
-
using
karabo::net::AsyncHandler = typedef std::function<void(const boost::system::error_code)>
Enums
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
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_servicecategory
: the category used for loggingerrorMessage
: will be part of the logged errordelayInMilliSec
: 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 signalsignalFunction
: 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 handlererrorNotifier
: - 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 handlererrorNotifier
: - 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 containbody
: of the messagepriority
: 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
-
Broker::Pointer
-
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
¶
-
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 contextinstanceId
: the client id - will usually be the name of the queue that will be subscribedqueueArgs
: the arguments passed to queue creationreadHandler
: a read handler for all received messages (if an invalid function, must call setReadHandler before the first subscription)
-
void
setReadHandler
(ReadHandler readHandler)¶ (Re-)set the read handler that will be called for all received messages
- Parameters
readHandler
: A valid read function (karabo::util::ParameterException if not valid)
-
void
asyncSubscribe
(const std::string &exchange, const std::string &routingKey, AsyncHandler onSubscriptionDone)¶ Asynchronously subscribes client
If subscription is reported to have failed, it will be tried again
- at next subscription or
- if reviveIfReconnected() is called.
- Parameters
exchange
: name of AMQP exchange that will be created if not yet existingroutingKey
: the AMQP routing keyonSubscriptionDone
: 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 fromroutingKey
: the AMQP routing key to unsubscribe fromonUnsubscriptionDone
: 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
Asynchronously publish data
- Parameters
exchange
: the exchange…routingKey
: …and the routingkey for the datadata
: 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
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.
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
urls
: vector of broker urls to try to connect to in asyncConnect (throws karabo::util::NetworkException if vector is empty)
-
std::string
getCurrentUrl
() const¶ Return currently used broker URL (either already connected to it or the currently/next tried one)
-
bool
isConnected
() const¶ Whether connection established
-
std::string
connectionInfo
() const¶ Various info about internal connection (for debug logs)
-
void
asyncConnect
(AsyncHandler onComplete)¶ Asynchronously connect to any of the broker addresses passed to the constructor.
Addresses will be tried in the order they have been passed. Can be called from any thread.
- Parameters
onComplete
: AsyncHAndler called (not from within asyncConnect) about success or failure of connection attempt. If all addresses failed, the error code passed is the one of the last address passed to the constructor. The handler (if valid) will be called from within the internal io context, but not within the scope of asyncConnect.
-
void
asyncCreateChannel
(ChannelCreationHandler onComplete)¶ Trigger creation of an amqp channel and return it via the handler.
If not connected yet, try to connect first. Note that if connection lost, channel creation will not be tried again, but failure is reported.
Can be called from any thread.
- Parameters
onComplete
: A valid (!) ChannelCreationHandler that will be called from within the internal io context, but not within the scope of asyncCreateChannel.
-
void
registerForReconnectInfo
(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.
-
enum
-
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 contextinstanceId
: the client id - will usually be the name of the queue that will be subscribedqueueArgs
: the arguments passed to queue creationreadHandler
: a valid read handler for all received messageserrorReadHandler
: 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
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
Deserializes ‘data’ input into Hash for header and body, adds exchange and key to the header and calls handler passed to constructor
-
void
-
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 signalsignalFunction
: 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 handlererrorNotifier
: - 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 handlererrorNotifier
: - error handler
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.
-
virtual Broker::Pointer
-
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 memorysize
: 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 informationdata
: Pre-allocated contiguous block of memorysize
: 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 informationdata
: 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 informationdata
: 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 memorysize
: This number of bytes will be copied into datahandler
: 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 donehandler
: handler with signature ReadStringHandler, i.e. void (const boost::system::error_code&, std::string&) is called. second handler parameter is the read string with terminator stripped away
-
virtual void
readAsyncVector
(const ReadVectorHandler &handler)¶ Asynchronously reads data into a vector<char>. All memory management is done by the API.
- Parameters
handler
: Call-function of signature: void (Channel::Pointer, const std::vector<char>&)
-
virtual void
readAsyncString
(const ReadStringHandler &handler)¶ Asynchronously reads data into a string. All memory management is done by the API. NOTE: A string in general is not storing data contiguously. Thus, an additional copy under the hood is needed which makes this interface slightly slower.
- Parameters
handler
: Call-function of signature: void (Channel::Pointer, const std::string&)
-
virtual void
readAsyncHash
(const ReadHashHandler &handler)¶ Asynchronously reads data into a hash. All memory management is done by the API.
- Parameters
handler
: Call-function of signature: void (Channel::Pointer, const karabo::util::Hash&)
-
virtual void
readAsyncHashPointer
(const ReadHashPointerHandler &handler)¶ Asynchronously reads data into a hash. All memory management is done by the API.
- Parameters
handler
: Call-function of signature: void (Channel::Pointer, const karabo::util::Hash&)
-
virtual void
readAsyncVectorPointer
(const ReadVectorPointerHandler &handler)¶ Asynchronously reads data into a vector<char>. All memory management is done by the API.
- Parameters
handler
: Call-function of signature: void (Channel::Pointer, const std::vector<char>&)
-
virtual void
readAsyncHashVector
(const ReadHashVectorHandler &handler)¶ Asynchronously reads data into a hash header and a vector<char>. All memory management is done by the API.
- Parameters
handler
: Call-function of signature: void (Channel::Pointer, const karabo::util::Hash&, const std::vector<char>&)
-
virtual void
readAsyncHashString
(const ReadHashStringHandler &handler)¶ Asynchronously reads data into a hash header and a string. All memory management is done by the API. NOTE: A string in general is not storing data contiguously. Thus, an additional copy under the hood is needed which makes this interface slightly slower.
- Parameters
handler
: Call-function of signature: void (Channel::Pointer, const karabo::util::Hash&, const std::string&)
-
virtual void
readAsyncHashHash
(const ReadHashHashHandler &handler)¶ Asynchronously reads data into a hash header and a hash body. All memory management is done by the API.
- Parameters
handler
: Call-function of signature: void (const ErrorCode&, const karabo::util::Hash&, const karabo::util::Hash&)
-
virtual void
readAsyncHashPointerHashPointer
(const ReadHashPointerHashPointerHandler &handler)¶ Asynchronously reads data into a hash header and a hash body. All memory management is done by the API.
- Parameters
handler
: Call-function of signature: void (const ErrorCode&, const karabo::util::Hash&, const karabo::util::Hash&)
-
virtual void
readAsyncHashVectorPointer
(const ReadHashVectorPointerHandler &handler)¶ Asynchronously reads data into a hash header and a vector<char>. All memory management is done by the API.
- Parameters
handler
: Call-function of signature: void (const ErrorCode&, const karabo::util::Hash&, const std::vector<char>&)
-
virtual void
readAsyncHashVectorBufferSetPointer
(const ReadHashVectorBufferSetPointerHandler &handler)¶ Asynchronously reads data into a hash header and into a vector of BufferSet pointers. All memory management is done by the API.
- Parameters
handler
: Call-function of signature: void (const ErrorCode&, const karabo::util::Hash&, const std::vector<karabo::io::BufferSet::Pointer>&)
-
virtual void
write
(const char *data, const size_t &size)¶ Synchronous write. The function blocks until all bytes are written.
- Parameters
data
: Pointer to a contiguous block of memory that should be writtensize
: 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 writtendata
: Pointer to a contiguous block of memory that should be writtensize
: 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 writtendata
: 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 layoutbody
: vector of BufferSet pointers
Synchronous write. The function blocks until all bytes are written.
- Parameters
header
: containing metadata for the data being writtendata
: 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 writtendata
: 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 writtendata
: 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 writtensize
: This number of bytes will be writtenhandler
: 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 writtenhandler
: 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.
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 pointerhandler
: 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 typeshandler
: 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 writtendata
: Pointer to a contiguous block of memory that should be writtensize
: This number of bytes will be writtenhandler
: 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 writtendata
: vector of chars containing the data to be writtenhandler
: 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.
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 writtendata
: vector of chars containing the data to be written, passed as a shared pointerhandler
: 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 writtenbody
: data contained in a Hash with no particular structure, but serializable, i.e. containing no non-karabo data types or Hash derived typeshandler
: 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 writtenbody
: data as a vector of BufferSet::Pointerhandler
: 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 writtensize
: This number of bytes will be writtenprio
: 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 writtenprio
: the priority of this write operation
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 pointerprio
: 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 messageprio
: 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 typesprio
: the priority of this write operationcopyAllData
: 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 writtenheader
: containing metadata for the data being writtensize
: This number of bytes will be writtenprio
: 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 writtendata
: vector of chars containing the data to be writtenprio
: the priority of this write operation
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 writtendata
: vector of chars containing the data to be written, passed as a shared pointerprio
: 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 writtendata
: passed as a string were each character represents one byte of the messageprio
: 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 writtendata
: is contained in a Hash with no particular structure, but serializable, i.e. containing no non-karabo data types or Hash derived typesprio
: 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 forpolicy
: to set for this queuecapacity
: is an optional capacity for the queue
-
virtual Connection::Pointer
-
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
-
virtual ChannelPointer
-
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 typedelayMs
: 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.
-
size_t
getNumberOfThreads
()¶ Return the number of threads currently available to the event loop for distributing work
- Return
Private Functions
-
void
clearThreadPool
()¶ Clears the thread pool and joins the threads
If joining fails repeatedly, throws karabo::util::TimeoutException.
-
void
-
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 commandsaction
: 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 4xxrequestId
: 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
Low-level callback called when writing into networks interface is done
-
void
postWriteDb
(const std::string &batch, const InfluxResponseHandler &action)¶ HTTP request “POST /write …” to InfluxDB server is registered in internal queue.
- Parameters
batch
: is a bunch of lines following InfluxDB “line protocol” separated by newline (‘ ‘) the “line protocol” is detailed at https://influxdbcom.readthedocs.io/en/latest/content/docs/v0.9/write_protocols/write_syntax/action
: callback is called when acknowledgment (response) comes from InfluxDB server. The callback signature is void(const HttpResponse&). The success error code in HttpResponse structure is 204.
-
void
postQueryDbTask
(const std::string &statement, const InfluxResponseHandler &action)¶ Actual “POST /query …” is accomplished. Non-blocking call. The connection to InfluxDB has to be established before this call
-
void
getPingDbTask
(const InfluxResponseHandler &action)¶ Actual “GET /ping …” is accomplished. Non-blocking call. The connection to InfluxDB has to be established before this call
-
void
postWriteDbTask
(const std::string &batch, const InfluxResponseHandler &action)¶ Actual “POST /write …” is accomplished. Non-blocking call, Connection should be established before this call
-
void
queryDbTask
(const std::string &statement, const InfluxResponseHandler &action)¶ Actual “GET /query …” is accomplished. If no connection to DB, this call is blocked until the connection is established. Otherwise the call is non-blocking.
-
void
onResponse
(const HttpResponse &o, const InfluxResponseHandler &action)¶ Generic wrap callback is called and call in turn the user “action”.
-
void
tryNextRequest
(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
-
void
-
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
:
-
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
-
size_t
-
class
Message
¶ - #include <Queues.hh>
This class represents a message in the distributed Karabo system.
Public Functions
-
const VectorCharPointer &
header
() const¶ Return the header of the message
- Return
-
const VectorCharPointer &
-
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 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
-
virtual size_t
-
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
-
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
:
-
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
-
size_t
-
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.
-
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 memorysize
: 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
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 informationdata
: Pre-allocated contiguous block of memorysize
: 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 informationdata
: A vector which will be updated accordingly
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 informationdata
: 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 informationdata
: 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 memorysize
: This number of bytes will be copied into datahandler
: 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 donehandler
: handler with signature ReadStringHandler, i.e. void (const boost::system::error_code&, std::string&) is called. second handler parameter is the read string including the terminator
-
void
readAsyncString
(const ReadStringHandler &handler)¶ Asynchronously reads data into a string. All memory management is done by the API. NOTE: A string in general is not storing data contiguously. Thus, an additional copy under the hood is needed which makes this interface slightly slower.
- Parameters
handler
: Call-function of signature: void (Channel::Pointer, const std::string&)
-
void
readAsyncVector
(const ReadVectorHandler &handler)¶ Asynchronously reads data into a vector<char>. All memory management is done by the API.
- Parameters
handler
: Call-function of signature: void (Channel::Pointer, const std::vector<char>&)
-
void
readAsyncHash
(const ReadHashHandler &handler)¶ Asynchronously reads data into a hash. All memory management is done by the API.
- Parameters
handler
: Call-function of signature: void (Channel::Pointer, const karabo::util::Hash&)
-
void
readAsyncHashPointer
(const ReadHashPointerHandler &handler)¶ Asynchronously reads data into a hash. All memory management is done by the API.
- Parameters
handler
: Call-function of signature: void (Channel::Pointer, const karabo::util::Hash&)
-
void
readAsyncVectorPointer
(const ReadVectorPointerHandler &handler)¶ Asynchronously reads data into a vector<char>. All memory management is done by the API.
- Parameters
handler
: Call-function of signature: void (Channel::Pointer, const std::vector<char>&)
-
void
readAsyncHashVector
(const ReadHashVectorHandler &handler)¶ Asynchronously reads data into a hash header and a vector<char>. All memory management is done by the API.
- Parameters
handler
: Call-function of signature: void (Channel::Pointer, const karabo::util::Hash&, const std::vector<char>&)
-
void
readAsyncHashString
(const ReadHashStringHandler &handler)¶ Asynchronously reads data into a hash header and a string. All memory management is done by the API. NOTE: A string in general is not storing data contiguously. Thus, an additional copy under the hood is needed which makes this interface slightly slower.
- Parameters
handler
: Call-function of signature: void (Channel::Pointer, const karabo::util::Hash&, const std::string&)
-
void
readAsyncHashHash
(const ReadHashHashHandler &handler)¶ Asynchronously reads data into a hash header and a hash body. All memory management is done by the API.
- Parameters
handler
: Call-function of signature: void (const ErrorCode&, const karabo::util::Hash&, const karabo::util::Hash&)
-
void
readAsyncHashPointerHashPointer
(const ReadHashPointerHashPointerHandler &handler)¶ Asynchronously reads data into a hash header and a hash body. All memory management is done by the API.
- Parameters
handler
: Call-function of signature: void (const ErrorCode&, const karabo::util::Hash&, const karabo::util::Hash&)
-
void
readAsyncHashVectorPointer
(const ReadHashVectorPointerHandler &handler)¶ Asynchronously reads data into a hash header and a vector<char>. All memory management is done by the API.
- Parameters
handler
: Call-function of signature: void (const ErrorCode&, const karabo::util::Hash&, const std::vector<char>&)
-
void
readAsyncHashVectorBufferSetPointer
(const ReadHashVectorBufferSetPointerHandler &handler)¶ Asynchronously reads data into a hash header and into a vector of BufferSet pointers. All memory management is done by the API.
- Parameters
handler
: Call-function of signature: void (const ErrorCode&, const karabo::util::Hash&, const std::vector<karabo::io::BufferSet::Pointer>&)
-
void
write
(const char *data, const size_t &size)¶ Synchronous write. The function blocks until all bytes are written.
- Parameters
data
: Pointer to a contiguous block of memory that should be writtensize
: 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 writtendata
: Pointer to a contiguous block of memory that should be writtensize
: 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 layoutbody
: 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 writtendata
: 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 writtensize
: This number of bytes will be writtenhandler
: 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 writtenhandler
: 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 typeshandler
: 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 writtendata
: Pointer to a contiguous block of memory that should be writtensize
: This number of bytes will be writtenhandler
: 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 writtendata
: vector of chars containing the data to be writtenhandler
: 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 writtenbody
: data as a vector of BufferSet::Pointerhandler
: 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 writtenbody
: data contained in a Hash with no particular structure, but serializable, i.e. containing no non-karabo data types or Hash derived typeshandler
: 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.
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.
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 forpolicy
: to set for this queuecapacity
: is an optional capacity for the queue
Public Static Functions
This function returns low level info about connection like … “localIp”, “localPort”, “remoteIp”, “remotePort” that constitute active connection. in form of Hash container
- Return
- Hash with 4 key/value pairs
- Parameters
ptr
: input TcpChannel boost shared pointer
Private Functions
-
void
bytesAvailableHandler
(const boost::system::error_code &e)¶ Internal default handler
- Parameters
channel
:
-
void
onSizeInBytesAvailable
(const ErrorCode &error, const ReadSizeInBytesHandler &handler)¶ This function calls the corresponding handler
- Parameters
handler
:error
:
-
void
onVectorBufferSetPointerAvailable
(const ErrorCode &error, size_t length, const std::vector<karabo::io::BufferSet::Pointer> &buffers, const ReadVectorBufferSetPointerHandler &handler)¶ Internal handler called after filling the buffer set
- Parameters
error
: error codelength
: number of bytes read == total size of buffer setbuffers
: vector of buffer set pointers with the datahandler
: 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.
-
Connection::Pointer
-
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
-
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
-
int
-
class
UserAuthClient
¶ Public Functions
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)>
-
using
-
typedef boost::system::error_code
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<unsigned long long>&, const std::vector<unsigned long long>&)>
ShowStatisticsHandler
¶
-
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 constructorallowMissing
: 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 dataidx
: 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 tokenssource
: 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 connectconfig
: 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
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)
-
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
: inputchannelIdx
: where to store the serialised datachunkIdx
: where to store the serialised datametaData
: of the datacopyAllData
: 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
:
-
class
MetaData
¶ Inherits from karabo::util::Hash
Public Functions
-
MetaData
(const std::string &source, const karabo::util::Timestamp ×tamp)¶ Constructor to directly set meta data entries
- Parameters
source
: an identifier of the data producertimestamp
: 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
-
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
andShowStatisticsHandler
. Currently only theaddress
key is included.
-
std::string
getInstanceIdName
() const¶ Concatenation of instance id and name
-
bool
hasRegisteredCopyInputChannel
(const std::string &instanceId) const¶ Check whether an InputChannel with given id is registered to receive all data
i.e. an InputChannel with “dataDistribution == copy”
- Return
- bool whether InputChannel of specified type is connected
- Parameters
instanceId
: of InputChannel
Check whether an InputChannel with given id is registered to receive a share of the data
i.e. an InputChannel with “dataDistribution == shared”
- Return
- bool whether InputChannel of specified type is connected
- Parameters
instanceId
: of InputChannel
-
void
write
(const karabo::util::Hash &data, const Memory::MetaData &metaData, bool = false)¶ Writes a Hash containing data to the output channel. Sending to the network happens when update() is called.
Note: Any NDArray/ImageData inside data must stay untouched at least until update() or the callback of asyncUpdate(cb) has been called. See also the documentation of the safeNDArray flag of the update()/asyncUpdate() methods.
- Parameters
data
: input Hash objectmetaData
: 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 objectmetaData
: 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 againwriteDoneHandler
: 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
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
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
Helper to indicate that given shared input is ready to receive more data
Requires m_registeredInputsMutex to be locked
Helper to provide id of shared input that is ready to receive more data
Requires m_registeredInputsMutex to be locked
Helper to tell whether none of the shared inputs is ready to receive more data
Requires m_registeredInputsMutex to be locked
Helper to query whether given shared input is ready to receive more data
Requires m_registeredInputsMutex to be locked
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 sendchannelInfo
: Container with info about channel to send todoneHandler
: 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 slotslotFunction
: 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 removedslotFunction
: 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
(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 systemconnection
: An existing broker connectionheartbeatInterval
: The interval (in s) in which a heartbeat is emittedinstanceInfo
: 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 systembrokerConfiguration
: 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 emittedinstanceInfo
: 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 systemconnection
: An existing broker connectionheartbeatInterval
: The interval (in s) in which a heartbeat is emittedinstanceInfo
: A hash containing any important additional informationconsumeBroadcasts
: 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 devicetimeout
: 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 devicetimeout
: 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 removeremove
: 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 signalslotInstanceId
: 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 signalslotInstanceId
: is the instance ID of the slot (if empty use this instance)slotSignature
: is the signature of the slotsuccessHandler
: 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 SignalSlotExceptiontimeout
: 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 signalslotInstanceId
: 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 signalslotInstanceId
: is the instance ID of the slot (if empty use this instance)slotSignature
: is the signature of the slotsuccessHandler
: 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 signalargs...
: 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 calledfunctionName
: 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 schemaconfig
: is a Hash with a Hash at ‘channelName’ which will be passed to InputChannel::createonDataAvailableHandler
: is a DataHandler called for each data item coming through the pipelineonInputAvailableHandler
: is an InputHandler called when new data arrives - user has to loop over all itemsonEndOfStreamEventHandler
: is an InputHandler called when EOS is receivedconnectTracker
: 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 channelconfig
: must have a Hash at key channelName - that is passed (after removeal of the “schema” key) to Configurator<OutputChannel>::createonOutputPossibleHandler
: ?
-
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 InputChannelhandler
: 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::AsyncErrorHandleroutputChannelsToIgnore
: 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.
-
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.
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 signalslotInstanceId
: instance id that carries the slotslotFunction
: the slot - if empty, all registered slots of slotInstanceId
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 RemoteExceptiondetails
: 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 extractedresult
: the string that will be assigned the value of the SignalInstanceId path
-
std::pair<karabo::util::Hash::Pointer, karabo::util::Hash::Pointer>
-
struct
SignalSlotConnection
¶ - #include <SignalSlotable.hh>
A structure to keep information of a signal-slot connection.
-
typedef boost::function<void()>
-
class
Slot
¶ Subclassed by karabo::xms::SlotN< Ret, Args >
-
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.
-
Derived &
- template <typename Ret, typename… Args>
-
class
SlotN
¶ Inherits from karabo::xms::Slot
-
typedef InputChannelElement
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 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
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 ×tampAsDouble)¶ 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 resultcolumnPrefixToRemove
: : remove this prefix from the column names. InfluxQL selector functions (e.g. SAMPLE) are prepended to the column name. Use this argument to remove said prefixes.
- Exceptions
karabo::util::NotSupportedException
: in case the column mismatch nlohmann::json exceptions in case of malformatted JSON objects.
-
boost::optional<std::string>
jsonValueAsString
(nl::json value)¶
-
std::string
toInfluxDurationUnit
(const TIME_UNITS &karaboDurationUnit)¶
-
std::string
epochAsMicrosecString
(const Epochstamp &ep)¶
-
boost::optional<std::string>
jsonValueAsString
(nlohmann::json value)¶ Utility function to convert a json object.
- Return
- a boost::optional<std::string> a null boost::optional<std::string> matches a null JSON value
- Parameters
value
:
-
std::ostream &
operator<<
(std::ostream &output, const Epochstamp &stamp)¶
-
bool
operator==
(const Epochstamp &lhs, const Epochstamp &rhs)¶ Relational operations between timestamps
- Return
- bool
- Parameters
other
: Epochstamp object
-
bool
operator!=
(const Epochstamp &lhs, const Epochstamp &rhs)¶
-
bool
operator>
(const Epochstamp &lhs, const Epochstamp &rhs)¶
-
bool
operator>=
(const Epochstamp &lhs, const Epochstamp &rhs)¶
-
bool
operator<
(const Epochstamp &lhs, const Epochstamp &rhs)¶
-
bool
operator<=
(const Epochstamp &lhs, const Epochstamp &rhs)¶
-
ostream &
operator<<
(ostream &os, const Exception &exception)¶ Automatic output using the << operator
-
static std::string
concat
(const std::vector<std::string> &vec, size_t len, const std::string &sep)¶
-
std::ostream &
operator<<
(std::ostream &os, const Hash &hash)¶ Serialize a hash to standard std::ostream object
- Parameters
visitor
:
-
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>
-
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
- 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 valueo
: 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 valueo
: 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::baro
: pointer to object to bind top
: 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 valuesargs
: 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
:
-
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)¶
-
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 tosrc
: typeinfo of source type, i.e. type of the value in the Hashtgt
: 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 splitdl
: 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 objectmaxBytesShown
: 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)¶
- 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 convertedmaxElementsShown
: 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 charfromString
<unsigned char>(const std::string &value)¶
- template <>
-
template<>
signed charfromString
<signed char>(const std::string &value)¶
- template <>
-
template<>
floatfromString
<float>(const std::string &value)¶
- template <>
-
template<>
doublefromString
<double>(const std::string &value)¶
- template <>
-
template<>
boolfromString
<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 emptydelimiters
: 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 emptydelimiter
:
-
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
:
-
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 <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
()¶
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
-
const std::string &
-
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
-
AlarmConditionElement &
- 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
-
ReturnType &
-
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:
- ChoiceElement::appendNodesOfConfigurationBase is used if another class of a type known to the factory system is to be added
- ChoiceElement::appendAsNode is used to append the entries of a NodeElement defined in the same expectedParameter function as the choice element
In either case, the user can select from the options during configuration
Inherits from karabo::util::GenericElement< ChoiceElement >
Public Functions
- template <class ConfigurationBase>
-
ChoiceElement &
appendNodesOfConfigurationBase
()¶ Append the expected parameters of another class of type ConfigurationBase. The class needs to be known by the factory system. It will be identified by its Karabo ClassId in the list of options.
- Return
- template <class T>
-
ChoiceElement &
appendAsNode
(const std::string &nodeName = "")¶ Append the entries found underneath a NodeElement identified by key. The node element needs to be defined prior to and in the same expected parameter function as the ChoiceElement.
- Return
- Parameters
nodeName
: identifying the node, i.e. the key of the node.
-
virtual ChoiceElement &
assignmentMandatory
()¶ The assignmentMandatory method serves for setting up a mode that requires the value of the element always being specified. No default value is possible.
- Return
- reference to the Element (to allow method’s chaining)
-
virtual DefaultValue<ChoiceElement, std::string> &
assignmentOptional
()¶ The assignmentOptional method is used to indicate that this element can optionally be configured. It is followed by either specifying that noDefaulValue() exists, or the defaultValue() is a classId or node key registered in the list of choices using either ChoiceElement::appendAsNode or ChoiceElement::appendNodesOfConfigurationBase.
- Return
-
virtual ChoiceElement &
init
()¶ The init method serves for setting up an access type property that allows the element to be included in initial schema.
- Return
- reference to the Element (to allow method’s chaining)
-
virtual ChoiceElement &
reconfigurable
()¶ The reconfigurable method serves for setting up an access type property that allows the element to be included in initial, reconfiguration and monitoring schemas.
- Return
- reference to the Element (to allow method’s chaining)
-
class
ClassInfo
¶ - #include <ClassInfo.hh>
ClassInfo holds meta-data to a factorized class.
Public Functions
-
const std::string &
getClassName
() const¶ Return the C++ class name of this class
- Return
-
const std::string &
getNamespace
() const¶ Return the C++ name space of this class
- Return
-
const std::string &
getClassId
() const¶ Return the Karabo ClassId of this class
- Return
-
const std::string &
getLogCategory
() const¶ Return the LogCategory for this class
- Return
-
const std::string &
getVersion
() const¶ Return the version number of this class - currently does not convey much meaning.
- Return
-
const std::string &
- 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 factoryrules
: 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 classIdvalidate
: 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
- 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 classIdarbitrary
: type parameter to be passed to the constructorvalidate
: 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
-
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 classclassId
: The factory key of the to be created object (must inherit the BaseClass template)input
: The input configuration of the parent classvalidate
: 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 classinput
: The input configuration of the parent classvalidate
: 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 requirementsvalidated
: 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:
Then you may generate a NODE_ELEMENT like this:class MyData : protected Hash { static void expectedParameters(const Schema& s) { // parameter definition [...] } };
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
:
-
Derived &
-
class
DateTimeString
¶ - #include <DateTimeString.hh>
This class expresses a valid date and time information in the form of a char string. To be a valid date and time char string, it must respect:
- ISO-8601:2000 Second Edition definition (docs available at http://www.qsl.net/g1smd/isopdf.htm)
- Subset (of ISO-8601) defined as Karabo date and time API
- Compact version: yyyymmddThhmmss[.|,]ffffffZ|z|±hhmm
- Extended version: yyyy-mm-ddThh:mm:ss[.|,]ffffffZ|z|±hh:mm
The default constructor initializes a DateTimeString object with the Epoch values (“19700101T000000Z”).
Public Functions
-
DateTimeString
()¶ Constructor without parameters, that creates a instance with epoch Timestamp (“19700101T000000Z”)
-
DateTimeString
(const std::string &timePoint)¶ Constructor from string
- Parameters
timePoint
: String that represents a complete and valid date format using Karabo agreed ISO-8601 subset API
-
DateTimeString
(const std::string &inputDate, const std::string &inputTime, const std::string &inputFractionSecond, const std::string &inputTimeZone)¶ Constructor from string
- Parameters
inputDateStr
: String that represents the date part of the Karabo agreed ISO-8601 subset APIinputTimeStr
: String that represents the time part of the Karabo agreed ISO-8601 subset APIinputFractionSecondStr
: String that represents the fractional part of the Karabo agreed ISO-8601 subset APIinputTimeZoneStr
: 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 precisionskipDot
: - 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
-
void
-
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.
-
std::size_t
-
class
DoocsException
¶ - #include <Exception.hh>
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
(const KeyType &key, const boost::any &value)¶ Construct a Hash element from a boost::any value
- Parameters
key
: identifies the elementvalue
: of the element
-
Element
(const KeyType &key, boost::any &&value)¶ Construct a Hash element from a boost::any value
- Parameters
key
: identifies the elementvalue
: 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 elementvalue
: 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 elementvalue
: of the element
- 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>
Set the value to a boost::shared_ptr of ValueType
- Parameters
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 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 attributevalue
: 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 attributevalue
: 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
- 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 sete
: element to set classId to
-
template<>
voidresetHashDerivedMoved
(ValueType &&value)¶ Helper to hack rvalue reference ‘value’ (which is Hash derived) back into a valid state
-
template<>
voidresetHashDerivedMoved
(ValueType &value)¶ No-op for lvalue reference
-
template<>
- template <typename isHashTheBase>
-
template<>
structSetClassIdAttribute
<Hash, isHashTheBase>¶ Hashes are not touched.
- template <typename ValueType>
-
template<>
structSetClassIdAttribute
<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<>
voidresetHashDerivedMoved
(const ValueType &value)¶ No-op
-
template<>
-
-
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 epochfraction
: 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 valuetv
: timeval structts
: timespec struct
-
Epochstamp
operator+
(const TimeDuration &duration) const¶ Move a timestamp forward/backward with given time distance, expressed in terms of time duration
- Return
- Epochstamp object
- Parameters
duration
: TimeDuration object
-
TimeDuration
operator-
(const Epochstamp &other) const¶ Time duration is the difference between two timestamps
- Return
- TimeDuration object
- Parameters
other
: Epochstamp object
-
Epochstamp
operator++
(int)¶ Auto increment/decrement operators
-
time_t
getTime
() const¶ Portability functions to convert Epochstamp to other system time structures
- Return
- time_t value
- Return
- timeval struct
- Return
- timespec struct
-
void
now
()¶ Retrieve current time for the system. Highest resolution is Nano-seconds
-
TimeDuration
elapsed
(const Epochstamp &other = Epochstamp()) const¶ Calculate elapsed time duration between two timestamps
- Return
- TimeDuration object
- Parameters
other
: Epochstamp object (by default, current time point)
-
std::string
toIso8601
(TIME_UNITS precision = MICROSEC, bool extended = false) const¶ Generates a sting (respecting ISO-8601) for object time for INTERNAL usage (“%Y%m%dT%H%M%S%f” => “20121225T132536.789333[123456789123]”)
- Return
- ISO 8601 formatted string (extended or compact)
- Parameters
precision
: - Indicates the precision of the fractional seconds (e.g. MILLISEC, MICROSEC, NANOSEC, PICOSEC, FEMTOSEC, ATTOSEC) [Default: MICROSEC]extended
: - “true” returns ISO8601 extended string; “false” returns ISO8601 compact string [Default: false]
-
std::string
toIso8601Ext
(TIME_UNITS precision = MICROSEC, bool extended = false) const¶ Generates a sting (respecting ISO-8601) for object time for EXTERNAL usage (“%Y%m%dT%H%M%S%f%z” => “20121225T132536.789333[123456789123]Z”)
- Return
- ISO 8601 formatted string with “Z” in the string end (“Z” means the date time zone is using Coordinated Universal Time - UTC)
- Parameters
precision
: - Indicates the precision of the fractional seconds (e.g. MILLISEC, MICROSEC, NANOSEC, PICOSEC, FEMTOSEC, ATTOSEC) [Default: MICROSEC]extended
: - “true” returns ISO8601 extended string; “false” returns ISO8601 compact string [Default: false]
-
const double
toTimestamp
() const¶ Generates a timestamp as double with seconds.fractional format (fractional precision == MICROSEC) Function necessary to use in graphs plotting in Python code (MICROSEC precision is enough)
- Return
- A double value with the decimal point indicating fractions of seconds
-
std::string
toFormattedString
(const std::string &format = std::string("%Y-%b-%d %H:%M:%S"), const std::string &localTimeZone = std::string("Z")) const¶ Formats to specified format time stored in the object
- Return
- formated string in the specified Time Zone
- Parameters
format
: The format of the time point (visit strftime for more info: http://www.cplusplus.com/reference/ctime/strftime/) [Default: “%Y-%b-%d %H:%M:%S”]localTimeZone
: - String that represents an ISO8601 time zone [Default: “Z” == UTC]
-
std::string
toFormattedStringLocale
(const std::string &localeName = std::string(""), const std::string &format = std::string("%Y-%b-%d %H:%M:%S"), const std::string &localTimeZone = std::string("Z")) const¶ Formats to specified format time stored in the object
- Return
- formated string in the specified Time Zone
- Parameters
localeName
: - String that represents the locale to be used [Default: “” == System locale]format
: The format of the time point (visit strftime for more info: http://www.cplusplus.com/reference/ctime/strftime/) [Default: “%Y-%b-%d %H:%M:%S”]localTimeZone
: - String that represents an ISO8601 time zone [Default: “Z” == UTC]
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 informationprecision
: - 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 timefacet
: Boost time_facet to be appliedlocaleName
: - String that represents the locale to be used
Friends
-
bool
operator==
(const Epochstamp &lhs, const Epochstamp &rhs)¶ Relational operations between timestamps
- Return
- bool
- Parameters
other
: Epochstamp object
-
-
class
Exception
¶ - #include <Exception.hh>
Karabo’s main exception class. Inherits from std::exception.
Inherits from std::exception
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 addedexceptionInfo
: 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>
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
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
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.
-
virtual Derived &
-
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
-
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 elementseparator
: 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 …
… is equivalent to …Hash hash(myKey);
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 keyvalue1
: Any object as (r- or l-)valuekey2
: Optionally another keyvalue2
: 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 &
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 keyvalue
: 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 stringtype
: 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 hashpolicy
: Whether to replace attributes by those merged in or to merge themselectedPaths
: If not empty, only merge these pathsseparator
: 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 subtractionseparator.
: 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 fromseparator
:
-
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.
-
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 withorderMatters
: 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
-
void
-
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>
Inherits from false_type
- template <class 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)
-
Derived &
-
class
ListElement
¶ - #include <ListElement.hh>
An element allowing choice-access to a list of factorized classes.
The ListElement can be configured to hold a number of factorized classes. Two methods exist for adding classes to the list of choices the ChoiceElement knows of:
- ListElement::appendNodesOfConfigurationBase is used if another class of a type known to the factory system is to be added
- ListElement::appendAsNode is used to append the entries of a NodeElement defined in the same expectedParameter function as the choice element
In either case, it will add a configuration entry to a Node List
Inherits from karabo::util::GenericElement< ListElement >
Public Functions
-
ListElement &
min
(const int minNumNodes)¶ Minimum number of nodes the list element should hold - inclusive
- Return
- Parameters
minNumNodes
:
-
ListElement &
max
(const int maxNumNodes)¶ Maximum number of nodes the list element should hold - inclusive
- Return
- Parameters
maxNumNodes
:
- template <class ConfigurationBase>
-
ListElement &
appendNodesOfConfigurationBase
()¶ Append the expected parameters of another class of type ConfigurationBase. The class needs to be known by the factory system. It will be identified by its Karabo ClassId in the list.
- Return
- template <class T>
-
ListElement &
appendAsNode
(const std::string &nodeName = "")¶ Append the entries found underneath a NodeElement identified by key. The node element needs to be defined prior to and in the same expected parameter function as the ListElement.
- Return
- Parameters
nodeName
: identifying the node, i.e. the key of the node.
-
virtual ListElement &
assignmentMandatory
()¶ The assignmentMandatory method serves for setting up a mode that requires the value of the element always being specified. No default value is possible.
- Return
- reference to the Element (to allow method’s chaining)
-
virtual DefaultValue<ListElement, std::vector<std::string>> &
assignmentOptional
()¶ The assignmentOptional method serves for setting up a mode that allows the value of element be optional, so it can be omitted in configuration. Default value is injected if defined. If you chain functions for definition of expected parameters the next function may be only defaultValue or noDefaultValue. When the default value is not specified (noDefaultValue) you must always check if the parameter has a value set in delivered User configuration.
- Return
- reference to DefaultValue object allowing proper defaultValue method chaining.
-
virtual ListElement &
init
()¶ The init method serves for setting up an access type property that allows the element to be included in initial schema.
- Return
- reference to the Element (to allow method’s chaining)
-
virtual ListElement &
reconfigurable
()¶ The reconfigurable method serves for setting up an access type property that allows the element to be included in initial, reconfiguration and monitoring schemas.
- Return
- reference to the Element (to allow method’s chaining)
-
class
LockException
¶ - #include <Exception.hh>
The LockException handles exceptions that result from not being able to acquire a lock
Inherits from karabo::util::Exception
-
class
LogicException
¶ - #include <Exception.hh>
The LogicException handles exceptions that are raised by any unexpected logical behaviour
Inherits from karabo::util::Exception
-
class
MemoryInitException
¶ - #include <Exception.hh>
The MemoryInitException handles exceptions raised during any memory initializations
Inherits from karabo::util::InitException
-
class
MessageException
¶ - #include <Exception.hh>
The MessageException handles exceptions that are caused during messaging
Inherits from karabo::util::Exception
-
struct
MetaData
¶ - #include <DataLogUtils.hh>
A structure defining meta data as used by the data loggers
-
struct
MetaSearchResult
¶ - #include <DataLogUtils.hh>
A structure defining meta data as used by the data logger’s search results
-
class
NDArray
¶ - #include <NDArray.hh>
A class representing multi-dimensional data in Karabo that seaminglessy converts to numpy.NDArray.
The NDArray class is intended to store any multidimensional data occurring in Karabo. Internally it holds the data in a ByteArray. It is a Hash-derived structure, which means it serializes into a karabo::util::Hash. Its meta-data is chosen such that it can be seamlessly converted into a numpy.NDArray
Inherits from karabo::util::Hash
Public Functions
-
NDArray
(const Dims &shape = Dims(), const karabo::util::Types::ReferenceType &type = karabo::util::Types::DOUBLE, const bool isBigEndian = karabo::util::isBigEndian())¶ This constructor creates an empty NDArray
- Parameters
shape
:type
:isBigEndian
:
- template <typename T>
-
NDArray
(const Dims &shape, const T &fill, const bool isBigEndian = karabo::util::isBigEndian())¶ This constructor creates an NDArray where all values are initialized with a fill value
- Parameters
shape
:fill
:isBigEndian
:
- template <typename T>
-
NDArray
(const T *dataPtr, const size_t numElems, const Dims &shape = Dims(), const bool isBigEndian = karabo::util::isBigEndian())¶ This constructor copies data from the provided memory location. Internally the data is kept as shared pointer.
- Parameters
dataPtr
: Typed address to a stretch of contiguous memorynumElems
: Number of elements (of type T)shape
: Shape informationisBigEndian
: 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 rangelast
: End of range (i.e. points one behind as vector.end())shape
: Shape informationisBigEndian
: 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 memorynumElems
: Number of elements (of type T)deleter
: A functor defining the deletion behaviorshape
: Shape informationisBigEndian
: 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 locationtype
: Type of provided datanumElems
: Number of elements of provided typeshape
: Shape informationisBigEndian
: Endianess flag
-
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
-
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
:
-
iterator
-
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
:
-
std::vector<bool>
-
OverwriteElement &
-
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
-
PathElement &
-
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>
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
:
-
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)
-
ReadOnlySpecific &
-
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
:
-
AlarmSpecific<Element, ValueType, Self> &
-
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
¶
-
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 ¶meterDescription)¶ Set the parameter hash of the schema. Implicitly alters the schema as this Hash is its underlying description.
-
void
setParameterHash
(karabo::util::Hash &¶meterDescription)¶ Set (with move semantics) the parameter hash of the schema. Implicitly alters the schema as this Hash is its underlying description.
-
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
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 sepsep
:
-
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
-
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 fromfilterTags
: 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 locateddataType
: 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 elementactions
: 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
:
Private Functions
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
-
enum
-
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)
-
SimpleElement &
-
class
StackTrace
¶ - #include <StackTrace.hh>
StackTrace prints out the exception stack, symbols are, in the best case, C++ demangled.
-
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
:
-
virtual const std::string &
-
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
-
StateElement &
-
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 orderstaticMoreSignificant
: identify if in the State::STATIC regime State::PASSIVE or State::ACTIVE is more significantchangingMoreSignificant
: 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 morechangingMoreSignificant
: identify if in the State::CHANGING regime State::INCREASING or State::DECREASING is more significant
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 stateall
: 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.
-
class
TableElement
¶ - #include <TableElement.hh>
The TableElement represents a vector<Hash> with fixed entries and types.
The TableElement represents a vector<Hash> with fixed entries and types. This means that each entry in the vector is expected to be a Hash with the same keys and same types, except for those which are set to assignment optional and have a default value.
Tables are defined by assigning a rowSchema to them, hence specifying how the Hash entries in the vector should look like. The Schema::Validator is aware of these specifications and will perform validation on these elements.
Inherits from karabo::util::GenericElement< TableElement >
Public Functions
-
TableElement &
allowedStates
(const std::vector<karabo::util::State> &value)¶ The allowedStates method serves for setting up allowed states for the element
- Return
- reference to the Element (to allow method’s chaining)
- Parameters
states
: A string describing list of possible states.sep
: A separator symbol used for parsing previous argument for list of states
-
virtual TableElement &
assignmentMandatory
()¶ The assignmentMandatory method serves for setting up a mode that requires the value of the element always being specified. No default value is possible.
- Return
- reference to the Element (to allow method’s chaining)
-
virtual TableDefaultValue<TableElement> &
assignmentOptional
()¶ The assignmentOptional method serves for setting up a mode that allows the value of element be optional, so it can be omitted in configuration. Default value is injected if defined. If you chain functions for definition of expected parameters the next function may be only defaultValue or noDefaultValue. When the default value is not specified (noDefaultValue) you must always check if the parameter has a value set in delivered User configuration. Example:
SOME_ELEMENT(expected) ... .assignmentOptional().defaultValue("client") ... .commit();
- Return
- reference to DefaultValue object allowing proper defaultValue method chaining.
-
virtual TableDefaultValue<TableElement> &
assignmentInternal
()¶ The assignmentInternal method serves for setting up the element to be internal. In the code it behaves like optional parameter but it is not exposed to the user. It is omitted when the schema is serialized to XSD. The value of this parameter should be defined programmatically. Conceptually, internal parameter with internal flag can be treated as an argument to the constructor.
- Return
- reference to DefaultValue (to allow method’s chaining)
-
virtual TableElement &
init
()¶ The init method serves for setting up an access type property that allows the element to be included in initial schema.
- Return
- reference to the Element (to allow method’s chaining)
-
virtual TableElement &
reconfigurable
()¶ The reconfigurable method serves for setting up an access type property that allows the element to be included in initial, reconfiguration and monitoring schemas.
- Return
- reference to the Element (to allow method’s chaining)
-
KARABO_DEPRECATED TableElement& karabo::util::TableElement::setNodeSchema(const Schema & schema)
This method is deprecated. Use setColumns instead.
- Return
- reference to the Element (chaining)
- Parameters
schema
:
-
TableElement &
setColumns
(const Schema &schema)¶ This method establishes content of the table, i.e. table columns and their types
- Return
- reference to the Element (chaining)
- Parameters
schema
:
-
TableElement &
addColumns
(const Schema &schema)¶ This method appends additional columns to the right side of the table.
- Return
- reference to the Element (chaining)
- Parameters
schema
:
- template <class T>
-
TableElement &
addColumnsFromClass
()¶ This method appends additional columns to the table taken from some class. The class is template parameter.
- Return
- reference to the Element (chaining)
Private Functions
-
void
sanitizeRowSchema
(karabo::util::Schema &rowSchema)¶ Controlling method for row schema sanitization.
- Exceptions
karabo::util::ParameterException
: can be throw by some specific sanitization methods.
-
void
sanitizeColumnsAccessModes
(karabo::util::Schema &rowSchema)¶ Turns reconfigurable and init columns into read-only columns when the hosting table is read-only. When the hosting table is init or reconfigurable, turns every init column into a reconfigurable column.
-
void
sanitizeNoDefaultColumns
(karabo::util::Schema &rowSchema)¶ Makes sure that every non read-only column in a non read-only table has a default value set.
Default values are synthesized for the columns that don’t have a default value. The synthesized values correspond to the default initializer of the column type (e.g. 0 for int columns, false for bool columns and empty vectors for vector<..> columns).
- Exceptions
karabo::util::ParameterException
: if the synthesized column default values are incompatible with any attribute that already existed in the schema, like ‘minInc’ or ‘minSize’ or if the type of the column lacking a default value is not supported for table columns.
-
std::pair<std::string, Types::ReferenceType>
findUnsupportedColumnType
(const karabo::util::Schema &rowSchema)¶ Finds, in the TableElement rowSchema, a column of an unsupported type - the TableElement supports a subset of the Leaf types for valid column types.
- Return
- std::pair<std::string, karabo::util::Types::ReferenceType> ‘first’ is the name of the column of the invalid type (empty string if all columns are of supported types) and ‘second’ is the type of the column with the invalid type (UNKNOWN if there is no column of an invalid type).
-
TableElement &
-
class
TimeDuration
¶ - #include <TimeDuration.hh>
This class represents the time duration (length) between two time points The value is hold in form of two unsigned 64bit values. The first expresses the total number of seconds, and the seconds the fractional of a second.
The default constructor create a time duration of length zero, i.e. empty.
Public Functions
-
TimeDuration
()¶ Default constructor creates an empty time duration
-
TimeDuration
(const karabo::util::Hash &hash)¶ Constructs a time duration from Hash. Seconds and fractions are stored as unsigned integer 64bits under the keys “seconds” and “fractions”, respectively.
- Parameters
hash
: Hash object (“seconds”, unsigned int 64bits, “fractions”, unsigned int 64bits)
-
TimeDuration
(const TimeValue seconds, const TimeValue fractions)¶ Construct a time duration from separate seconds and fractions of seconds.
- Parameters
seconds
:fractions
: in Atto seconds
-
TimeDuration
(const int days, const int hours, const int minutes, const TimeValue seconds, const TimeValue fractions)¶ Construct a time duration that expand over days, hours, …
- Parameters
days
:hours
:minutes
:seconds
:fractions
:
-
TimeDuration &
set
(const TimeValue seconds, const TimeValue fractions)¶ Set new length of, expand, or shrink a time duration
- Parameters
days
:hours
:minutes
:seconds
:fractions
:
-
bool
operator==
(const TimeDuration &other) const¶ Relational operations between time duration objects
- Return
- bool
- Parameters
other
: TimeDuration
-
TimeDuration
operator+
(const TimeDuration &other) const¶ Arithmetic operations over time durations
- Return
- TimeDuration
- Parameters
other
: TimeDuration
-
TimeDuration
operator*
(TimeValue factor) const¶ Create a multiple of the TimeDuration by multiplication with an unsigned, i.e. non-negative number.
- Return
- the new TimeDuration
- Parameters
factor
: that the time duration should be multiplied with
-
TimeDuration &
operator*=
(TimeValue factor)¶ Multiply by an unsigned, i.e. non-negative number.
- Return
- reference to *this after multiplication
- Parameters
factor
: that the time duration should be multiplied with
-
TimeDuration
operator*
(long long illegalSignedFactor) const¶ These multiplications with a signed value create a linker error: TimeDuration cannot be negative.
-
long double
operator/
(const TimeDuration &other) const¶ Division, i.e. how many times one time duration is bigger/smaller than another one
- Return
- long double
- Parameters
other
: TimeDuration
-
bool
isNull
() const¶ Check if the time duration is empty, i.e. of zero length.
- Return
- bool
-
uint64_t
getDays
() const¶ In the standard mixed format DD::HH::MM::SS::FF, How many days, hours, minutes, and seconds are in the time duration.
- Return
- unsigned int 64bits
-
TimeValue
getTotalHours
() const¶ Express the total length of a time duration in hours, minutes, or seconds.
- Return
- unsigned int 64bits
-
TimeValue
getFractions
(const TIME_UNITS unit = NANOSEC) const¶ Number of fractions of a second, default resolution is Nano seconds
- Return
- unsigned int 64bits
-
std::string
format
(const std::string &fmt) const¶ Serialize time duration to string/std::ostream
- Return
- string/ostream object holding the string representation of the time period
- Parameters
format
:
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
-
-
class
TimeoutException
¶ - #include <Exception.hh>
The TimeoutException handles exceptions that are caused by time out events
Inherits from karabo::util::Exception
-
class
TimePeriod
¶ - #include <TimePeriod.hh>
This class models a time period expressed by two time points, i.e. start and stop.
The default constructor create a time period of length zero, i.e. start=stop.
Public Functions
-
TimePeriod
()¶ Default constructor creates and empty time period
-
TimePeriod
(const karabo::util::Hash &hash)¶ Constructs a time period from Hash. Start and stop timestamps are stored under the two reserved keys “KRB_start” and “KRB_stop”, respectively.
- Parameters
hash
: Hash object (“KRB_start”, any, “KRB_stop”, any)
-
TimePeriod
(const Epochstamp &start, const Epochstamp &stop)¶ Constructs a time period from two given timestamps
- Parameters
start
: Epochstamp objectstop
: Epochstamp object
-
TimeDuration
getDuration
() const¶ Return the time duration (i.e. length) of a time period.
- Return
- TimeDuration object
-
Epochstamp
getStart
() const¶ Get the start (resp. stop) timestamp
- Return
- Epochstamp object
-
void
start
(const Epochstamp &tm = Epochstamp())¶ Set the start (resp. stop) timestamp. By default, it set it to the current system epoch timestamp.
- Parameters
tm
: Epochstamp (by default, use the current system timestamp)
-
bool
isOpen
() const¶ Check if period is still open (i.e. not yet stopped)
- Return
- bool
-
bool
before
(const Epochstamp &tm) const¶ Check if time point (timestamp) is before, within, or after a time period.
- Return
- bool
- Parameters
tm
: Epochstamp object
-
-
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
-
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 formatlevel
: 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 objectformat
: time formatlevel
: deepest level
-
-
class
Timestamp
¶ - #include <Timestamp.hh>
This class expresses a time point and holds it in form of an Epochstamp and Trainstamp
Public Functions
-
Epochstamp
getEpochstamp
() const¶ Return Epochstamp part of the timestamp
- Return
-
Trainstamp
getTrainstamp
() const¶ Return Trainstamp part of the timestamp
- Return
-
const unsigned long long &
getSeconds
() const¶ Return the seconds entry of the timestamp
- Return
-
const unsigned long long &
getFractionalSeconds
() const¶ Return the fractional seconds entry of the timestamp
- Return
-
const unsigned long long &
getTrainId
() const¶ Return the train id entry of the timestamp
- Return
-
std::string
toIso8601
(TIME_UNITS precision = MICROSEC, bool extended = false) const¶ Generates a sting (respecting ISO-8601) for object time for INTERNAL usage (“%Y%m%dT%H%M%S%f” => “20121225T132536.789333[123456789123]”)
- Return
- ISO 8601 formatted string (extended or compact)
- Parameters
precision
: - Indicates the precision of the fractional seconds (e.g. MILLISEC, MICROSEC, NANOSEC, PICOSEC, FEMTOSEC, ATTOSEC) [Default: MICROSEC]extended
: - “true” returns ISO8601 extended string; “false” returns ISO8601 compact string [Default: false]
-
std::string
toIso8601Ext
(TIME_UNITS precision = MICROSEC, bool extended = false) const¶ Generates a sting (respecting ISO-8601) for object time for EXTERNAL usage (“%Y%m%dT%H%M%S%f%z” => “20121225T132536.789333[123456789123]Z”)
- Return
- ISO 8601 formatted string with “Z” in the string end (“Z” means the date time zone is using Coordinated Universal Time - UTC)
- Parameters
precision
: - Indicates the precision of the fractional seconds (e.g. MILLISEC, MICROSEC, NANOSEC, PICOSEC, FEMTOSEC, ATTOSEC) [Default: MICROSEC]extended
: - “true” returns ISO8601 extended string; “false” returns ISO8601 compact string [Default: false]
-
std::string
toFormattedString
(const std::string &format = std::string("%Y-%b-%d %H:%M:%S"), const std::string &localTimeZone = std::string("Z")) const¶ Formats to specified format time stored in the object
- Return
- formated string in the specified Time Zone
- Parameters
format
: The format of the time point (visit strftime for more info: http://www.cplusplus.com/reference/ctime/strftime/) [Default: “%Y-%b-%d %H:%M:%S”]localTimeZone
: - String that represents an ISO8601 time zone [Default: “Z” == UTC]
-
std::string
toFormattedStringLocale
(const std::string &localeName = std::string(""), const std::string &format = std::string("%Y-%b-%d %H:%M:%S"), const std::string &localTimeZone = std::string("Z")) const¶ Formats to specified format time stored in the object
- Return
- formated string in the specified Time Zone
- Parameters
localeName
: - String that represents the locale to be used [Default: “” == System locale]format
: The format of the time point (visit strftime for more info: http://www.cplusplus.com/reference/ctime/strftime/) [Default: “%Y-%b-%d %H:%M:%S”]localTimeZone
: - String that represents an ISO8601 time zone [Default: “Z” == UTC]
-
double
toTimestamp
() const¶ Generates a timestamp as double with seconds.fractional format (fractional precision == MICROSEC) Function necessary to use in graphs plotting in Python code (MICROSEC precision is enough)
- Return
- A double value with the decimal point indicating fractions of seconds
Public Static Functions
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
:
-
Epochstamp
-
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
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 ×tamp = 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 validateunvalidatedInput
: which should be validatedvalidatedOutput
: validated and altered according to current ValidationRulestimestamp
:
- 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)
-
VectorElement &
-
class
Version
¶ - #include <Version.hh>
A class providing versioning information for the Karabo framework.
Public Functions
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
-
const Version &
- 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
-
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’
-
using
-
namespace
detail
¶
-
namespace
MetricPrefix
¶
-
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
¶
-
-
enum
-
typedef AlarmConditionElement