.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
.\" ========================================================================
.\"
.IX Title "Arch::SharedIndex 3pm"
.TH Arch::SharedIndex 3pm "2022-06-08" "perl v5.34.0" "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"
Arch::SharedIndex \- a synchronized data structure (map) for IPC
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Arch::SharedIndex;
\&
\&    my $map = Arch::SharedIndex\->new(file => "/tmp/logintimes.idx");
\&    my $time = time;
\&    $map\->store(migo => $time \- 75, bob => $time \- 5, enno => $time);
\&
\&    printf "All users: %s, %s, %s\en", $map\->keys;
\&    printf "New users: %s\en", $map\->grep(sub { $_[1] == $time });
\&    printf "Login time of migo: %s\en", $map\->fetch(\*(Aqmigo\*(Aq);
\&
\&    $map\->update(sub { $_[1] + 10 }, sub { $_[1] == $time });
\&    $map\->store(migo => $time);
\&    $map\->delete(\*(Aqbob\*(Aq);
\&
\&    printf "Logged users with times: (%s)\en", join(", ", $map\->hash);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Arch::SharedIndex provides a key-value map that can be shared and
accessed safely by multiple processes.
.SH "METHODS"
.IX Header "METHODS"
The following methods are available:
.PP
\&\fBnew\fR,
\&\fBencode_value\fR,
\&\fBdecode_value\fR,
\&\fBstore_value\fR,
\&\fBfetch_value\fR,
\&\fBdelete_value\fR,
\&\fBstore\fR,
\&\fBfetch\fR,
\&\fBdelete\fR,
\&\fBfetch_store\fR,
\&\fBkeys\fR,
\&\fBvalues\fR,
\&\fBhash\fR,
\&\fBlist\fR,
\&\fBgrep\fR,
\&\fBfilter\fR,
\&\fBupdate\fR,
\&\fBquery_index_list\fR.
.IP "\fBnew\fR \fIoptions\fR" 4
.IX Item "new options"
Create a new index object.  \fIoption\fR is a hash of parameters.
.RS 4
.IP "\fBfile\fR" 4
.IX Item "file"
The path of the index file, used to store data.  Must not be omitted.
.IP "\fBcan_create\fR" 4
.IX Item "can_create"
Whether the index file is automatically created.  Defaults to 1.
.IP "\fBmax_size\fR" 4
.IX Item "max_size"
Maximum number of entries in the index.  Defaults to 0 (no limit).
.IP "\fBexpiration\fR" 4
.IX Item "expiration"
Timeout in seconds after which unused entries are removed.  Defaults
to 0 (don't expire entries)
.IP "\fBtime_renewal\fR" 4
.IX Item "time_renewal"
Whether fetching values resets the entry expiration timeout.  Defaults
to 1 if \fBmax_size\fR is set, 0 otherwise.
.IP "\fBperl_data\fR" 4
.IX Item "perl_data"
Whether non-scalar perl data can be stored.  If true, values are
encoded using Data::Dumper.
.IP "\fBperl_data_indent\fR" 4
.IX Item "perl_data_indent"
Indent value for Data::Dumper when \fBperl_data\fR is set.  Defaults to
0.
.IP "\fBperl_data_pair\fR" 4
.IX Item "perl_data_pair"
Pair value for Data::Dumper when \fBperl_data\fR is set.  Defaults to
\&\f(CW\*(C`=>\*(C'\fR.
.RE
.RS 4
.RE
.IP "\fBencode_value\fR \fIref\fR" 4
.IX Item "encode_value ref"
Encode the value referenced by \fIref\fR in a string representation.
The encoding is done in place.
.IP "\fBdecode_value\fR \fIref\fR" 4
.IX Item "decode_value ref"
Decode a value encoded with \fBencode_value\fR from its string
representation.  The decoding is done in place.
.IP "\fBstore_value\fR \fIkey\fR \fItoken\fR \fIvalue\fR" 4
.IX Item "store_value key token value"
Store a value for the given \fIkey\fR and \fItoken\fR.  Create a new token
if none is given.  Returns the (new) token.  Sub-classes should
implement this method.
.IP "\fBfetch_value\fR \fIkey\fR \fItoken\fR" 4
.IX Item "fetch_value key token"
Fetch the value stored for the given \fIkey\fR and \fItoken\fR.  Sub-classes
should implement this method.
.IP "\fBdelete_value\fR \fIkey\fR \fItoken\fR" 4
.IX Item "delete_value key token"
Delete a value stored for the given \fIkey\fR and \fIvalue\fR.  Sub-classes
should implement this method.
.IP "\fBstore\fR \fIkvp\fR" 4
.IX Item "store kvp"
Store a set of key-value pairs.  \fIkvp\fR may either be a reference to a
hash or array, or list of keys and values.
.IP "\fBfetch\fR \fIkeys\fR" 4
.IX Item "fetch keys"
Fetch values stored for a list of keys. \fIkeys\fR may either be an array
reference, or a list of keys.
.IP "\fBdelete\fR \fIkeys\fR" 4
.IX Item "delete keys"
Delete values stored for a list of keys.  \fIkeys\fR may either be an
array reference, or a list of keys.
.IP "\fBfetch_store\fR \fImapfunc\fR \fIkeys\fR" 4
.IX Item "fetch_store mapfunc keys"
This is an optimized (\fBfetch\fR or \fBstore\fR) in a single step.  Fetch
values stored for keys, just like \fBfetch\fR, but store values for the
missing keys in the process.  \fIkeys\fR may be an array reference or a list
of keys.  \fImapfunc\fR will be called once for every key in \fIkeys\fR that
has no associated value, with the key as its only argument.  Its return
value will be stored for that key.
.IP "\fBkeys\fR" 4
.IX Item "keys"
Returns a list of all valid keys.  In scalar context, returns an array
reference.
.Sp
Keys are returned in no particular order, but \fBvalues\fR will return
values in matching order if the index has not been changed between
calls.
.IP "\fBvalues\fR" 4
.IX Item "values"
Returns a list of all stored values.  In scalar context, returns an
array reference.
.Sp
Values are returned in no particular order, but \fBkeys\fR will return
values in matching order if the index has not been changed between
calls.
.IP "\fBhash\fR" 4
.IX Item "hash"
Returns the stored keys and values as a perl hash.  In scalar context,
returns hash reference.
.IP "\fBlist\fR" 4
.IX Item "list"
Returns the stored keys and values as a list of pairs (array
references with two elements each).  In scalar context, returns an
array reference.
.IP "\fBgrep\fR \fIpredicate\fR" 4
.IX Item "grep predicate"
Returns a list of keys for which \fIpredicate\fR returns a true value.
\&\fIpredicate\fR is called once for every key, with the key and the stored
value as its first and second argument.
.IP "\fBfilter\fR \fIpredicate\fR" 4
.IX Item "filter predicate"
Deletes every entry for which \fIpredicate\fR returns a true value.
\&\fIpredicate\fR is called once for every key, with the key and the stored
value asi its first and second argument.
.IP "\fBupdate\fR \fImapfunc\fR \fIpredicate\fR" 4
.IX Item "update mapfunc predicate"
Updates the value for every key for which \fIpredicate\fR returns a true
value with the return value from \fImapfunc\fR.  Both \fIpredicate\fR and
\&\fImapfunc\fR are called with the key and the stored values as their
first and second argument.
.IP "\fBupdate_index_list\fR \fIcode\fR" 4
.IX Item "update_index_list code"
Synchronize access and call \fIcode\fR with a reference to a list of
pairs, each containing the key and token, for every stored value.
.Sp
Used internally by \fBstore\fR, \fBfetch\fR, \fBdelete\fR, \fBfetch_store\fR,
\&\fBkeys\fR, \fBvalues\fR, \fBhash\fR, \fBlist\fR, \fBgrep\fR, \fBfilter\fR and \fBupdate\fR.
.SH "BUGS"
.IX Header "BUGS"
Awaiting for your reports.
.SH "AUTHORS"
.IX Header "AUTHORS"
Mikhael Goikhman (migo@homemail.com\*(--Perl\-GPL/arch\-perl\*(--devel).
.PP
Enno Cramer (uebergeek@web.de\-\-2003/arch\-perl\*(--devel).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For more information, see Arch::SharedCache.