.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DiskCache 3pm"
.TH DiskCache 3pm 2024-04-25 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
PDL::DiskCache \-\- Non\-memory\-resident array object
.SH SYNOPSIS
.IX Header "SYNOPSIS"
NON-OO:
.PP
.Vb 3
\&   use PDL::DiskCache;
\&   tie @a,\*(AqPDL::DiskCache\*(Aq, \e@files, \e%options;
\&   imag $a[3];
.Ve
.PP
OO:
.PP
.Vb 3
\&   use PDL::DiskCache;
\&   $x = diskcache(\e@files,\e%options);
\&   imag $x\->[3];
.Ve
.PP
or
.PP
.Vb 3
\&   use PDL::DiskCache;
\&   $x = PDL::DiskCache\->new(\e@files,\e%options);
\&   imag $x\->[4];
.Ve
.IP \e@files 3
.IX Item "@files"
an array ref containing a list of file names
.IP \e%options 3
.IX Item "%options"
a hash ref containing options for the PDL::DiskCache object (see "TIEARRAY"
below for details)
.SH DESCRIPTION
.IX Header "DESCRIPTION"
A PDL::DiskCache object is a perl "tied array" that is useful
for operations where you have to look at a large collection of PDLs  one
or a few at a time (such as tracking features through an image sequence).  
You can write prototype code that uses a perl list of a few PDLs, then 
scale up to to millions of PDLs simply by handing the prototype code
a DiskCache tied array instead of a native perl array.  The individual
PDLs are stored on disk and a few of them are swapped into memory on a
FIFO basis.  You can set whether the data are read-only or writeable.
.PP
By default, PDL::DiskCache uses FITS files to represent the PDLs, but
you can use any sort of file at all \-\- the read/write routines are the
only place where it examines the underlying data, and you can specify 
the routines to use at construction time (or, of course, subclass 
PDL::DiskCache).
.PP
Items are swapped out on a FIFO basis, so if you have 10 slots
and an expression with 10 items in it then you're OK (but you probably
want more slots than that); but if you use more items in an expression than
there are slots, thrashing will occur!
.PP
The hash ref interface is kept for historical reasons; you can access
the \fBsync()\fR and \fBpurge()\fR method calls directly from the returned array ref.
.SH "Shortcomings & caveats"
.IX Header "Shortcomings & caveats"
There's no file locking, so you could really hose yourself by having two of
these things going at once on the same files.
.PP
Since this is a tied array, things like Dumper traverse it transparently.
That is sort-of good but also sort-of dangerous.  You wouldn't want to
\&\fBPDL::Dumper::sdump()\fR a large PDL::DiskCache, for example \-\- that would defeat
the purpose of using a PDL::DiskCache in the first place.
.SH "Author, license, no warranty"
.IX Header "Author, license, no warranty"
Copyright 2001, Craig DeForest
.PP
This code may be distributed under the same terms as Perl itself
(license available at <http://www.perl.org>).  Copying, reverse engineering,
distribution, and modification are explicitly allowed so long as this notice
is preserved intact and modified versions are clearly marked as such.
.PP
If you modify the code and it's useful, please send a copy of the modified
version to cdeforest@solar.stanford.edu.
.PP
This package comes with NO WARRANTY.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.SS diskcache
.IX Subsection "diskcache"
Object constructor.
.PP
.Vb 1
\&  $x = diskcache(\e@f,\e%options);
.Ve
.PP
Options
.IP \(bu 3
See the TIEARRAY options, below.
.SS TIEARRAY
.IX Subsection "TIEARRAY"
Tied-array constructor; invoked by perl during object construction.
.PP
.Vb 1
\&  TIEARRAY(class,\e@f,\e%options)
.Ve
.PP
Options
.IP "ro (default 0)" 3
.IX Item "ro (default 0)"
If set, treat the files as read-only (modifications
to the tied array will only persist until the changed elements are
swapped out)
.IP "rw (default 1)" 3
.IX Item "rw (default 1)"
If set, allow reading and writing to the files.
Because there's currently no way to determine reliably whether a PDL
has been modified, rw files are always written to disk when they're
swapped out \-\- this causes a slight performance hit.
.IP "mem (default 20)" 3
.IX Item "mem (default 20)"
Number of files to be cached in memory at once.
.IP "read (default \e&rfits)" 3
.IX Item "read (default &rfits)"
A function ref pointing to code that will read
list objects from disk.  The function must have the same syntax as
rfits: \f(CW$object\fR = rfits(filename).
.IP "write (default \e&wfits)" 3
.IX Item "write (default &wfits)"
A function ref pointing to code that will
write list objects to disk.  The function must have the same syntax as
wfits: func(object,filename).
.IP "bless (default 0)" 3
.IX Item "bless (default 0)"
If set to a nonzero value, then the array ref gets
blessed into the DiskCache class for for easier access to the "purge"
and "sync" methods.  This means that you can say \f(CW\*(C`$x\->sync\*(C'\fR instead
of the more complex \f(CW\*(C`(%{tied @$x})\->sync\*(C'\fR, but \f(CW\*(C`ref $x\*(C'\fR will return
"PDL::DiskCache" instead of "ARRAY", which could break some code.
.IP "verbose (default 0)" 3
.IX Item "verbose (default 0)"
Get chatty.
.SS purge
.IX Subsection "purge"
Remove an item from the oldest slot in the cache, writing to disk as necessary.
You also send in how many slots to purge (default 1; sending in \-1 purges
everything.)
.PP
For most uses, a nice MODIFIED flag in the data structure could save
some hassle here.  But PDLs can get modified out from under us 
with slicing and .= \-\- so for now we always assume everything is tainted
and must be written to disk.
.SS sync
.IX Subsection "sync"
In a rw cache, flush items out to disk but retain them in the cache.
.PP
Accepts a single scalar argument, which is the index number of a
single item that should be written to disk. Passing (\-1), or no
argument, writes all items to disk, similar to purge(\-1).
.PP
For ro caches, this is a not-too-slow (but safe) no-op.
.SS DESTROY
.IX Subsection "DESTROY"
This is the perl hook for object destruction.  It just makes a call to
"sync", to flush the cache out to disk.  Destructor calls from perl don't
happen at a guaranteed time, so be sure to call "sync" if you need to 
ensure that the files get flushed out, e.g. to use 'em somewhere else.