1DiskCache(3)          User Contributed Perl Documentation         DiskCache(3)
2
3
4

NAME

6       PDL::DiskCache -- Non-memory-resident array object
7

SYNOPSIS

9       NON-OO:
10
11          use PDL::DiskCache;
12          tie @a,'PDL::DiskCache', \@files, \%options;
13          imag $a[3];
14
15       OO:
16
17          use PDL::DiskCache;
18          $x = diskcache(\@files,\%options);
19          imag $x->[3];
20
21       or
22
23          use PDL::DiskCache;
24          $x = PDL::DiskCache->new(\@files,\%options);
25          imag $x->[4];
26
27       \@files
28          an array ref containing a list of file names
29
30       \%options
31          a hash ref containing options for the PDL::DiskCache object (see
32          "TIEARRAY" below for details)
33

DESCRIPTION

35       A PDL::DiskCache object is a perl "tied array" that is useful for
36       operations where you have to look at a large collection of PDLs  one or
37       a 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
44       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
50       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
55       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

Shortcomings & caveats

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
63       Since this is a tied array, things like Dumper traverse it
64       transparently.  That is sort-of good but also sort-of dangerous.  You
65       wouldn't want to PDL::Dumper::sdump() a large PDL::DiskCache, for
66       example -- that would defeat the purpose of using a PDL::DiskCache in
67       the first place.
68

Author, license, no warranty

70       Copyright 2001, Craig DeForest
71
72       This code may be distributed under the same terms as Perl itself
73       (license available at <http://www.perl.org>).  Copying, reverse
74       engineering, distribution, and modification are explicitly allowed so
75       long as this notice is preserved intact and modified versions are
76       clearly marked as such.
77
78       If you modify the code and it's useful, please send a copy of the
79       modified version to cdeforest@solar.stanford.edu.
80
81       This package comes with NO WARRANTY.
82

FUNCTIONS

84   diskcache
85       Object constructor.
86
87         $x = diskcache(\@f,\%options);
88
89       Options
90
91       •  See the TIEARRAY options, below.
92
93   TIEARRAY
94       Tied-array constructor; invoked by perl during object construction.
95
96         TIEARRAY(class,\@f,\%options)
97
98       Options
99
100       ro (default 0)
101          If set, treat the files as read-only (modifications to the tied
102          array will only persist until the changed elements are swapped out)
103
104       rw (default 1)
105          If set, allow reading and writing to the files.  Because there's
106          currently no way to determine reliably whether a PDL has been
107          modified, rw files are always written to disk when they're swapped
108          out -- this causes a slight performance hit.
109
110       mem (default 20)
111          Number of files to be cached in memory at once.
112
113       read (default \&rfits)
114          A function ref pointing to code that will read list objects from
115          disk.  The function must have the same syntax as rfits: $object =
116          rfits(filename).
117
118       write (default \&wfits)
119          A function ref pointing to code that will write list objects to
120          disk.  The function must have the same syntax as wfits:
121          func(object,filename).
122
123       bless (default 0)
124          If set to a nonzero value, then the array ref gets blessed into the
125          DiskCache class for for easier access to the "purge" and "sync"
126          methods.  This means that you can say "$x->sync" instead of the more
127          complex "(%{tied @$x})->sync", but "ref $x" will return
128          "PDL::DiskCache" instead of "ARRAY", which could break some code.
129
130       verbose (default 0)
131          Get chatty.
132
133   purge
134       Remove an item from the oldest slot in the cache, writing to disk as
135       necessary.  You also send in how many slots to purge (default 1;
136       sending in -1 purges everything.)
137
138       For most uses, a nice MODIFIED flag in the data structure could save
139       some hassle here.  But PDLs can get modified out from under us with
140       slicing and .= -- so for now we always assume everything is tainted and
141       must be written to disk.
142
143   sync
144       In a rw cache, flush items out to disk but retain them in the cache.
145
146       Accepts a single scalar argument, which is the index number of a single
147       item that should be written to disk. Passing (-1), or no argument,
148       writes all items to disk, similar to purge(-1).
149
150       For ro caches, this is a not-too-slow (but safe) no-op.
151
152   DESTROY
153       This is the perl hook for object destruction.  It just makes a call to
154       "sync", to flush the cache out to disk.  Destructor calls from perl
155       don't happen at a guaranteed time, so be sure to call "sync" if you
156       need to ensure that the files get flushed out, e.g. to use 'em
157       somewhere else.
158
159
160
161perl v5.38.0                      2023-07-21                      DiskCache(3)
Impressum