NAME

CHI::Cascade::Value - a class for valid values

SYNOPSIS

You can use it class for a returning of values by exceptions. For example:

    die CHI::Cascade::Value->new

This throws an exception with nothing value. If you do it from your recompute code your "run" in CHI::Cascade method will return an old value from cache or if it's not in cache it will return an undef value.

Or

    die CHI::Cascade::Value->new->value( $any_value );
    die CHI::Cascade::Value->new->value( undef );

This throws an exception with valid value. Please note that undef is valid value too! But bacause the "run" in CHI::Cascade method returns only a value (not instance of CHI::Cascade::Value object) there is not recommended to use undef values (run method returns undef when it cannot get a value right now).

Please use it class only in special cases - when you need to break recopmuting, want to return an specific value only for once execution of "run" in CHI::Cascade method and don't want to save value in cache.

CONSTRUCTOR

    $value = CHI::Cascade::Value->new;

It will create instance $value with nothing value

METHODS

value

Examples:

    $value->value
    $value->value( $new_value )

You can use it to get/set a value of $value. An undef value is valid too! First version returns a value, second sets a value and returns $value.

is_value

    $value->is_value

returns true if value was set by "value" method or false else.

state

    use CHI::Cascade::Value ':state';
    $state_bits = $value->state;
    $value = $value->state( CASCADE_* );

A getting or setting of state bits of value object.

state_as_str

    my $value = $cascade->run( 'my_target', state => \$state );
    my $str = CHI::Cascade::Value->state_as_str( $state );

Returns a string presentation of state bits (see below "STATE BITS"). Strings of bits are ordered by alphabetical before concatenation. Here some examples:

    # It means you get actual value and this was recomputed right now
    CASCADE_ACTUAL_VALUE | CASCADE_RECOMPUTED

    # It happens when returned value of CHI::Cascade::run is undef and here is reason why:
    # value right now is being computed in other process and no old value in cache
    CASCADE_COMPUTING | CASCADE_NO_CACHE

This method is useful for debugging or logging processes.

STATE BITS

Since version 0.26 the CHI::Cascade introduces the concept of state bits. An every value object (even which has not valid value) has a history is described by these state bits. To use this bit mask we can know how this value was gotten. These bits are returned by "run" in CHI::Cascade in "state" in CHI::Cascade variable.

CASCADE_NO_CACHE

A value of target was missed in cache. Only as information as value was fetched

CASCADE_COMPUTING

A value of target to be computing in other process. So "run" in CHI::Cascade will return to you a undef (if it misses in cache) or old value from cache.

CASCADE_DEFERRED

A value of target should be recomputed but was not recomputed because "run" in CHI::Cascade was executed with "defer" in CHI::Cascade option as true. This useful when you want to control an excution of codes of targets yourself.

CASCADE_FROM_CACHE

A value of target is old or actual value and was fetched from cache.

CASCADE_ACTUAL_VALUE

A value of target is actual value (should not be recomputed)

CASCADE_RECOMPUTED

A value of target was recomputed by your request right now (was called "code" in CHI::Cascade in your process)

CASCADE_CODE_EXCEPTION

This state bit occurs only if exception was thrown from code or any dependencies and it has the type CHI::Cascade::Value (the expression $@->isa('CHI::Cascade::Value') is true). If there to be thrown an other type expression it will be rethrown from "run" in CHI::Cascade. A value of target returned by "run" in CHI::Cascade can be:

undef

A cache doesn't have any value of target

old value from cache

If "code" in CHI::Cascade if a code or any code of dependencies threw exception as CHI::Cascade::Value object without value and a cache has any value for target (i.e. die CHI::Cascade::Value->new)

value was thrown by exception

If value was thrown by die CHI::Cascade::Value->new->value(123) and even same: die CHI::Cascade::Value->new->value(undef)) for example.

CASCADE_ACTUAL_TERM

The method "run" in CHI::Cascade was run with actual_term option and actual term is actual for this value (a value can be old - the CASCADE_ACTUAL_VALUE bit will not be set).

CASCADE_TTL_INVOLVED

A returned value is not actual value and already is old because some dependence is newly than value which depends from this. But you describes an option ttl in "rule" in CHI::Cascade. If you had passed the option ttl like \$ttl to "run" in CHI::Cascade method there in $ttl will be fractal number of "time to live" - how many seconds are left before the computation (of course, if you will call run again for that target). This feature is useful for global reset mechanism (one reset target as global dependence and other rules from its have a ttl parameter in rules).

AUTHOR

This module has been written by Perlover <perlover@perlover.com>

LICENSE

This module is free software and is published under the same terms as Perl itself.

SEE ALSO

CHI::Cascade