Provided by: libhash-sharedmem-perl_0.005-1_amd64 
NAME
Hash::SharedMem - efficient shared mutable hash
SYNOPSIS
use Hash::SharedMem qw(shash_referential_handle);
if(shash_referential_handle) { ...
use Hash::SharedMem qw(is_shash check_shash);
if(is_shash($arg)) { ...
check_shash($arg);
use Hash::SharedMem qw(shash_open);
$shash = shash_open($filename, "rwc");
use Hash::SharedMem qw(
shash_is_readable shash_is_writable shash_mode);
if(shash_is_readable($shash)) { ...
if(shash_is_writable($shash)) { ...
$mode = shash_mode($shash);
use Hash::SharedMem qw(
shash_exists shash_length shash_get
shash_set shash_gset shash_cset);
if(shash_exists($shash, $key)) { ...
$length = shash_length($shash, $key);
$value = shash_get($shash, $key);
shash_set($shash, $key, $newvalue);
$oldvalue = shash_gset($shash, $key, $newvalue);
if(shash_cset($shash, $key, $chkvalue, $newvalue)) { ...
use Hash::SharedMem qw(
shash_occupied shash_count shash_size
shash_key_min shash_key_max
shash_key_ge shash_key_gt shash_key_le shash_key_lt
shash_keys_array shash_keys_hash
shash_group_get_hash);
if(shash_occupied($shash)) { ...
$count = shash_count($shash);
$size = shash_size($shash);
$key = shash_key_min($shash);
$key = shash_key_max($shash);
$key = shash_key_ge($shash, $key);
$key = shash_key_gt($shash, $key);
$key = shash_key_le($shash, $key);
$key = shash_key_lt($shash, $key);
$keys = shash_keys_array($shash);
$keys = shash_keys_hash($shash);
$group = shash_group_get_hash($shash);
use Hash::SharedMem qw(shash_snapshot shash_is_snapshot);
$snap_shash = shash_snapshot($shash);
if(shash_is_snapshot($shash)) { ...
use Hash::SharedMem qw(shash_idle shash_tidy);
shash_idle($shash);
shash_tidy($shash);
use Hash::SharedMem qw(
shash_tally_get shash_tally_zero shash_tally_gzero);
$tally = shash_tally_get($shash);
shash_tally_zero($shash);
$tally = shash_tally_gzero($shash);
DESCRIPTION
This module provides a facility for efficiently sharing mutable data between processes on
one host. Data is organised as a key/value store, resembling a Perl hash. The keys and
values are restricted to octet (Latin-1) strings. Structured objects may be stored by
serialising them using a mechanism such as Sereal.
The data is represented in files that are mapped into each process's memory space, which
for interprocess communication amounts to the processes sharing memory. Processes are
never blocked waiting for each other. The use of files means that there is some
persistence, with the data continuing to exist when there are no processes with it mapped.
The data structure is optimised for the case where all the data fits into RAM. This
happens either via buffering of a disk-based filesystem, or as the normal operation of a
memory-backed filesystem, in either case as long as there isn't much swapping activity.
If RAM isn't large enough, such that the data has to reside mainly on disk and parts of it
have to be frequently reread from disk, speed will seriously suffer. The data structure
exhibits poor locality of reference, and is not designed to play nicely with filesystem
block sizes.
Consistency and synchronisation
A shared hash is held in regular files, grouped in a directory. At all times, the OS-
visible state of the files provides a consistent view of the hash's content, from which
read and write operations can proceed. It is no problem for a process using the shared
hash to crash; other processes, running concurrently or later, will be unimpeded in using
the shared hash.
It is mainly intended that the shared hash should be held on a memory-backed filesystem,
and will therefore only last as long as the machine stays up. However, it can use any
filesystem that supports mmap(2), including conventional disk filesystems such as ext2.
In this case, as long as the OS shuts down cleanly (synching all file writes to the
underlying disk), a consistent state of the shared hash will persist between boots, and
usage of the shared hash can continue after the OS boots again. Note that only the OS is
required to shut down cleanly; it still doesn't matter if user processes crash.
Because the OS is likely to reorder file writes when writing them to disk, the
instantaneous state of the shared hash's files on disk is generally not guaranteed to be
consistent. So if the OS crashes, upon reboot the files are liable to be in an
inconsistent state (corrupted).
Maintaining consistency across an OS crash is a feature likely to be added to this module
in the future. Durability of writes, for which that is a prerequisite, is another likely
future addition.
File permissions
To read normally from a shared hash requires read and search (execute) permission on the
shared hash directory and read permission on all the regular files in the directory. To
write normally requires read, write, and search permissions on the directory and read and
write permissions on all the regular files. For security purposes, some information about
shared hash content can be gleaned by anyone who has read or search permission on the
directory, and content can be modified by anyone who has search permission on the
directory and write permission on either the directory or any of the regular files.
The file permission bits on a shared hash are determined by the circumstances in which it
was created, specifically by the umask in effect at the point of creation. As shared hash
creation is unavoidably non-atomic, competing creation attempts can cause trouble, and the
resulting permissions are only guaranteed if all competing attempts at creation use the
same umask. After the shared hash is fully created, subsequently opening it with the
create flag set doesn't affect permissions.
The directory gets permissions "rwxrwxrwx" modified by the creation umask, and the regular
files in it get permissions "rw-rw-rw-" modified by the creation umask. All the regular
files that contain any part of the shared hash content will get the same permission bits.
This includes files created long after initial creation of the shared hash, which are
created as part of shared hash write operations; the umask in effect at the point of those
operations is insignificant.
File ownership and group assignment are not so controlled. An attempt is made to give all
files the same group assignment and ownership, determined by the creation of the shared
hash, but the ability to do so is limited by OS semantics. Typically, users other than
the superuser cannot affect ownership, and can only assign files to groups of which they
are members. Also, as with permission bits, competing creation attempts can make
ownerships and group assignments inconsistent, even if they are generally controllable.
Where they can't be freely set, each regular file gets whatever ownership and group
assignment arise naturally from the circumstances in which it was created. If multiple
users write to a single shared hash, it is to be expected that the constituent files will
end up having different owners. It is up to the user to ensure that the varying
ownerships combined with the consistent permission bits yield compatible permissions for
all intended users of the shared hash. Group-based permissions should work provided that
all writers are members of the relevant group.
Filesystem referential integrity
If the system calls openat(2) et al are supported by the kernel and the C library, then an
open shared hash handle contains an OS-supported first-class reference to the shared hash
to which it refers. (Specifically, it has a file descriptor referring to the shared hash
directory.) In this situation, the reference remains valid regardless of filename
changes. The shared hash can be renamed or moved arbitrarily, within the filesystem, or
the process can change its current directory or root directory, and the handle remains
valid.
If these modern system calls are not available, then an open shared hash handle cannot
contain a first-class reference to the shared hash directory. Instead it must repeatedly
refer to the directory by name. The name supplied to "shash_open" is resolved to an
absolute pathname, so the handle will continue to work if the process changes its current
directory. But any renaming of the shared hash, or the process changing its root
directory, will cause the handle to fail at the next operation that requires the use of
filenames. (This is unlikely to be the very next operation after the pathname becomes
invalid.) An attempt is made to ensure that the stored pathname is still correct each
time it is used, but there is unavoidably a race condition, whereby some very unluckily
timed renaming could cause an operation to be applied to the wrong directory.
The means by which shared hash handles reference their directories is indicated by the
constant "shash_referential_handle".
When a shared hash is being opened, if it already exists then the name passed to
"shash_open" is resolved just once to determine to what shared hash it refers. If the
modern system calls are supported, this yields perfectly clean name resolution semantics.
However, if a shared hash does not already exist, its creation cannot currently be so
perfectly clean. The name passed to "shash_open" must be resolved at least twice, once to
create the shared hash directory and once to acquire a reference to it (of whichever
type). There is unavoidably a race condition here.
File operations
Because a shared hash is encapsulated in a directory, rather than being a single non-
directory file, the ability to perform file operations on it is limited. Although it can
be renamed or moved, under POSIX semantics such a rename can't atomically replace any file
other than an empty directory. In particular, it can't atomically replace another shared
hash. It also can't be hard-linked to have multiple names. (However, a major use case
for link(2), non-overwriting renaming, can be achieved through rename(2) due to the
latter's limitations for directories.) Finally, it can't be unlinked. (Linking and
unlinking directories are possible for root on some systems, but cause undesirable
filesystem irregularities.)
A shared hash can be disposed of by applying "rm -r" to its directory. This is not
equivalent to unlink(2) ("rm") on a regular file, because it not only removes the object's
name but also disrupts its internal structure. If a process has an open handle referring
to the shared hash at the time of "rm -r", the use of the shared hash through that handle
is likely to fail, although probably not immediately. If a process is writing to the
shared hash at the time of "rm -r", there is a race condition that could prevent the
removal from completing. "rm -r" should therefore only be applied after all processes
have finished using the shared hash.
A shared hash can be copied by means of "cp -r" (not mere "cp"), "tar", or similar means.
It is safe to do this while processes have open handles referring to the shared hash, and
while processes are reading from it. However, as with most forms of database file, if a
process is writing to the shared hash then the file copier is liable to pick up an
inconsistent (corrupted) view of the shared hash. Copying should therefore only be
attempted at a time when no write operations are being performed. It is acceptable for
processes to have the shared hash open in write mode, provided that they do not actually
perform any write operation while the copy is being made.
A file-level copying operation applied to a shared hash is likely to result in a copy that
occupies much more filesystem space than the original. This occurs because most of the
time a large part of the main data file is a filesystem hole, not occupying any actual
storage. Some copying mechanisms (such as GNU "cp") can recognise this and avoid
allocating unnecessary storage for the copy, but others (such as GNU "tar") will blindly
fill space with a lot of zeroes. If the copy is subsequently used in shared hash write
operations, ultimately it will recover from this inefficient block allocation.
Forking
If a process is duplicated by fork(2) while it holds a shared hash handle, the handle is
duplicated with the rest of the process, so both resulting processes have handles
referring to the same underlying shared hash. Provided that the duplication did not
happen during a shared hash operation, both processes' handles will subsequently work
normally, and can be used independently.
Things are more difficult if a fork(2) happens while a shared hash operation is in
progress. This should not normally be possible to achieve from Perl code: arbitrary Perl
code should not run during the critical part of an operation. If a shared hash operator
is given a tied variable as a parameter, the magic method call for access to that
parameter occurs before the critical part, so a fork in that method is safe. If a signal
is received during a shared hash operation, any signal handler installed in %SIG will be
deferred until the operation is complete, so a fork in such a signal handler is also safe.
A problematic fork(2) should only be achievable by XS code.
If a fork(2) does happen during the critical part of a shared hash operation, the two
resulting handles are liable to interfere if the operation is resumed in both processes.
In this case, it is safe for at most one process (which may be either of them) to resume
the operation. The other process must neither resume the operation in progress nor make
any further use of the handle. It is safe for the non-resuming process to chain a new
program with execve(2), to terminate with _exit(2), or generally to make use of the C
library before doing either of those. Attempting to run Perl code would be unwise.
On platforms lacking a native fork(2), the Perl function fork actually creates a Perl
thread. In that case the behaviour should be similar to that seen with a real fork(2), as
described in the next section.
Threads
This module can be used in multiple Perl threads simultaneously. The module may be loaded
by multiple threads separately, or from Perl 5.8.9 onwards may be loaded by a thread that
spawns new threads. (Prior to Perl 5.8.9, limitations of the threading system mean that
module data can't be correctly cloned upon thread spawning. Any but the most trivial
cases of thread spawning with this module loaded will crash the interpreter. The rest of
this section only applies to Perls that fully support cloning.)
If a thread is spawned while the parent thread has an open shared hash handle, the handle
is duplicated, so that both resulting threads have handles referring to the same
underlying shared hash. Provided that the duplication did not happen during a shared hash
operation, both threads' handles will subsequently work normally, and can be used
independently.
Tainting
If taint mode is enabled, taintedness is relevant to some operations on shared hashes.
Shared hash handles mostly behave like regular file handles for tainting purposes. Where
the following description says that a result is "not tainted", that means it does not get
the taint flag set merely by virtue of the operation performed; it may still be marked as
tainted if other tainted data is part of the same expression, due to Perl's conservative
taint tracking.
The classification functions are happy to operate on tainted arguments. Their results are
not tainted.
When opening a shared hash, if the shared hash filename or the mode string is tainted then
it is not permitted to open for writing or with the possibility of creating. It is
permitted to open non-creatingly for reading regardless of taint status. Of course, any
kind of opening is permitted in an untainted expression.
A shared hash handle per se is never tainted.
The results of the mode checking functions are not tainted.
The content of a shared hash is always treated as tainted. It is permitted to write
tainted data to a shared hash. The data operations all accept tainted arguments. When
reading from a shared hash, the keys existing in the hash and the values referenced by
them are always tainted, but an absent item is treated as clean. So where a data
operation returns a key or value from the shared hash, the result will be tainted if it is
a string, but "undef" representing an absent item will not be tainted. The count of keys
existing in the hash, size of the hash, and the length of an existing value are also
tainted, being derived from tainted content. However, the truth values returned by some
operations are not tainted, even if they are derived entirely from tainted data.
CONSTANTS
shash_referential_handle
Truth value indicating whether each shared hash handle contains a first-class
reference to the shared hash to which it refers. See "Filesystem referential
integrity" above for discussion of the significance of this.
FUNCTIONS
The SHASH parameter that most of these functions take must be a handle referring to a
shared hash object.
Classification
is_shash(ARG)
Returns a truth value indicating whether ARG is a handle referring to a shared hash
object.
check_shash(ARG)
Checks whether ARG is a handle referring to a shared hash object. Returns normally if
it is, or "die"s if it is not.
Opening
shash_open(FILENAME, MODE)
Opens and returns a handle referring to a shared hash object, or "die"s if the shared
hash can't be opened as specified. FILENAME must refer to the directory that
encapsulates the shared hash.
If the filename string contains non-ASCII characters, then the filename actually used
consists of the octets of the internal encoding of the string, which does not
necessarily match the ostensible characters of the string. This gives inconsistent
behaviour for the same character sequence represented in the two different ways that
Perl uses internally. This is consistent with the treatment of filenames in Perl's
built-in operators such as open; see "When Unicode Does Not Happen" in perlunicode.
This may change in future versions of Perl (beyond 5.26).
MODE is a string controlling how the shared hash will be used. It can contain these
characters:
r The shared hash is to be readable. If this is not specified then read operations
through the handle will be denied. Beware that at the system-call level the files
are necessarily opened readably. Thus read permission on the files is required
even if one will only be writing.
w The shared hash is to be writable. If this is not specified then write operations
through the handle will be denied. This flag also determines in what mode the
files are opened at the system-call level, so write permission on the files
operates as expected.
c The shared hash will be created if it does not already exist. The permission bits
on the shared hash will be controlled by the creating process's umask. If this
flag is not specified then the shared hash must already exist.
e The shared hash must not already exist. If this is not specified and the shared
hash already exists then it will be opened normally. This flag is meant to be
used with c; it means that a successful open implies that this process, rather
than any other, is the one that created the shared hash.
When a shared hash is created, some of its constituent files will be opened in
read/write mode even if read-only mode was requested. Shared hash creation is not an
atomic process, so if a creation attempt is interrupted it may leave a half-created
shared hash behind. This does not prevent a subsequent creation attempt on the same
shared hash from succeeding: creation will continue from whatever stage it had
reached. Likewise, multiple simultaneous creation attempts may each do part of the
job. This can result in ownerships and permissions being inconsistent; see "File
permissions" above.
Regardless of the combination of efforts leading to the creation of a shared hash,
completion of the process is atomic. Non-creating open attempts will either report
that there is no shared hash or open the created shared hash. Exactly one creation
attempt will be judged to have created the shared hash, and this is detectable through
the e flag.
Mode checking
shash_is_readable(SHASH)
Returns a truth value indicating whether the shared hash can be read from through this
handle.
shash_is_writable(SHASH)
Returns a truth value indicating whether the shared hash can be written to through
this handle.
shash_mode(SHASH)
Returns a string in which characters indicate the mode of this handle. It matches the
form of the MODE parameter to "shash_open", but mode flags that are only relevant
during the opening process (c and e) are not included. The returned string can
therefore contain these characters:
r The shared hash can be read from through this handle.
w The shared hash can be written to through this handle.
Single-key data operations
For all of these functions, the key of interest (KEY parameter) can be any octet (Latin-1)
string, and values (VALUE parameters and some return values) can be any octet string or
"undef". The "undef" value represents the absence of a key from the hash; there is no
present-but-undefined state. Strings containing non-octets (Unicode characters above
U+FF) and items other than strings cannot be used as keys or values. If a dualvar (scalar
with independent string and numeric values) is supplied, only its string value will be
used.
shash_exists(SHASH, KEY)
Returns a truth value indicating whether the specified key currently references a
defined value in the shared hash.
shash_getd(SHASH, KEY)
Deprecated alias for "shash_exists".
shash_length(SHASH, KEY)
Returns the length (in octets) of the value currently referenced by the specified key
in the shared hash, or "undef" if the key is absent.
shash_get(SHASH, KEY)
Returns the value currently referenced by the specified key in the shared hash.
shash_set(SHASH, KEY, NEWVALUE)
Modifies the shared hash so that the specified key henceforth references the specified
value.
shash_gset(SHASH, KEY, NEWVALUE)
Modifies the shared hash so that the specified key henceforth references the value
NEWVALUE, and returns the value that the key previously referenced. This swap is
performed atomically.
shash_cset(SHASH, KEY, CHKVALUE, NEWVALUE)
Examines the value currently referenced by the specified key in the shared hash. If
it is identical to CHKVALUE, the function modifies the shared hash so that the
specified key henceforth references the value NEWVALUE, and returns true. If the
current value is not identical to CHKVALUE, the function leaves it unmodified and
returns false. This conditional modification is performed atomically.
This function can be used as a core on which to build arbitrarily complex kinds of
atomic operation (on a single key). For example, an atomic increment can be
implemented as
do {
$ov = shash_get($shash, $key);
$nv = $ov + 1;
} until shash_cset($shash, $key, $ov, $nv);
Whole-hash data operations
shash_occupied(SHASH)
Returns a truth value indicating whether there are currently any items in the shared
hash.
shash_count(SHASH)
Returns the number of items that are currently in the shared hash.
shash_size(SHASH)
Returns the approximate size (in octets) of the entire content of the shared hash.
The size of a hash is not a well-defined quantity, so the return value of this
function should be interpreted with care. It aims specifically to indicate how much
space is required in a shared hash data file to represent this content. It is
affected by details of the file format (which may differ between shared hashes on one
system) and by accidents of how the content is laid out in a particular shared hash.
Calling this function twice on identical content will not necessarily produce
identical results. The details of the size estimation may also change in the future.
Although this function computes size specifically with respect to the file format used
by this module, this function does not directly indicate the amount of space occupied
by a shared hash. There is some non-content overhead, and, more importantly, the
process by which content is modified requires space to store multiple versions of the
content. It is normal for the amount of space actually occupied to fluctuate over the
cycle of data file rewriting. If "shash_tidy" is being used appropriately, the space
occupied can be expected to vary up to a little over five times the size of the
nominal content, and if "shash_tidy" is not used then the normal maximum will be more
than ten times the content size. Occasional spikes above these levels can be expected
in any case, and fixed overheads make these multipliers inapplicable if the content is
very small.
shash_key_min(SHASH)
Returns the lexicographically least of the keys that are currently in the shared hash,
or "undef" if there are none.
shash_key_max(SHASH)
Returns the lexicographically greatest of the keys that are currently in the shared
hash, or "undef" if there are none.
shash_key_ge(SHASH, KEY)
Returns the least of the keys currently in the shared hash that are lexicographically
no less than the specified key, or "undef" if there are none.
shash_key_gt(SHASH, KEY)
Returns the least of the keys currently in the shared hash that are lexicographically
greater than the specified key, or "undef" if there are none.
shash_key_le(SHASH, KEY)
Returns the greatest of the keys currently in the shared hash that are
lexicographically no greater than the specified key, or "undef" if there are none.
shash_key_lt(SHASH, KEY)
Returns the greatest of the keys currently in the shared hash that are
lexicographically less than the specified key, or "undef" if there are none.
shash_keys_array(SHASH)
Returns a reference to a plain array containing all the keys currently in the shared
hash in lexicographical order. The array and the key scalars in it are unwritable.
shash_keys_hash(SHASH)
Returns a reference to a plain hash in which the keys are all the keys currently in
the shared hash and all the values are "undef". The value scalars are unwritable.
Writability of the hash is not guaranteed: currently in practice it is writable, but
this may change in the future.
shash_group_get_hash(SHASH)
Returns a reference to a plain hash representing the entire current content of the
shared hash. The value scalars are unwritable. Writability of the hash is not
guaranteed: currently in practice it is writable, but this may change in the future.
Snapshots
shash_snapshot(SHASH)
Returns a shared hash handle that encapsulates the current content of the shared hash.
The entire state of the shared hash is captured atomically, and the returned handle
can be used to perform arbitrarily many read operations on that state: it will never
reflect later modifications to the shared hash. The snapshot handle cannot be used
for writing.
shash_is_snapshot(SHASH)
Returns a truth value indicating whether this handle refers to a snapshot (as opposed
to a live shared hash).
Maintenance
shash_idle(SHASH)
Puts the shared hash handle into a state where it occupies less resources, at the
expense of making the next operation through the handle more expensive. This doesn't
change the visible behaviour of the handle, and doesn't affect the state of the shared
hash itself at all. The invisible operations performed by this function may vary
between versions of this module.
This function should be called when the handle is going to be unused for a lengthy
period. For example, if a long-running daemon uses a shared hash in brief bursts once
an hour, it should idle its handle at the end of each burst of activity.
Currently the effect of this operation is to discard the handle's memory mapping of
the shared hash data file. The next operation has to reestablish the mapping. The
benefit of discarding the mapping is that periodically the data file has to be
replaced with a new one, but the old data file continues to exist as long as some
process has it mapped. A process that is actively using the shared hash will quickly
notice that the data file has been replaced and will unmap the old one. A process
with a handle that it's not using, however, could keep the old data file in existence,
occupying storage, long after it has no further use. A handle that has been put into
the idle state won't perpetuate the existence of an obsolete data file.
shash_tidy(SHASH)
Rearranges the storage of the shared hash if it seems useful to do so, to avoid
tidying work having to be performed by other processes. This doesn't change the
visible content of the shared hash, but the handle must be open for writing, and this
counts as a write operation for purposes concerned with the state of the underlying
files. The invisible operations performed by this function may vary between versions
of this module.
This function should be called in circumstances where it is acceptable to incur some
delay for this maintenance work to complete. For example, it could be called
periodically by a cron job. Essentially, calling this function signals that this is a
convenient time at which (and process in which) to perform maintenance.
If this maintenance work is not carried out by means of this function, then ultimately
it will be performed anyway, but less predictably and possibly less conveniently.
Eventually it will become necessary to perform maintenance in order to continue using
the shared hash, at which point the next process that attempts to write to it will
carry out the work and incur the cost. The shared hash will still work properly in
that case, but the unlucky writer will experience a disproportionately large delay in
the completion of its write operation. This could well be a problem if the shared
hash is large.
Event counters
shash_tally_get(SHASH)
Returns a reference to a hash of counts of events that have occurred with this shared
hash handle. These counts may be of interest for profiling and debugging purposes,
but should not be relied upon for semantic purposes. The event types may vary between
versions of this module. Few of the event types make sense in terms of the API
supplied by this module: most of them are internal implementation details.
Events are counted separately for each handle. The events counted are associated
specifically with the handle, rather than with the shared hash as a whole. Generally,
an idle handle will accumulate no events, even if the shared hash to which it refers
is active. The event counters start at zero when a handle is opened, and can be reset
to zero by "shash_tally_zero" or "shash_tally_gzero".
In the returned hash, each key identifies a type of event, and the corresponding value
is (unless wrapped) the number of times events of that type have occurred on the
handle since the counters were last zeroed. Currently the event counters are held in
fixed-size variables and can wrap, so if event counts might get as high as 2^64 then
they can't be relied upon to be accurate. Wrapping will not occur at less than 2^64;
in other respects, wrapping behaviour may change in the future.
The event types that are currently counted are:
string_read
Parse an octet string representation in a shared hash data file.
string_write
Write an octet string representation into a shared hash data file.
bnode_read
Parse a B-tree node representation in a shared hash data file.
bnode_write
Write a B-tree node representation into a shared hash data file.
key_compare
Compare two strings as shared hash keys.
root_change_attempt
Attempt to replace the root pointer in a shared hash data file. This may be done
to change the content of the shared hash, or as part of the process of switching
to a new data file.
root_change_success
Succeed in replacing the root pointer in a shared hash data file. An attempt will
fail if another process changed the root pointer during the operation that
required this process to change the root pointer.
file_change_attempt
Attempt to replace the data file in a shared hash. This is necessary from time to
time as data files fill up.
file_change_success
Succeed in replacing the data file in a shared hash. An attempt will fail if
another process replaced the data file while this process was initialising its new
one.
data_read_op
Perform a high-level data operation that purely reads from the shared hash:
"shash_exists", "shash_length", "shash_get", "shash_occupied", "shash_count",
"shash_size", "shash_key_min", "shash_key_max", "shash_key_ge", "shash_key_gt",
"shash_key_le", "shash_key_lt", "shash_keys_array", "shash_keys_hash", or
"shash_group_get_hash".
data_write_op
Perform a high-level data operation that writes, or at least may write, to the
shared hash: "shash_set", "shash_gset", or "shash_cset".
The value scalars in the returned hash are unwritable. Writability of the hash is not
guaranteed: currently in practice it is writable, but this may change in the future.
shash_tally_zero(SHASH)
Zero the event counters that can be read by "shash_tally_get".
shash_tally_gzero(SHASH)
Zero the event counters that can be read by "shash_tally_get", and return the values
the event counters previously had, in the same form as "shash_tally_get". This swap
is performed atomically.
BUGS
As explained for "shash_open", creation of a shared hash is not atomic. This is an
unavoidable consequence of the need for the shared hash to consist of multiple files in a
directory. Multi-party creation can result in the files having different permission bits;
to avoid this, all creators should use the same umask. Multiple users writing to a shared
hash can result in the files having different ownerships, so the permission bits must be
chosen to work appropriately with the chimeric ownership.
When calls to the functions supplied by this module are compiled down to custom ops (which
is attempted for performance reasons), the ability to deparse the resulting code with
B::Deparse is limited. Prior to Perl 5.13.7, deparsing will generate very incorrect code.
From Perl 5.13.7 onwards, deparsing should normally work, but will break if another module
defines a separate type of custom op that happens to have the same short name (though
these ops do not clash in other respects).
SEE ALSO
Hash::SharedMem::Handle, Sereal
AUTHOR
Andrew Main (Zefram) <zefram@fysh.org>
COPYRIGHT
Copyright (C) 2014, 2015 PhotoBox Ltd
Copyright (C) 2014, 2015, 2017 Andrew Main (Zefram) <zefram@fysh.org>
LICENSE
This module is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.