---
name: "Arch::SharedIndex"
section: "3pm"
platform: "linux"
package: "libarch-perl"
version: "0.5.2-2"
release: "Debian 11 (Bullseye)"
platforms: ["linux"]
url: "https://new.carta.tech/Arch::SharedIndex"
---

# Arch::SharedIndex(3pm)

a synchronized data structure (map) for IPC

## 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\n", $map->keys;
    printf "New users: %s\n", $map->grep(sub { $_[1] == $time });
    printf "Login time of migo: %s\n", $map->fetch('migo');
    $map->update(sub { $_[1] + 10 }, sub { $_[1] == $time });
    $map->store(migo => $time);
    $map->delete('bob');
    printf "Logged users with times: (%s)\n", 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.