File: //usr/local/share/man/man3/Cache::File.3pm
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Cache::File 3"
.TH Cache::File 3 "2021-11-08" "perl v5.26.3" "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"
Cache::File \- Filesystem based implementation of the Cache interface
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Cache::File;
\&
\& my $cache = Cache::File\->new( cache_root => \*(Aq/tmp/mycache\*(Aq,
\& default_expires => \*(Aq600 sec\*(Aq );
.Ve
.PP
See Cache for the usage synopsis.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Cache::File class implements the Cache interface. This cache stores
data in the filesystem so that it can be shared between processes and persists
between process invocations.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.Vb 1
\& my $cache = Cache::File\->new( %options )
.Ve
.PP
The constructor takes cache properties as named arguments, for example:
.PP
.Vb 3
\& my $cache = Cache::File\->new( cache_root => \*(Aq/tmp/mycache\*(Aq,
\& lock_level => Cache::File::LOCK_LOCAL(),
\& default_expires => \*(Aq600 sec\*(Aq );
.Ve
.PP
Note that you \s-1MUST\s0 provide a cache_root property.
.PP
See '\s-1PROPERTIES\s0' below and in the Cache documentation for a list of all
available properties that can be set.
.SH "METHODS"
.IX Header "METHODS"
See 'Cache' for the \s-1API\s0 documentation.
.SH "PROPERTIES"
.IX Header "PROPERTIES"
Cache::File adds the following properties in addition to those discussed in
the 'Cache' documentation.
.IP "cache_root" 4
.IX Item "cache_root"
Used to specify the location of the cache store directory. All methods will
work \s-1ONLY\s0 data stored within this directory. This parameter is \s-1REQUIRED\s0 when
creating a Cache::File instance.
.Sp
.Vb 1
\& my $ns = $c\->cache_root();
.Ve
.IP "cache_depth" 4
.IX Item "cache_depth"
The number of subdirectories deep to store cache entires. This should be
large enough that no cache directory has more than a few hundred object.
Defaults to 2 unless explicitly set.
.Sp
.Vb 1
\& my $depth = $c\->cache_depth();
.Ve
.IP "cache_umask" 4
.IX Item "cache_umask"
Specifies the umask to use when creating entries in the cache directory. By
default the umask is '077', indicating that only the same user may access
the cache files.
.Sp
.Vb 1
\& my $umask = $c\->cache_umask();
.Ve
.IP "lock_level" 4
.IX Item "lock_level"
Specify the level of locking to be used. There are three different levels
available:
.IP "\fBCache::File::LOCK_NONE()\fR" 4
.IX Item "Cache::File::LOCK_NONE()"
No locking is performed. Useful when you can guarantee only one process will
be accessing the cache at a time.
.IP "\fBCache::File::LOCK_LOCAL()\fR" 4
.IX Item "Cache::File::LOCK_LOCAL()"
Locking is performed, but it is not suitable for use over \s-1NFS\s0 filesystems.
However it is more efficient.
.IP "\fBCache::File::LOCK_NFS()\fR" 4
.IX Item "Cache::File::LOCK_NFS()"
Locking is performed in a way that is suitable for use on \s-1NFS\s0 filesystems.
.PP
.Vb 1
\& my $level = $c\->cache_lock_level();
.Ve
.SH "CAVEATS"
.IX Header "CAVEATS"
There are a couple of caveats in the current implementation of Cache::File.
None of these will present a problem in using the class, it's more of a \s-1TODO\s0
list of things that could be done better.
.IP "external cache modification (and re-syncronization)" 4
.IX Item "external cache modification (and re-syncronization)"
Cache::File maintains indexes of entries in the cache, including the number of
entries and the total size. Currently there is no process of checking that
the count or size are in syncronization with the actual data on disk, and thus
any modifications to the cache store by another program (eg. a user shell)
will result in an inconsitency in the index. A better process would be for
Cache::File to resyncronize at an appropriate time (eg whenever the size or
count is initially requested \- this would only need happen once per instance).
This resyncronization would involve calculating the total size and count as
well as checking that entries in the index accurately reflect what is on the
disk (and removing any entries that have dissapeared or adding any new ones).
.IP "index efficiency" 4
.IX Item "index efficiency"
Currently Berkeley \s-1DB\s0's are used for indexes of expiry time, last use and entry
age. They use the \s-1BTREE\s0 variant in order to implement a heap (see
Cache::File::Heap). This is probably not the most efficient format and having
3 separate index files adds overhead. These are also cross-referenced with
a fourth index file that uses a normal hash db and contains all these time
stamps (frozen together with the validity object to a single scalar via
Storable) indexed by key. Needless to say, all this could be done more
efficiently \- probably by using a single index in a custom format.
.IP "locking efficiency" 4
.IX Item "locking efficiency"
Currently \s-1LOCK_LOCAL\s0 is not implemented (if uses the same code as \s-1LOCK_NFS\s0).
.Sp
There are two points of locking in Cache::File, index locking and entry
locking. The index locking is always exclusive and the lock is required
briefly during most operations. The entry locking is either shared or
exclusive and is also required during most operations. When locking is
enabled, File::NFSLock is used to provide the locking for both situations.
This is not overly efficient, especially as the entry lock is only ever
grabbed whilst the index lock is held.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Cache
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 2
\& Chris Leishman <chris@leishman.org>
\& Based on work by DeWitt Clinton <dewitt@unto.net>
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
.Vb 1
\& Copyright (C) 2003\-2006 Chris Leishman. All Rights Reserved.
.Ve
.PP
This module is distributed on an \*(L"\s-1AS IS\*(R"\s0 basis, \s-1WITHOUT WARRANTY OF ANY KIND,\s0
either expressed or implied. This program is free software; you can
redistribute or modify it under the same terms as Perl itself.
.PP
\&\f(CW$Id:\fR File.pm,v 1.7 2006/01/31 15:23:58 caleishm Exp $