Provided by: libhash-sharedmem-perl_0.005-1build4_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.