This module is the attempt to use a benefits of caching and 'make' concept. If we have many an expensive tasks (a computations or sometimes here used term as a recomputing) and want to cache it we can split its to small expsnsive tasks and to describe dependencies for cache items.

This module is experimental yet. I plan to improve it near time but some things already work. You can take a look for t/* tests as examples.

Optional. Default is never. This is not busy_lock option of CHI! This is amount of time (to see "DURATION EXPRESSIONS" in CHI) until all target locks expire. When a target is to being computing it is locked. If process which is to be computing target and it will die or OS will be hangs up we can dead locks and locked target will never recomputed again. This option helps to avoid it. You can set up a special busy_lock for rules too.

Optional. This is CHI cache for target markers. Default value is value of "chi" option. It can be useful if you use a "l1_cache" in CHI option. So you can separate data of targets from target markers - data will be kept in a file cache and a marker in memory cache for example.

An each item of list can be scalar value (exactly matched target) or code reference. If item is coderef it will be executed as $coderef->( $rule, $rule->qr_params ) and should return a scalar value as current dependence for this target at runtime (the API for coderef parameters was changed since v0.16)

This subroutine will be executed every time inside run method if necessary and with parameters as: $coderef->( $rule, $rule->qr_params ) (API was changed since v0.16). It should return scalar or arrayref. The returned value is scalar it will be considered as single dependence of this target and the behavior will be exactly as described for scalar in this paragraph. If the returned value is arrayref it will be considered as list of dependencies for this target and the behavior will be exactly as described for arrayref in this paragraph.

Optional. This is coderef for dependence exceptions. If any dependence from list of "depends"'s option throws an exception of type CHI::Cascade::Value by die (for example like this code: die CHI::Cascade::Value->new->value( { i_have_problem => 1 } ) ) then the $cascade will execute this code as $rule->{depends_catch}->( $this_rule_obj, $exception_of_dependence, $rule_obj_of_dependence, $plain_text_target_of_dependence ) and you can do into inside a following:

You can make something in this code. After execution of your code the cascade re-throws original exception of dependence like described above in "re-die" section.

But please notice that original exception has a status of "thrown from code" so it can be catched later by other "depends_catch" callback from other rule located closer to the call hierarchy of "run".

Please notice that there no way to continue a "code" of current rule if any dependence throws an exception!. It because that the main concept of execution code of rules is to have all valid values (cached or recomputed) of all dependencies before execution of dependent code.

Required. The code reference for computing a value of this target (a computational code). Will be executed if no value in cache for this target or any dependence or dependences of dependences and so on will be recomputed. Will be executed as $code->( $rule, $target, $hashref_to_value_of_dependencies )(The API of running this code was changed since v0.10)

If "run" method will have a "defer" option as true this code will not be executed and you will get a set bit CASCADE_DEFERRED in "state" bit mask variable. This may useful when you want to control a target execution.

An instance of CHI::Cascade::Rule object. You can use it object as accessor for some current executed target data (plain text of target, for getting of parameters and so on). Please to see CHI::Cascade::Rule

A hash reference of values (values are cleaned values not CHI::Cascade::Value objects!) of all dependencies for current target. Keys in this hash are flat strings of dependecies and values are computed or cached ones.

This module should guarantee that values of dependencies will be valid values even if value is undef. This code can return undef value as a valid code return but author doesn't recommend it. If CHI::Cascade could not get a valid values of all dependencies of current target before execution of this code the last will not be executed (The run will return undef).

Optional. Default is "busy_lock" of constructor or never if first is not defined. This is not busy_lock option of CHI! This is amount of time (to see "DURATION EXPRESSIONS" in CHI) until target lock expires. When a target is to being computed it is locked. If process which to be recomputing a target and it will die or OS will be hangs up we can dead locks and locked target will never recomputed again. This option helps to avoid it.

Optional. This is a computational callback (coderef). If target of this rule was recomputed this callback will be executed right away after a recomputed value has been saved in cache. The callback will be executed as $coderef->( $rule, $target, $value ) where passed parameters are:

Optional. An arrayref for min & max intervals of TTL. Example: [ 60, 3600 ] - where the minimum ttl is seconds and the maximum is 3600 seconds. Targets of this rule will be recomputed during from 60 up to 3600 seconds from touched time of any dependence this rule. Please read "CASCADE_TTL_INVOLVED" in CHI::Cascade::Value too.

This method makes a cascade computation if need and returns value (value is cleaned value not CHI::Cascade::Value object!) for this target If any dependence of this target of any dependencies of dependencies were (re)computed this target will be (re)computed too.

If value will be a true then computational code will not be run if there is a need. After "run" you can test status of returned value - it should be (re)computed or not by bit CASCADE_DEFERRED in saved "state" variable. If the CASCADE_DEFERRED bit is set you can recall "run" method again or re-execute target in other process for a non-blocking execution of current process.

The value in seconds (a floating point value) of actual term. The actual term is period when dependencies to be checked for $target in "run" method. If this option is not defined then the "run" method checks a dependencies of $target every time in runtime. But sometimes (when a target has many dependencies) we could want to reduce an amount of dependencies checks. For example if actual_term will be defined as 2.5 this will mean to check a dependencies only every 2.5 seconds. So recomputing in this example can be recomputed only one time in every 2.5 seconds (even if one from dependencies will be updated). But if value of $target is missing in cache a recomputing can be run regardless of this option.

A scalarref for getting current TTL for value of 'run' target. The TTL is "time to live" as TTL in DNS. If any rule in a path of following to dependencies has ttl parameter then the cascade will do there:

will look up a time of this retouched dependence;

if rule's target marker already has a upper time and this time in future the target will be recomputed in this time in future and before this moment you will get a old data from cache for 'run' target. If this time is there and has elapsed cascade will use a standard algorithm.

will look up the rule's ttl parameter (min & max ttl values) and will generate upper time of computation of this rule's target and will return from "run" method old data of 'run' target. Next "run"s executions will return old values of any targets where this TTL-marked target is as dependence.

In any case if old value misses in cache the cascade will recompute codes.

This feature was made for reset situation. For example if we have 'reset' rule and all rules depend from this one rule the better way will be to have 'ttl' parameter in every rule except 'reset' rule. So if rule 'reset' will be retouched (or deleted) other targets will be recomputed during time from 'min' and 'max' intervals from 'reset' touched time. It reduce a server's load. Later i will add examples for this and will document this feature more details. Please read "CASCADE_TTL_INVOLVED" in CHI::Cascade::Value too.

This method refreshes the time of this target. Here is analogy with touch utility of Unix and behaviour as make(1) after it. After "touch" all targets are dependent from this target will be recomputed at next "run" with an appropriate ones.

It's like a removing of target file in make. You can force to recompute target by this method. It will remove target marker if one exists and once when cascade will need target value it will be recomputed. In a during recomputing of course cascade will return an old value if one exists in cache.

It returns hashref to a stash. A stash is hash for temporary data between rule's codes. It can be used only from inside "run". Example:

$cascade->run( 'target', stash => { key1 => value1 } )

and into rule's code:

$rule->cascade->stash->{key1}

If a "run" method didn't get stash hashref the default stash will be as empty hash. You can pass a data between rule's codes but it's recommended only in special cases. For example when run's target cannot get a full data from its target's name.

If module needs to compute item for cache we compute inside process (no forks) For web applications it means that one process for one request could take a some time for computing. But other processes will not wait and will get either old previous computed value or undef value.

If other process want to get data from cache we should not block it. So concurrent process can get an old data if new computing is run or can get undef value. A concurrent process should decide itself what it should do after it - try again after few time or print some message like 'Please wait and try again' to user.

If unique_name_other1 and/or unique_name_other2 are(is) more newer than unique_name the unique_name will be recomputed. If in this example unique_name_other1 and unique_name_other2 are older than unique_name but the unique_name_other3 is newer than unique_name_other1 then unique_name_other1 will be recomputed and after the unique_name will be recomputed.