InstanceChangeThrottler

class InstanceChangeThrottler : public std::enable_shared_from_this<InstanceChangeThrottler>

@brief 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.

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

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.

Variables

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

Functions

Name	Description
createThrottler	InstanceChangeThrottler factory.
submitInstanceNew	Submits an instance new change for dispatching by the throttler.
submitInstanceUpdate	Submits an instance update change for dispatching by the throttler.
submitInstanceGone	Submits an instance gone change for dispatching by the throttler.
cycleIntervalMs	The interval, in milliseconds, between cycles of the throttler.
maxChangesPerCycle	The maximum number of instance changes entries to be dispatched per throttler cycle.
getInstChangeTypeStr	Returns the string representation of a given InstChangeType value.
flush	Flushes the throttler by making it dispatch the instance changes it has stored asap.
instNewUpdateEncoder	Encodes the instanceInfo hash into the format that the Throttler uses internally for changes of type NEW and UPDATE.
instGoneEncoder	Encodes the instanceInfo hash into the format that the Throttler uses internally for changes of type GONE.
addChange	Adds an instance change to m_instChanges.
runThrottlerCycleAsync	Throttler cycle execution.
kickNextThrottlerCycleAsync	Schedules the next throttler event dispatching cycle.
flushThrottler	Flushes the throttler by running its dispatching loop immediately.

Variable Details

m_instChanges

karabo::data::Hash m_instChanges

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

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

Function Details

addChange

void addChange(InstChangeType changeType, const std::string& instanceId, const karabo::data::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.

changeType :

instanceId :

instanceInfo :

createThrottler

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

InstanceChangeThrottler factory.

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.

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.

cycleIntervalMs

unsigned int cycleIntervalMs() const

The interval, in milliseconds, between cycles of the throttler.

flush

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.

flushThrottler

void flushThrottler(bool kickNextCycle = true)

Flushes the throttler by running its dispatching loop immediately.

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

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

getInstChangeTypeStr

std::string getInstChangeTypeStr(InstChangeType changeType) const

Returns the string representation of a given InstChangeType value.

instGoneEncoder

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

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

instanceId : the id of the instance the change is about.

instanceInfo : the instanceInfo hash as used by the karabo GUI.

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

instNewUpdateEncoder

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

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

instanceId : the id of the instance the change is about.

instanceInfo : the instanceInfo hash as used by the karabo GUI.

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.

kickNextThrottlerCycleAsync

void kickNextThrottlerCycleAsync()

Schedules the next throttler event dispatching cycle.

maxChangesPerCycle

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.

runThrottlerCycleAsync

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

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

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

submitInstanceGone

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

Submits an instance gone change for dispatching by the throttler.

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

instanceInfo : Information about the instance the gone change refers to.

submitInstanceNew

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

Submits an instance new change for dispatching by the throttler.

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

instanceInfo : Information about the instance the new change refers to.

submitInstanceUpdate

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

Submits an instance update change for dispatching by the throttler.

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

instanceInfo : Information about the instance the update change refers to.