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