Arch::SharedIndex(3pm)					User Contributed Perl Documentation				    Arch::SharedIndex(3pm)

NAME

       Arch::SharedIndex - a synchronized data structure (map) for IPC

SYNOPSIS

	   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
", $map->keys;
	   printf "New users: %s
", $map->grep(sub { $_[1] == $time });
	   printf "Login time of migo: %s
", $map->fetch('migo');

	   $map->update(sub { $_[1] + 10 }, sub { $_[1] == $time });
	   $map->store(migo => $time);
	   $map->delete('bob');

	   printf "Logged users with times: (%s)
", join(", ", $map->hash);

DESCRIPTION

       Arch::SharedIndex provides a key-value map that can be shared and accessed safely by multiple processes.

METHODS

       The following methods are available:

       new, encode_value, decode_value, store_value, fetch_value, delete_value, store, fetch, delete, fetch_store, keys, values, hash, list, grep,
       filter, update, query_index_list.

       new options
	   Create a new index object.  option is a hash of parameters.

	   file
	       The path of the index file, used to store data.	Must not be omitted.

	   can_create
	       Whether the index file is automatically created.  Defaults to 1.

	   max_size
	       Maximum number of entries in the index.	Defaults to 0 (no limit).

	   expiration
	       Timeout in seconds after which unused entries are removed.  Defaults to 0 (don't expire entries)

	   time_renewal
	       Whether fetching values resets the entry expiration timeout.  Defaults to 1 if max_size is set, 0 otherwise.

	   perl_data
	       Whether non-scalar perl data can be stored.  If true, values are encoded using Data::Dumper.

	   perl_data_indent
	       Indent value for Data::Dumper when perl_data is set.  Defaults to 0.

	   perl_data_pair
	       Pair value for Data::Dumper when perl_data is set.  Defaults to "=>".

       encode_value ref
	   Encode the value referenced by ref in a string representation.  The encoding is done in place.

       decode_value ref
	   Decode a value encoded with encode_value from its string representation.  The decoding is done in place.

       store_value key token value
	   Store a value for the given key and token.  Create a new token if none is given.  Returns the (new) token.  Sub-classes should
	   implement this method.

       fetch_value key token
	   Fetch the value stored for the given key and token.	Sub-classes should implement this method.

       delete_value key token
	   Delete a value stored for the given key and value.  Sub-classes should implement this method.

       store kvp
	   Store a set of key-value pairs.  kvp may either be a reference to a hash or array, or list of keys and values.

       fetch keys
	   Fetch values stored for a list of keys. keys may either be an array reference, or a list of keys.

       delete keys
	   Delete values stored for a list of keys.  keys may either be an array reference, or a list of keys.

       fetch_store mapfunc keys
	   This is an optimized (fetch or store) in a single step.  Fetch values stored for keys, just like fetch, but store values for the
	   missing keys in the process.  keys may be an array reference or a list of keys.  mapfunc will be called once for every key in keys that
	   has no associated value, with the key as its only argument.	Its return value will be stored for that key.

       keys
	   Returns a list of all valid keys.  In scalar context, returns an array reference.

	   Keys are returned in no particular order, but values will return values in matching order if the index has not been changed between
	   calls.

       values
	   Returns a list of all stored values.  In scalar context, returns an array reference.

	   Values are returned in no particular order, but keys will return values in matching order if the index has not been changed between
	   calls.

       hash
	   Returns the stored keys and values as a perl hash.  In scalar context, returns hash reference.

       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.

       grep predicate
	   Returns a list of keys for which predicate returns a true value.  predicate is called once for every key, with the key and the stored
	   value as its first and second argument.

       filter predicate
	   Deletes every entry for which predicate returns a true value.  predicate is called once for every key, with the key and the stored
	   value asi its first and second argument.

       update mapfunc predicate
	   Updates the value for every key for which predicate returns a true value with the return value from mapfunc.  Both predicate and
	   mapfunc are called with the key and the stored values as their first and second argument.

       update_index_list code
	   Synchronize access and call code with a reference to a list of pairs, each containing the key and token, for every stored value.

	   Used internally by store, fetch, delete, fetch_store, keys, values, hash, list, grep, filter and update.

BUGS

       Awaiting for your reports.

AUTHORS

       Mikhael Goikhman (migo@homemail.com--Perl-GPL/arch-perl--devel).

       Enno Cramer (uebergeek@web.de--2003/arch-perl--devel).

SEE ALSO

       For more information, see Arch::SharedCache.

perl v5.10.1							    2005-09-17						    Arch::SharedIndex(3pm)