NAME

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

SYNOPSIS

       NON-OO:

          use PDL::DiskCache;
          tie @a,'PDL::DiskCache', \@files, \%options;
          imag $a[3];

       OO:

          use PDL::DiskCache;
          $x = diskcache(\@files,\%options);
          imag $x->[3];

       or

          use PDL::DiskCache;
          $x = PDL::DiskCache->new(\@files,\%options);
          imag $x->[4];

       \@files
          an array ref containing a list of file names

       \%options
          a hash ref containing options for the PDL::DiskCache object (see "TIEARRAY" below for details)

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.

       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).

       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!

       The hash ref interface is kept for historical reasons; you can access the sync() and purge() method calls
       directly from the returned array ref.

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.

       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 PDL::Dumper::sdump() a large PDL::DiskCache, for example -- that
       would defeat the purpose of using a PDL::DiskCache in the first place.

Author, license, no warranty

       Copyright 2001, Craig DeForest

       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.

       If   you   modify   the   code  and  it's  useful,  please  send  a  copy  of  the  modified  version  to
       cdeforest@solar.stanford.edu.

       This package comes with NO WARRANTY.

FUNCTIONS

   diskcache
       Object constructor.

         $x = diskcache(\@f,\%options);

       Options

       •  See the TIEARRAY options, below.

   TIEARRAY
       Tied-array constructor; invoked by perl during object construction.

         TIEARRAY(class,\@f,\%options)

       Options

       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)

       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.

       mem (default 20)
          Number of files to be cached in memory at once.

       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: $object = rfits(filename).

       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).

       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 "$x->sync" instead of the  more
          complex  "(%{tied  @$x})->sync",  but  "ref $x" will return "PDL::DiskCache" instead of "ARRAY", which
          could break some code.

       verbose (default 0)
          Get chatty.

   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.)

       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.

   sync
       In a rw cache, flush items out to disk but retain them in the cache.

       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).

       For ro caches, this is a not-too-slow (but safe) no-op.

   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.

perl v5.38.2                                       2024-04-10                                     DiskCache(3pm)