Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DiskCache(3)	      User Contributed Perl Documentation	  DiskCache(3)

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;
	  $a = diskcache(\@files,\%options);
	  imag $a->[3];

       or

	  use PDL::DiskCache;
	  $a = new PDL::DiskCache(\@files,\%options);
	  imag $a->[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.

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

       Options

       o  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	"$a->sync" instead of the more
	  complex "(%{tied @$a})->sync", but "ref $a" 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.32.0			  2018-05-05			  DiskCache(3)

NAME | SYNOPSIS | DESCRIPTION | Shortcomings & caveats | Author, license, no warranty | FUNCTIONS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=PDL::DiskCache&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help