File Coverage

blib/lib/Memoize/Once.pm
Criterion Covered Total %
statement 18 18 100.0
branch n/a
condition n/a
subroutine 6 6 100.0
pod n/a
total 24 24 100.0


line stmt bran cond sub pod time code
1             =head1 NAME
2              
3             Memoize::Once - memoise expression on first execution
4              
5             =head1 SYNOPSIS
6              
7             use Memoize::Once qw(once);
8              
9             $value = once(expensive_computation());
10              
11             =head1 DESCRIPTION
12              
13             This module supplies an operator that causes an expression to be evaluated
14             only once per program run, memoising its value for the remainder of
15             the run.
16              
17             =cut
18              
19             package Memoize::Once;
20              
21 11     11   295468 { use 5.006; }
  11         42  
  11         749  
22 11     11   59 use warnings;
  11         25  
  11         460  
23 11     11   71 use strict;
  11         38  
  11         453  
24              
25 11     11   11686 use Devel::CallChecker 0.003 ();
  11         26837  
  11         288  
26 11     11   77 use XSLoader;
  11         20  
  11         431  
27              
28             our $VERSION = "0.000";
29              
30 11     11   49 use parent "Exporter";
  11         22  
  11         45  
31             our @EXPORT_OK = qw(once);
32              
33             XSLoader::load(__PACKAGE__, $VERSION);
34              
35             =head1 OPERATORS
36              
37             =over
38              
39             =item once(EXPR)
40              
41             Evaluate I once and memoise its value. The first time a C
42             expression is evaluated, I is evaluated, and (if everything proceeds
43             normally) C stores the value it yielded and also yields the same
44             value. When the same C expression is evaluated subsequently, it
45             yields the value that I yielded the first time, without evaluating
46             I again. There is one instance of this memoisation for each
47             instance of the C operator in the source.
48              
49             Because I is not evaluated until the C operator is being
50             evaluated, it can refer to and use any aspects of the lexical and dynamic
51             environment as they exist at runtime of the C operator. However,
52             if I yields different results depending on variable aspects of the
53             environment, such as arguments of the surrounding subroutine, then the
54             memoisation is probably inappropriate. That is, I can't sensibly
55             depend on the specific features of an invocation of the surrounding
56             code, but can depend on the general features that are consistent to
57             all invocations.
58              
59             If evaluation of I results in an exception, rather than yielding
60             a normal value, no value will be memoised. A value will be memoised
61             the first time that I does yield a normal value. If multiple
62             evaluations of I are in progress simultaneously (due to recursion),
63             and multiple instances of it yield a normal value, then the first yielded
64             value will be memoised and others will be ignored. A C expression
65             will never yield a value other than the one it memoised.
66              
67             I is always evaluated in scalar context, regardless of the
68             context in which the C operator appears. To memoise a list,
69             write C<@{once([...])}>.
70              
71             =back
72              
73             =head1 BUGS
74              
75             L will generate incorrect source when deparsing C
76             expressions. The code that it displays gives a rough indication of
77             how memoisation operates, but appears buggy in detail. In fact the
78             C operator works through some custom ops that cannot be adequately
79             represented in pure Perl.
80              
81             =head1 SEE ALSO
82              
83             L
84              
85             =head1 AUTHOR
86              
87             Andrew Main (Zefram)
88              
89             =head1 COPYRIGHT
90              
91             Copyright (C) 2011 Andrew Main (Zefram)
92              
93             =head1 LICENSE
94              
95             This module is free software; you can redistribute it and/or modify it
96             under the same terms as Perl itself.
97              
98             =cut
99              
100             1;