Author: larry Date: Wed May 30 09:13:35 2007 New Revision: 14409 Modified: doc/trunk/design/syn/S06.pod
Log: Added "is reparsed" and removed $<KEY> kludge Explained caching semantics more thoroughly as suggested by Tim Bunce++ Modified: doc/trunk/design/syn/S06.pod ============================================================================== --- doc/trunk/design/syn/S06.pod (original) +++ doc/trunk/design/syn/S06.pod Wed May 30 09:13:35 2007 @@ -13,9 +13,9 @@ Maintainer: Larry Wall <[EMAIL PROTECTED]> Date: 21 Mar 2003 - Last Modified: 29 May 2007 + Last Modified: 30 May 2007 Number: 6 - Version: 85 + Version: 86 This document summarizes Apocalypse 6, which covers subroutines and the @@ -1467,31 +1467,61 @@ =item C<is parsed> Specifies the subrule by which a macro call is parsed. The parse -always starts after the macro token, but the token may be referred -to within the subrule as C<< $<KEY> >>. +always starts after the macro's initial token. + +=item C<is reparsed> + +Also specifies the subrule by which a macro call is parsed, but restarts +the parse before the macro's initial token, usually because you want +to parse using an existing rule that expects to traverse the initial +token. =item C<is cached> -Marks a subroutine as being memoized, or at least memoizable. The +Marks a subroutine as being memoized, or at least memoizable. +In the abstract, this cache is just a hash where incoming argument +C<Capture>s are mapped to return values. If the C<Capture> is found in +the hash, the return value need not be recalculated. If you use +this trait, the compiler will assume two things: + +=over + +=item * + +A given C<Capture> would always calculate the same return value. That is, +there is no state hidden within the dynamic scope of the call. + +=item * + +The cache lookup is likely to be more efficient than recalculating +the value in at least some cases, because either most uncached calls +would be slower (and reduce throughput), or you're trying to avoid a +significant number of pathological cases that are unacceptably slow +(and increase latency). + +=back + +This trait is a suggestion to the compiler that caching is okay. The compiler is free to choose any kind of caching algorithm (including non-expiring, random, lru, pseudo-lru, or adaptive algoritms, or even no caching algorithm at all). The run-time system is free to choose any kind of maximum cache size depending on the availability of memory and trends in usage patterns. You may suggest a particular -cache size by passing a numeric argument, and some of the possible +cache size by passing a numeric argument (representing the maximum number +of unique C<Capture> values allowed), and some of the possible algorithms may pay attention to it. You may also pass C<*> for the size to request a non-expiring cache (complete memoization). The compiler is free to ignore this too. -The intent of this pragma is to specify performance hints without -mandating any exact behavior. Use of this pragma should not change -semantics of the program, and this pragma will not be extended to -reinvent other existing ways of achieving the same effect. To gain -more control, write your own trait handler to allow the use of a more -specific trait, such as "C<is lru(42)>". Alternately, just -use a state hash keyed on the sub's argument capture to write -your own memoization with complete control from within the subroutine -itself. +The intent of this trait is to specify performance hints without +mandating any exact behavior. Proper use of this trait should not +change semantics of the program; it functions as a kind of "pragma". +This trait will not be extended to reinvent other existing ways of +achieving the same effect. To gain more control, write your own +trait handler to allow the use of a more specific trait, such as +"C<is lru(42)>". Alternately, just use a state hash keyed on the +sub's argument capture to write your own memoization with complete +control from within the subroutine itself. =item C<is inline>
