Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 288 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/Memoize::Expire.3perl b/upstream/debian-unstable/man3/Memoize::Expire.3perl
new file mode 100644
index 00000000..1e6ac4f8
--- /dev/null
+++ b/upstream/debian-unstable/man3/Memoize::Expire.3perl
@@ -0,0 +1,288 @@
+.\" -*- 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 "Memoize::Expire 3perl"
+.TH Memoize::Expire 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+Memoize::Expire \- Plug\-in module for automatic expiration of memoized values
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 5
+\&  use Memoize;
+\&  use Memoize::Expire;
+\&  tie my %cache => \*(AqMemoize::Expire\*(Aq,
+\&                     LIFETIME => $lifetime,    # In seconds
+\&                     NUM_USES => $n_uses;
+\&
+\&  memoize \*(Aqfunction\*(Aq, SCALAR_CACHE => [HASH => \e%cache ];
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Memoize::Expire is a plug-in module for Memoize.  It allows the cached
+values for memoized functions to expire automatically.  This manual
+assumes you are already familiar with the Memoize module.  If not, you
+should study that manual carefully first, paying particular attention
+to the HASH feature.
+.PP
+Memoize::Expire is a layer of software that you can insert in between
+Memoize itself and whatever underlying package implements the cache.
+The layer presents a hash variable whose values expire whenever they
+get too old, have been used too often, or both. You tell \f(CW\*(C`Memoize\*(C'\fR to
+use this forgetful hash as its cache instead of the default, which is
+an ordinary hash.
+.PP
+To specify a real-time timeout, supply the \f(CW\*(C`LIFETIME\*(C'\fR option with a
+numeric value.  Cached data will expire after this many seconds, and
+will be looked up afresh when it expires.  When a data item is looked
+up afresh, its lifetime is reset.
+.PP
+If you specify \f(CW\*(C`NUM_USES\*(C'\fR with an argument of \fIn\fR, then each cached
+data item will be discarded and looked up afresh after the \fIn\fRth time
+you access it.  When a data item is looked up afresh, its number of
+uses is reset.
+.PP
+If you specify both arguments, data will be discarded from the cache
+when either expiration condition holds.
+.PP
+Memoize::Expire uses a real hash internally to store the cached data.
+You can use the \f(CW\*(C`HASH\*(C'\fR option to Memoize::Expire to supply a tied
+hash in place of the ordinary hash that Memoize::Expire will normally
+use.  You can use this feature to add Memoize::Expire as a layer in
+between a persistent disk hash and Memoize.  If you do this, you get a
+persistent disk cache whose entries expire automatically.  For
+example:
+.PP
+.Vb 7
+\&  #   Memoize
+\&  #      |
+\&  #   Memoize::Expire  enforces data expiration policy
+\&  #      |
+\&  #   DB_File  implements persistence of data in a disk file
+\&  #      |
+\&  #   Disk file
+\&
+\&  use Memoize;
+\&  use Memoize::Expire;
+\&  use DB_File;
+\&
+\&  # Set up persistence
+\&  tie my %disk_cache => \*(AqDB_File\*(Aq, $filename, O_CREAT|O_RDWR, 0666];
+\&
+\&  # Set up expiration policy, supplying persistent hash as a target
+\&  tie my %cache => \*(AqMemoize::Expire\*(Aq, 
+\&                     LIFETIME => $lifetime,    # In seconds
+\&                     NUM_USES => $n_uses,
+\&                     HASH => \e%disk_cache; 
+\&
+\&  # Set up memoization, supplying expiring persistent hash for cache
+\&  memoize \*(Aqfunction\*(Aq, SCALAR_CACHE => [ HASH => \e%cache ];
+.Ve
+.SH INTERFACE
+.IX Header "INTERFACE"
+There is nothing special about Memoize::Expire.  It is just an
+example.  If you don't like the policy that it implements, you are
+free to write your own expiration policy module that implements
+whatever policy you desire.  Here is how to do that.  Let us suppose
+that your module will be named MyExpirePolicy.
+.PP
+Short summary: You need to create a package that defines four methods:
+.IP " TIEHASH" 4
+.IX Item " TIEHASH"
+Construct and return cache object.
+.IP " EXISTS" 4
+.IX Item " EXISTS"
+Given a function argument, is the corresponding function value in the
+cache, and if so, is it fresh enough to use?
+.IP " FETCH" 4
+.IX Item " FETCH"
+Given a function argument, look up the corresponding function value in
+the cache and return it.
+.IP " STORE" 4
+.IX Item " STORE"
+Given a function argument and the corresponding function value, store
+them into the cache.
+.IP " CLEAR" 4
+.IX Item " CLEAR"
+(Optional.)  Flush the cache completely.
+.PP
+The user who wants the memoization cache to be expired according to
+your policy will say so by writing
+.PP
+.Vb 2
+\&  tie my %cache => \*(AqMyExpirePolicy\*(Aq, args...;
+\&  memoize \*(Aqfunction\*(Aq, SCALAR_CACHE => [HASH => \e%cache];
+.Ve
+.PP
+This will invoke \f(CW\*(C`MyExpirePolicy\->TIEHASH(args)\*(C'\fR.
+MyExpirePolicy::TIEHASH should do whatever is appropriate to set up
+the cache, and it should return the cache object to the caller.
+.PP
+For example, MyExpirePolicy::TIEHASH might create an object that
+contains a regular Perl hash (which it will to store the cached
+values) and some extra information about the arguments and how old the
+data is and things like that. Let us call this object \fR\f(CI\*(C`C\*(C'\fR\fI\fR.
+.PP
+When Memoize needs to check to see if an entry is in the cache
+already, it will invoke \f(CW\*(C`C\->EXISTS(key)\*(C'\fR.  \f(CW\*(C`key\*(C'\fR is the normalized
+function argument.  MyExpirePolicy::EXISTS should return 0 if the key
+is not in the cache, or if it has expired, and 1 if an unexpired value
+is in the cache.  It should \fInot\fR return \f(CW\*(C`undef\*(C'\fR, because there is a
+bug in some versions of Perl that will cause a spurious FETCH if the
+EXISTS method returns \f(CW\*(C`undef\*(C'\fR.
+.PP
+If your EXISTS function returns true, Memoize will try to fetch the
+cached value by invoking \f(CW\*(C`C\->FETCH(key)\*(C'\fR.  MyExpirePolicy::FETCH should
+return the cached value.  Otherwise, Memoize will call the memoized
+function to compute the appropriate value, and will store it into the
+cache by calling \f(CW\*(C`C\->STORE(key, value)\*(C'\fR.
+.PP
+Here is a very brief example of a policy module that expires each
+cache item after ten seconds.
+.PP
+.Vb 1
+\&        package Memoize::TenSecondExpire;
+\&
+\&        sub TIEHASH {
+\&          my ($package, %args) = @_;
+\&          my $cache = $args{HASH} || {};
+\&          bless $cache => $package;
+\&        }
+\&
+\&        sub EXISTS {
+\&          my ($cache, $key) = @_;
+\&          if (exists $cache\->{$key} && 
+\&              $cache\->{$key}{EXPIRE_TIME} > time) {
+\&            return 1
+\&          } else {
+\&            return 0;  # Do NOT return undef here
+\&          }
+\&        }
+\&
+\&        sub FETCH {
+\&          my ($cache, $key) = @_;
+\&          return $cache\->{$key}{VALUE};
+\&        }
+\&
+\&        sub STORE {
+\&          my ($cache, $key, $newvalue) = @_;
+\&          $cache\->{$key}{VALUE} = $newvalue;
+\&          $cache\->{$key}{EXPIRE_TIME} = time + 10;
+\&        }
+.Ve
+.PP
+To use this expiration policy, the user would say
+.PP
+.Vb 3
+\&        use Memoize;
+\&        tie my %cache10sec => \*(AqMemoize::TenSecondExpire\*(Aq;
+\&        memoize \*(Aqfunction\*(Aq, SCALAR_CACHE => [HASH => \e%cache10sec];
+.Ve
+.PP
+Memoize would then call \f(CW\*(C`function\*(C'\fR whenever a cached value was
+entirely absent or was older than ten seconds.
+.PP
+You should always support a \f(CW\*(C`HASH\*(C'\fR argument to \f(CW\*(C`TIEHASH\*(C'\fR that ties
+the underlying cache so that the user can specify that the cache is
+also persistent or that it has some other interesting semantics.  The
+example above demonstrates how to do this, as does \f(CW\*(C`Memoize::Expire\*(C'\fR.
+.PP
+Another sample module, Memoize::Saves, is available in a separate
+distribution on CPAN.  It implements a policy that allows you to
+specify that certain function values would always be looked up afresh.
+See the documentation for details.
+.SH ALTERNATIVES
+.IX Header "ALTERNATIVES"
+Brent Powers has a Memoize::ExpireLRU module that was designed to
+work with Memoize and provides expiration of least-recently-used data.
+The cache is held at a fixed number of entries, and when new data
+comes in, the least-recently used data is expired.
+.PP
+Joshua Chamas's Tie::Cache module may be useful as an expiration
+manager.  (If you try this, let me know how it works out.)
+.PP
+If you develop any useful expiration managers that you think should be
+distributed with Memoize, please let me know.
+.SH CAVEATS
+.IX Header "CAVEATS"
+This module is experimental, and may contain bugs.  Please report bugs
+to the address below.
+.PP
+Number-of-uses is stored as a 16\-bit unsigned integer, so can't exceed
+65535.
+.PP
+Because of clock granularity, expiration times may occur up to one
+second sooner than you expect.  For example, suppose you store a value
+with a lifetime of ten seconds, and you store it at 12:00:00.998 on a
+certain day.  Memoize will look at the clock and see 12:00:00.  Then
+9.01 seconds later, at 12:00:10.008 you try to read it back.  Memoize
+will look at the clock and see 12:00:10 and conclude that the value
+has expired.  This will probably not occur if you have
+\&\f(CW\*(C`Time::HiRes\*(C'\fR installed.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Mark-Jason Dominus
+.PP
+Mike Cariaso provided valuable insight into the best way to solve this
+problem.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBperl\fR\|(1)
+.PP
+The Memoize man page.