The docs say:
The thresholdCount and thresholdWindow attributes specify a
threshold, where xxx is the number of errors permitted in a window of size
yyy.
If the threshold is exceeded, the framework take the specified
action of either disabling this delegate, or terminating the containing AS
Aggregate
(or if not an AS Aggregate, terminated the AS Primitive).
The implementation uses a thresholdCount of 0 to mean "no threshold" (i.e.
ignore all errors) hence 1 must mean "act on the first error", so the action
is taken when the threshold is reached, not exceeded.
So we must change the implementation or the documentation.
Implementation: We could use a value of "-1" or "no threshold" for the
ignore-all-errors case, and "0" for no-errors-tolerated so
act-on-first-error. But this runs counter to our other uses of 0 to mean
"no-....", e.g. the CDE replaces a timeout of 0 by "no timeout" and a
thresholdWindow of 0 by "no window", and a maxRetries of 0 by "no retries".
Changing all of these to use -1 for the "no" case would leave confusion over
what 0 means, or why we have 2 ways of representing "no".
Documentation: The word "threshold" is often used to mean "max", and the
action is taken only when crossing it, but it can also be used as a minimum
value marking the level at which something happens, e.g. sensory threshold,
election threshold, lasing threshold. So we could change the documentation
to describe it as the minimum number of errors that trigger the action. (In
practice the error count will exceed the threshold when multiple CASes
enqueued at a dead service all time-out, but the action for all but the
first is ignored)
Possible wording:
The thresholdCount and thresholdWindow attributes specify the
threshold at which the thresholdAction is taken.
If xxx errors occur within a window of size yyy, the framework takes
the specified
action of either disabling this delegate, or terminating the
containing AS Aggregate
(or if not an AS Aggregate, terminating the AS Primitive).
A thresholdCount of 0 has the special meaning of no-threshold (errors
ignored),
and a thresholdWindow of 0 means no-window (all errors are counted.)
We should probably also state that it is an error to specify the impossible
case of a non-zero window smaller than the threshold (reject in dd2spring?)
And perhaps point out that if the window is equal to the threshold then the
errors must be consecutive, and that the window is irrelevant if the
threshold is 1.
