1DiskCache(3) User Contributed Perl Documentation DiskCache(3)
2
6 PDL::DiskCache -- Non-memory-resident array object
7
9 NON-OO:
10 use PDL::DiskCache;
12 tie @a,'PDL::DiskCache', \@files, \%options;
13 imag $a[3];
14 OO:
16 use PDL::DiskCache;
18 $a = diskcache(\@files,\%options);
19 imag $a->[3];
20 or
22 use PDL::DiskCache;
24 $a = new PDL::DiskCache(\@files,\%options);
25 imag $a->[4];
26 \@files
28 an array ref containing a list of file names
29 \%options
31 a hash ref containing options for the PDL::DiskCache object (see
32 "TIEARRAY" below for details)
33
35 A PDL::DiskCache object is a perl "tied array" that is useful for oper‐
36 ations where you have to look at a large collection of PDLs one or a
37 few at a time (such as tracking features through an image sequence).
38 You can write prototype code that uses a perl list of a few PDLs, then
39 scale up to to millions of PDLs simply by handing the prototype code a
40 DiskCache tied array instead of a native perl array. The individual
41 PDLs are stored on disk and a few of them are swapped into memory on a
42 FIFO basis. You can set whether the data are read-only or writeable.
43 By default, PDL::DiskCache uses FITS files to represent the PDLs, but
45 you can use any sort of file at all -- the read/write routines are the
46 only place where it examines the underlying data, and you can specify
47 the routines to use at construction time (or, of course, subclass
48 PDL::DiskCache).
49 Items are swapped out on a FIFO basis, so if you have 10 slots and an
51 expression with 10 items in it then you're OK (but you probably want
52 more slots than that); but if you use more items in an expression than
53 there are slots, thrashing will occur!
54 The hash ref interface is kept for historical reasons; you can access
56 the sync() and purge() method calls directly from the returned array
57 ref.
58
60 There's no file locking, so you could really hose yourself by having
61 two of these things going at once on the same files.
62 Since this is a tied array, things like Dumper traverse it transpar‐
64 ently. That is sort-of good but also sort-of dangerous. You wouldn't
65 want to PDL::Dumper::sdump() a large PDL::DiskCache, for example --
66 that would defeat the purpose of using a PDL::DiskCache in the first
67 place.
68
70 Copyright 2001, Craig DeForest
71 This code may be distributed under the same terms as Perl itself
73 (license available at http://www.perl.org). Copying, reverse engineer‐
74 ing, distribution, and modification are explicitly allowed so long as
75 this notice is preserved intact and modified versions are clearly
76 marked as such.
77 If you modify the code and it's useful, please send a copy of the modi‐
79 fied version to cdeforest@solar.stanford.edu.
80 This package comes with NO WARRANTY.
82
84 diskcache
85 Object constructor.
87 Synopsis
89 $a = diskcache(\@f,\%options);
90 Options
92 see the TIEARRAY options,below.
93 TIEARRAY
95 Tied-array constructor; invoked by perl during object construction.
97 Synopsis
99 TIEARRAY(class,\@f,\%options)
100 Options
102 ro (default 0): If set, treat the files as read-only (modifications
103 to the tied array will only persist until the changed elements are
104 swapped out)
105 rw (default 1): If set, allow reading and writing to the files.
107 Because there's currently no way to determine reliably whether a PDL
108 has been modified, rw files are always written to disk when they're
109 swapped out -- this causes a slight performance hit.
110 mem (default 20): Number of files to be cached in memory at once.
112 read (default \&rfits): A function ref pointing to code that will
114 read list objects from disk. The function must have the same syntax
115 as rfits: $object = rfits(filename).
116 write (default \&wfits): A function ref pointing to code that will
118 write list objects to disk. The function must have the same syntax
119 as wfits: func(object,filename).
120 bless (default 0): If set to a nonzero value, then the array ref
122 gets blessed into the DiskCache class for for easier access to the
123 "purge" and "sync" methods. This means that you can say "$a-"sync>
124 instead of the more complex "(%{tied @$a})-"sync>, but "ref $a" will
125 return "PDL::DiskCache" instead of "ARRAY", which could break some
126 code.
127 verbose (default 0): Get chatty.
129 purge
131 Remove an item from the oldest slot in the cache, writing to disk as
133 necessary. You also send in how many slots to purge (default 1; send‐
134 ing in -1 purges everything.)
135 For most uses, a nice MODIFIED flag in the data structure could save
137 some hassle here. But PDLs can get modified out from under us with
138 slicing and .= -- so for now we always assume everything is tainted and
139 must be written to disk.
140 sync
142 In a rw cache, flush all items out to disk but retain them in the
144 cache. This is useful primarily for cache protection and could be
145 slow. Because we have no way of knowing what's modified and what's not
146 in the cache, all elements are always flushed from an rw cache. For ro
147 caches, this is a not-too-slow (but safe) no-op.
148 DESTROY
150 This is the perl hook for object destruction. It just makes a call to
152 "sync", to flush the cache out to disk. Destructor calls from perl
153 don't happen at a guaranteed time, so be sure to call "sync" if you
154 need to ensure that the files get flushed out, e.g. to use 'em some‐
155 where else.
156perl v5.8.8 2000-04-29 DiskCache(3)