NAME

Hash::SharedMem::Handle - handle for efficient shared mutable hash

SYNOPSIS

        use Hash::SharedMem::Handle;

        $shash = Hash::SharedMem::Handle->open($filename, "rwc");

        if($shash->is_readable) { ...
        if($shash->is_writable) { ...
        $mode = $shash->mode;

        if($shash->getd($key)) { ...
        $value = $shash->get($key);
        $shash->set($key, $newvalue);
        $oldvalue = $shash->gset($key, $newvalue);
        if($shash->cset($key, $chkvalue, $newvalue)) { ...

        $snap_shash = $shash->snapshot;
        if($shash->is_snapshot) { ...

        tie %shash, "Hash::SharedMem::Handle", $shash;
        tie %shash, "Hash::SharedMem::Handle", $filename, "rwc";

        if(exists($shash{$key})) { ...
        $value = $shash{$key};
        $shash{$key} = $newvalue;
        $oldvalue = delete($shash{$key});

DESCRIPTION

An object of this class is a handle referring to a memory-mapped shared hash object of the kind described in Hash::SharedMem. It can be passed to the functions of that module, or the same operations can be performed by calling the methods described below. Uses of the function and method interfaces may be intermixed arbitrarily; they are completely equivalent in function. They are not equivalent in performance, however, with the method interface being somewhat slower.

This class also supplies a tied-hash interface to shared hashes. As seen through the tied interface, the values in a shared hash can only be octet (Latin-1) strings. The tied interface is much slower than the function and method interfaces.

CONSTRUCTOR

Hash::SharedMem::Handle->open(FILENAME, MODE)

Opens and return a handle referring to a shared hash object, or dies if the shared hash can't be opened as specified. See "shash_open" in Hash::SharedMem for details.

METHODS

$shash->is_readable

$shash->is_writable

$shash->mode

$shash->getd(KEY)

$shash->get(KEY)

$shash->set(KEY, NEWVALUE)

$shash->gset(KEY, NEWVALUE)

$shash->cset(KEY, CHKVALUE, NEWVALUE)

$shash->snapshot

$shash->is_snapshot

These methods are each equivalent to the corresponding "shash_"-prefixed function in Hash::SharedMem. See that document for details.

TIE CONSTRUCTORS

tie(VARIABLE, "Hash::SharedMem::Handle", SHASH)

VARIABLE must be a hash variable, and SHASH must be a handle referring to a shared hash object. The call binds the variable to the shared hash, so that the variable provides a view of the shared hash that resembles an ordinary Perl hash. The shared hash handle is returned.

tie(VARIABLE, "Hash::SharedMem::Handle", FILENAME, MODE)

VARIABLE must be a hash variable. The call opens a handle referring to a shared hash object, as described in "shash_open" in Hash::SharedMem, and binds the variable to the shared hash, so that the variable provides a view of the shared hash that resembles an ordinary Perl hash. The shared hash handle is returned.

TIED OPERATORS

exists($SHASH{KEY})

Returns a truth value indicating whether the specified key is currently present in the shared hash.

$SHASH{KEY}

Returns the value currently referenced by the specified key in the shared hash, or undef if the key is absent.

$SHASH{KEY} = NEWVALUE

Modifies the shared hash so that the specified key henceforth references the specified value. The new value must be a string.

delete($SHASH{KEY})

Modifies the shared hash so that the specified key is henceforth absent, and returns the value that the key previously referenced, or undef if the key was already absent. This swap is performed atomically.

%SHASH = LIST

Setting the entire contents of the shared hash (throwing away the previous contents) is not supported.

each(%SHASH)

keys(%SHASH)

values(%SHASH)

%SHASH

Iteration over, or enumeration of, the shared hash's contents is not supported.

scalar(%SHASH)

Checking whether the shared hash is occupied is not supported.

BUGS

Due to details of the Perl implementation, this object-oriented interface to the shared hash mechanism is somewhat slower than the function interface, and the tied interface is much slower. The functions in Hash::SharedMem are the recommended interface.

SEE ALSO

Hash::SharedMem

AUTHOR

Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT

Copyright (C) 2014 PhotoBox Ltd

LICENSE

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.