NAME
Schedule::Activity::Attribute - Updating, tracking, and reporting numeric values.
SYNOPSIS
my $attr=Schedule::Activity::Attribute->new(type=>'int',value=>0,tm=>0);
$attr->change(tm=>10,set=>10);
$attr->change(tm=>20,set=>20);
print $attr->value();
print $attr->average();DESCRIPTION
This module is responsible for individual attributes. It tracks values for the attribute, facilitates changes, and handles reporting.
Attributes are intended to be typed, so cross-type requests may produce failures.
CONFIGURATION
Declaration
Named attributes in scheduling configurations may provide the following:
type =>'bool' or 'int'
value=>numeric
note =>'any comment'Attributes are integers initialized to zero by default. An initialization may include a note for convenience, but this value is not stored nor reported.
Changes
Attribute changes within scheduling configurations may include the following:
set =>value
incr=>value (only for int)
decr=>value (only for int)
note=>'any comment'A change may include a note for convenience, but this value is not stored nor reported.
TYPES
The two types of attributes are bool or int, which is the default. A boolean attribute is primarily used as a state flag. An integer attribute can be used both as a counter or gauge, either to track the number of occurrences of an activity or event, or to log varying numeric values.
Integer attributes
The int type is the default. The default initial value is zero.
Integer attributes may change with any of: set, incr, decr. There is no actual restriction on numeric type so any Perl number is valid, integers or real numbers, positive or negative.
The reported avg is the overall time-weighted average of the values, computed via a trapezoid rule. That is, if tm=0, value=2 and tm=10, value=12, the average is 7 with a weight of 10. See "Logging" for more details.
Boolean attributes
The bool type must be declared. The default initial value is zero/false.
Boolean attributes may change with any of: set. Currently there is no restriction on values, but the behavior is only defined for values 0/1.
The reported avg is the percentage of time in the schedule for which the flag was true. That is, if tm=0, value=0, and tm=7, value=1, and tm=10, value=1 is the complete schedule, then the reported average for the boolean will be 0.3.
RESPONSE
Each named attribute in a scheduling configuration uses the report function, described below, to build an attribute report that includes:
y =>(final value)
xy =>[[tm,value,average],...]
avg=>(average, depends on type)The y value is the last recorded value. The xy contains an array of all values, averages, and the times at which they changed. The avg is roughly the time-weighted average of the value, but this depends on the attribute type.
Logging
The reported xy is an array of values of the form (tm, value, average), with each timestamped entry indicating that a scheduling activity, action, or message, included an attribute change configuration. Each attribute has an initial entry of (0, value), either the default or the value specified in the declaration. Note that the starting time may be a value other than zero.
Any attribute may be "fixed" in the log at its current value by passing the change as {}, which is equivalent to incr=0 for integers. (Internally this may also be invoked with _log=1, but this is subject to change.)
FUNCTIONS
The Attribute object provides the following functions.
change
Ideally called as $attr-change(tm=>tm,options)>, this updates the value of the attribute and logs at the given timestamp. Change options must be type-appropriate. The specified time must exceed (or be the same as) the maximum logged time for the attribute to have any effect. That is, historical requests are a no-op: They don't update the current value, nor do they create an entry in the log.
Called without a timestamp, the maximum time will be assumed, the value changed, and the logged entry overwritten.
Historic entry is proposed by not yet defined, since it must support set and incr options and handle updates to the rolling average.
value
The value of the attribute associated with the logged event having the maximum time.
average
Computes the type-specific time-weighted "average value" over all entries in the log. Averages are maintained for integers and booleans on the fly, so they can be referenced at any time without performance impact.
report
Returns a hash of
y the value
xy this list of logged (time,value)
avg the time-weighted average_xy
An internal helper to build the list of values from the log.
validateConfig
Returns errors if any of the keys in an attribute configuration are unavailable for the type. By default, the type is 'int'.
log
Called with a timestamp as $attr-log(tm)> to create a log entry of the current value. This is public so callers can establish a "checkpoint" where the value is known/unchanged, typically at boundaries of events or scheduling windows.
Does nothing if the indicated time is below the maximum logged time. Historic entry is proposed by not defined (see 'change' above).
dump
Return a hash of values that can be used to restore the state of the attribute.
restore
Called either as a static function or $attr-restore(%copy)>, loads the state of the attribute from the given hash.