view release on metacpan or  search on metacpan

lib/CHI/Cascade/Value.pm  view on Meta::CPAN

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 L<CHI::Cascade/run> method will return an old value from cache or if
it's not in cache it will return an C<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 C<undef> is valid
value too! But bacause the L<CHI::Cascade/run> method returns only a value (not
instance of L<CHI::Cascade::Value> object) there is not recommended to use
C<undef> values (C<run> method returns C<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 L<CHI::Cascade/run>
method and don't want to save value in cache.

=head1 CONSTRUCTOR

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

It will create instance $value with nothing value

=head1 METHODS

=over

=item value

Examples:

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

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

=item is_value

    $value->is_value

returns C<true> if value was set by L</value> method or C<false> else.

=item state

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

A getting or setting of state bits of value object.

=item 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 L</"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.

=back

=head1 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 L<CHI::Cascade/run> in L<CHI::Cascade/state>
variable.

=over

=item CASCADE_NO_CACHE

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

=item CASCADE_COMPUTING

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

=item CASCADE_DEFERRED

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

=item CASCADE_FROM_CACHE

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

=item CASCADE_ACTUAL_VALUE

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

=item CASCADE_RECOMPUTED

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

=item CASCADE_CODE_EXCEPTION

This state bit occurs only if exception was thrown from code or any dependencies
and it has the type L<CHI::Cascade::Value> (the expression C<<
$@->isa('CHI::Cascade::Value') >> is C<true>). If there to be thrown an other