Threshold Actor
The ThresholdActor stores a list of thresholds against which a stream of data can be tested to trigger events. A set of messages can be attached to each threshold, to be sent when the data stream crosses the threshold.
The messages are stored in MessageGroups with each threshold, so the messages may use the MessageGroup indexing scheme (with the '*' symbol). When a datum from the stream is sent to the threshold actor, it may be sent with a data array that will be passed on to the MessageGroups associated with threshold crossings.
To use the ThresholdActor, load msgGroup.so and then load thresh.so and create an actor of type ThresholdActor. You do not need to create any MessageGroups, as the ThresholdActor manages its own groups. You must load the MessageGroup dso, however, or the ThresholdActor dso will not load.
ThresholdActor messages
In addition to the messages understood by all actors, the ThresholdActor understands the following messages:
- AddThreshold hActor x message
- Create a new threshold at x, or add message to the MessageGroup associated with an existing threshold at x. message will be sent whenever the data stream crosses with threshold in either direction (i.e. changes from greater than to less than or from less than to greater than).
- AddThresholdGT hActor x message
- AddThresholdLT hActor x message
- AddThresholdGTEQ hActor x message
- AddThresholdLTEQ hActor x message
- AddThresholdEQ hActor x message
- Create a new threshold at x, or add message to the MessageGroup associated with an existing threshold at x. message will be sent whenever the data stream crosses with threshold in a direction specified by the last two or four characters of the message name (AddThreshXX or AddThreshXXXX). The tests associated with each message are greater than, less than, greater than or equal to, less than or equal to, and equal to, respectively. Whenever a datum is received for which a threshold's test returns true, and for which the previously sent datum (or initial value) tested false, the associated messages will be sent.
- SetInitialVal hActor x
- Set the initial value of the data stream to x. This does not trigger any messages. Since threshold crossings (i.e. changes of state) are detected, the ThresholdActor must have some initial state against which to compare the state established by the first stream datum in order to determine whether there has been a crossing. If no initial state is specified, 0.0 is assumed. The state may be initialized at any time.
- TestThresholds hActor x c
- Test x against all thresholds. For any thresholds that are crossed, send the data array [z1 z2 z3 ...] to the corresponding MessageGroup. If no data array is specified, then the MessageGroups receive an empty (NULL) array.
- SetNoRedundancies hActor f
- Set no-redundancy mode to true or false, as flag f
is true or false. In this mode, the actor will send at most one
message, even if several thresholds are crossed at once (since
the previous TestThresholds message).
In particular, of the messages which would have been sent,
the only one which is sent will be the
"last" one, in the sense of whether the value is rising or falling.
- LimitRate hActor t
- Wait at least t seconds between sending messages.
If a message is sent and a second one "should" be sent before
t seconds have elapsed, the second one will wait until
the time has elapsed and then it will be sent, a little "late".
If a third message "should" be sent before
t seconds have elapsed, the second one will be discarded
and only the third one will be sent when the proper time arrives.
Side effect: this forces the actor into no-redundancy mode.
- AddPrefixMessage hActor message
- Send message immediately before sending any other message or group of messages.
- AddSuffixMessage hActor message
- Send message immediately after sending any other message or group of messages.