Official release of v0.26

Perlover · Dec 14, 2012 · 625d6f8 · 625d6f8
1 parent ad82ab5
commit 625d6f8
Show file tree

Hide file tree

Showing 4 changed files with 72 additions and 36 deletions.
diff --git a/Changes b/Changes
@@ -1,30 +1,33 @@
-NEXT (may be 0.26)
+0.26 (STABLE)
     *) New conception of non-blocking run method - deferring
     *) The test 04_memcached_multi.t some fails in FreeBSD. May be this is
        because 'sleep' works not as expected. I changed the 'sleep' to
        'select($,$,$,$)'. May be it will improve this test at FreeBSD...
     +) Added CHI::Cascade::Rule::value_expires method for changing by recompute
-       code the expiration time of values & target markers (no docs yet)
+       code the expiration time of values & target markers
     +) Added test for value_expires - test_05.pm by 08_fast_mmap.t
     *) Fixed bugs - in tests *_fast_mmap.t if was ^C signal - files of FastMmap
        driver were not deleted
-    *) The new method CHI::Cascade::Value->state (no docs yet)
-    +) Added method CHI::Cascade::Value::state_as_str (no docs yet)
+    *) The new method CHI::Cascade::Value->state
+    +) Added method CHI::Cascade::Value::state_as_str
     *) The test '07_fast_mmap.t' tests now deferring & states of values
     *) Fix few bug with target locking
     *) Fixed unproductive code piece of value with expiring
     *) Fixed unproductive code with target locking
     *) Changed some tests for testing the 'actual_term' option
-    +) Added stats  for operations 'run' & 'dependencies_lookup'
-    +) Added the bit state CASCADE_ACTUAL_TERM
-    +) Added 'ttl' feature. Few some docs about this yet but there is tests for it
-    +) CHI::Cascade->rule now has the new option: value_expires
+    +) Added stats for operations 'run' & 'dependencies_lookup'
+    +) Added bits of state CASCADE_ACTUAL_TERM & CASCADE_TTL_INVOLVED
+    +) Added 'ttl' feature.
+    +) CHI::Cascade->rule has now some new options: value_expires & ttl
+    +) CHI::Cascade->run has now some new options: ttl & stash
     *) Memcached tests are skipped by default. They use a starting of memcached
        and from cpanm they doesn't work. If you want to tests please use this
-       method: perl Makefile.PL; FORCE_MEMCACHED_TESTS= make test && make install
-    +) Added stack for targets for circled dependencies die (now it prints stack)
+       method:
+	$ perl Makefile.PL
+	$ FORCE_MEMCACHED_TESTS=1 make test && make install
+    +) Added a stack info for targets for circled dependencies die (now it prints stack)
     *) Fixed bug with circled dependencies - now more accurate (no tests)
-    +) Added new method 'stash' and same option in 'run' method of CHI::Cascade
+    +) Added new method 'stash' for getting a stash passed through 'run' method
 
 0.25001
     *) Few fix - should improve tests

diff --git a/README b/README
@@ -247,11 +247,12 @@ METHODS
             created by this rule in notation described in "DURATION
             EXPRESSIONS" in CHI. The default is 'never'.
 
-        ttl Optional. *(Soon will be more documented)* 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 to 3600 seconds
-            from touched time of any dependence this rule.
+        ttl 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.
 
     run( $target, %options )
         This method makes a cascade computation if need and returns value
@@ -294,11 +295,10 @@ METHODS
                 is missing in cache a recomputing can be run regardless of
                 this option.
 
-            ttl *(Soon will be more documented)* 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:
+            ttl 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:
 
                 1.  will look up a time of this retouched dependence;
 
@@ -326,7 +326,8 @@ METHODS
                 (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.
+                and will document this feature more details. Please read
+                "CASCADE_TTL_INVOLVED" in CHI::Cascade::Value too.
 
             stash
                 A *hashref* to stash - temporary data container between

diff --git a/lib/CHI/Cascade.pm b/lib/CHI/Cascade.pm
@@ -3,7 +3,7 @@ package CHI::Cascade;
 use strict;
 use warnings;
 
-our $VERSION = 0.2520;
+our $VERSION = 0.26;
 
 use Carp;
 
@@ -721,11 +721,12 @@ notation described in L<CHI/"DURATION EXPRESSIONS">. The B<default> is 'never'.
 
 =item ttl
 
-B<Optional>. I<(Soon will be more documented)>
+B<Optional>.
 An arrayref for min & max intervals of TTL. Example: C<[ 60, 3600 ]> - where the
 minimum ttl is seconds and the maximum is 3600 seconds. Targets of this rule
-will be recomputed during from 60 to 3600 seconds from touched time of any
-dependence this rule.
+will be recomputed during from 60 up to 3600 seconds from touched time of any
+dependence this rule. Please read L<CHI::Cascade::Value/CASCADE_TTL_INVOLVED>
+too.
 
 =back
 
@@ -777,10 +778,9 @@ run regardless of this option.
 
 =item ttl
 
-I<(Soon will be more documented)> A B<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:
+A B<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:
 
 =over
 
@@ -813,7 +813,8 @@ 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.
+i will add examples for this and will document this feature more details. Please
+read L<CHI::Cascade::Value/CASCADE_TTL_INVOLVED> too.
 
 =item stash
 

diff --git a/lib/CHI/Cascade/Value.pm b/lib/CHI/Cascade/Value.pm
@@ -180,13 +180,33 @@ returns C<true> if value was set by L</value> method or C<false> else.
 
 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 described by
-state bits. To use this bit mask we can know how this value was gotten.
+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
 
@@ -232,9 +252,20 @@ die CHI::Cascade::Value->new(undef) >>)
 
 =item CASCADE_ACTUAL_TERM
 
-The method L<CHI::Cascade/run> was run with L<actual_term|CHI::Cascade/actual_term> option
-and C<actual term> is actual for this value (a value can be old - the
-CASCADE_ACTUAL_VALUE bit will not be set).
+The method L<CHI::Cascade/run> was run with
+L<actual_term|CHI::Cascade/actual_term> option and C<actual term> is actual for
+this value (a value can be old - the CASCADE_ACTUAL_VALUE bit will not be set).
+
+=item 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 C<ttl>
+in L<CHI::Cascade/rule>. If you had passed the option C<ttl> like C<\$ttl> to
+L<CHI::Cascade/run> 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 C<run> again for that target). This feature is useful for global reset
+mechanism (one I<reset> target as global dependence and other rules from its
+have a C<ttl> parameter in I<rules>).
 
 =back