/ 
Data-Sync-Shared-0.08
/ Data::Sync::Shared

NAME

Data::Sync::Shared - Shared-memory synchronization primitives for Linux

SYNOPSIS

use Data::Sync::Shared;

# Semaphore -- bounded counter for resource limiting
my $sem = Data::Sync::Shared::Semaphore->new('/tmp/sem.shm', 4);
$sem->acquire;            # block until available
$sem->acquire(1.5);       # with timeout
$sem->try_acquire;        # non-blocking
$sem->acquire_n(3);       # acquire N permits atomically
$sem->release;
$sem->release(2);         # release N permits
my $n = $sem->drain;      # acquire all, return count
{
    my $g = $sem->acquire_guard;   # auto-release on scope exit
}

# Barrier -- N processes rendezvous
my $bar = Data::Sync::Shared::Barrier->new('/tmp/bar.shm', 3);
my $leader = $bar->wait;       # block until all 3 arrive
my $leader = $bar->wait(5.0);  # with timeout (-1=timeout)

# RWLock -- reader-writer lock
my $rw = Data::Sync::Shared::RWLock->new('/tmp/rw.shm');
$rw->rdlock;  $rw->rdunlock;
$rw->wrlock;  $rw->wrunlock;
$rw->try_rdlock;  $rw->try_wrlock;
$rw->downgrade;                # wrlock -> rdlock atomically
{
    my $g = $rw->wrlock_guard;  # auto-release on scope exit
}

# Condvar -- condition variable with built-in mutex
my $cv = Data::Sync::Shared::Condvar->new('/tmp/cv.shm');
$cv->lock;
$cv->try_lock;       # non-blocking
$cv->wait;           # atomically unlock + wait + re-lock
$cv->wait(2.0);      # with timeout
$cv->signal;         # wake one waiter
$cv->broadcast;      # wake all waiters
$cv->wait_while(sub { !$ready }, 5.0);  # predicate loop
$cv->unlock;

# Once -- one-time initialization gate
my $once = Data::Sync::Shared::Once->new('/tmp/once.shm');
if ($once->enter) {          # or enter($timeout)
    do_init();
    $once->done;
}

# All primitives support anonymous (fork-inherited) mode:
my $sem = Data::Sync::Shared::Semaphore->new(undef, 4);

# And memfd mode (fd-passable):
my $sem = Data::Sync::Shared::Semaphore->new_memfd("my_sem", 4);
my $fd = $sem->memfd;

DESCRIPTION

Data::Sync::Shared provides five cross-process synchronization primitives stored in file-backed shared memory (mmap(MAP_SHARED)), using Linux futex for efficient blocking.

Linux-only. Requires 64-bit Perl.

Primitives

Data::Sync::Shared::Semaphore - bounded counter

CAS-based counting semaphore. acquire decrements (blocks at 0), release increments (capped at max). Useful for cross-process resource limiting (connection pools, worker slots).

Data::Sync::Shared::Barrier - rendezvous point

N processes call wait; all block until the last one arrives, then all proceed. Returns true for one "leader" process. Generation counter tracks how many times the barrier has tripped.

Data::Sync::Shared::RWLock - reader-writer lock

Multiple concurrent readers or one exclusive writer. Readers use rdlock/rdunlock, writers use wrlock/wrunlock. Non-blocking try_rdlock/try_wrlock variants available.

Data::Sync::Shared::Condvar - condition variable

Includes a built-in mutex. lock/unlock protect the predicate. wait atomically releases the mutex and sleeps; on wakeup it re-acquires the mutex. signal wakes one waiter, broadcast wakes all.

Data::Sync::Shared::Once - one-time init gate

enter returns true for exactly one process (the initializer); all others block until done is called. If the initializer dies, waiters detect the stale PID and a new initializer is elected.

Features

  • File-backed mmap for cross-process sharing

  • Futex-based blocking (no busy-spin, no pthread)

  • PID-based stale lock recovery (dead process detection)

  • Anonymous and memfd modes

  • Timeouts on all blocking operations (except Condvar lock, which provides only a non-blocking try_lock)

  • eventfd integration for event-loop wakeup

Crash Safety

All primitives encode the holder's PID in the lock word. If a process dies while holding a lock, other processes detect the stale lock within 2 seconds via kill(pid, 0) and automatically recover.

Reader-slot exhaustion (slotless readers): dead-process recovery attributes a crashed lock holder's contribution through its reader-slot. The slot table holds 1024 entries (one per concurrent reader process). If more than that many reader processes share one mapping at once, a reader that cannot claim a slot proceeds "slotless" -- it still takes the read lock but leaves no per-process record. If such a slotless reader is then killed while holding the read lock, its share of the lock cannot be attributed to a dead process, so writer recovery cannot reclaim it and writers may block until the mapping is recreated. Reaching this needs more than 1024 concurrent reader processes on one mapping plus a crash in the brief read-lock window; the dead-process slot reclaim keeps the table from filling with stale entries, so in practice it is very unlikely.

Security

Backing files are created securely: the path is opened with O_CREAT|O_EXCL|O_NOFOLLOW (a pre-existing symlink at the path is rejected, and an existing regular file is attached rather than truncated) and the new file is created mode 0600 (owner-only) by default, so a segment is not world-writable unless you opt in. To share a file with a peer group, pass an explicit octal mode as the last argument to new():

my $sem = Data::Sync::Shared::Semaphore->new($path, $max, $initial, 0660);
my $rw  = Data::Sync::Shared::RWLock->new($path, 0660);

The mode is applied exactly via fchmod after an O_EXCL create, so the caller's umask does not narrow it. Offsets read back from an attached segment are bounds-checked before use, so a poisoned reader-slot offset cannot steer a pointer outside the mapping.

Guard Objects

All locking primitives provide scope-based guards that auto-release on scope exit (including exceptions):

{
    my $g = $rw->rdlock_guard;
    # ... read operations ...
}  # rdunlock called automatically

{
    my $g = $sem->acquire_guard(3);  # acquire 3 permits
    # ... use resource ...
}  # release(3) called automatically

{
    my $g = $cv->lock_guard;
    $cv->wait_while(sub { !$ready }, 5.0);
}  # unlock called automatically

PRIMITIVES

Data::Sync::Shared::Semaphore

Constructors

my $sem = Data::Sync::Shared::Semaphore->new($path, $max);
my $sem = Data::Sync::Shared::Semaphore->new($path, $max, $initial);
my $sem = Data::Sync::Shared::Semaphore->new(undef, $max);
my $sem = Data::Sync::Shared::Semaphore->new_memfd($name, $max);
my $sem = Data::Sync::Shared::Semaphore->new_memfd($name, $max, $initial);
my $sem = Data::Sync::Shared::Semaphore->new_from_fd($fd);

$max is the maximum permit count. $initial defaults to $max (fully available); set to 0 to start with no available permits.

Operations

my $ok  = $sem->acquire;              # block until available (infinite)
my $ok  = $sem->acquire($timeout);    # block with timeout (seconds)
my $ok  = $sem->try_acquire;          # non-blocking, false if unavailable
my $ok  = $sem->acquire_n($n);        # acquire N permits atomically
my $ok  = $sem->acquire_n($n, $timeout);
my $ok  = $sem->try_acquire_n($n);    # non-blocking N-permit acquire
$sem->release;                        # release one permit
$sem->release($n);                    # release N permits (clamped at max)
my $n   = $sem->drain;               # acquire all available, return count
my $val = $sem->value;                # current available count
my $max = $sem->max;                  # maximum permits

Guard

my $g = $sem->acquire_guard;          # acquire 1, release on scope exit
my $g = $sem->acquire_guard($n);      # acquire N
my $g = $sem->acquire_guard($n, $timeout);  # with timeout, undef on fail

Data::Sync::Shared::Barrier

Constructors

my $bar = Data::Sync::Shared::Barrier->new($path, $parties);
my $bar = Data::Sync::Shared::Barrier->new(undef, $parties);
my $bar = Data::Sync::Shared::Barrier->new_memfd($name, $parties);
my $bar = Data::Sync::Shared::Barrier->new_from_fd($fd);

$parties must be >= 2.

Operations

my $r = $bar->wait;           # block until all parties arrive
my $r = $bar->wait($timeout); # with timeout

Returns: 1 = leader (last to arrive), 0 = non-leader, -1 = timeout. A zero timeout (wait(0)) is a non-blocking probe: it returns -1 if the party would have to block, without breaking the barrier. On a positive timeout that actually elapses the barrier is permanently broken: wait returns -1 for the timing-out party and all other waiters, and every subsequent wait also returns -1 until reset is called. This matches POSIX pthread_barrier_t broken semantics.

my $gen = $bar->generation;    # how many times barrier has tripped
my $n   = $bar->arrived;       # currently arrived count
my $n   = $bar->parties;       # party count
$bar->is_broken;               # true if timeout broke the barrier
$bar->reset;                   # clear broken state + bump generation

Data::Sync::Shared::RWLock

Constructors

my $rw = Data::Sync::Shared::RWLock->new($path);
my $rw = Data::Sync::Shared::RWLock->new(undef);
my $rw = Data::Sync::Shared::RWLock->new_memfd($name);
my $rw = Data::Sync::Shared::RWLock->new_from_fd($fd);

Operations

$rw->rdlock;                   # block until read lock acquired
$rw->rdlock($timeout);         # with timeout (croaks on timeout)
$rw->wrlock;                   # block until write lock acquired
$rw->wrlock($timeout);         # with timeout (croaks on timeout)
my $ok = $rw->try_rdlock;      # non-blocking
my $ok = $rw->try_wrlock;      # non-blocking
my $ok = $rw->rdlock_timed($timeout);  # returns false on timeout
my $ok = $rw->wrlock_timed($timeout);  # returns false on timeout
$rw->rdunlock;
$rw->wrunlock;
$rw->downgrade;                # convert wrlock to rdlock atomically

Guards

my $g = $rw->rdlock_guard;             # rdunlock on scope exit
my $g = $rw->rdlock_guard($timeout);   # with timeout (croaks on fail)
my $g = $rw->wrlock_guard;
my $g = $rw->wrlock_guard($timeout);

Data::Sync::Shared::Condvar

Constructors

my $cv = Data::Sync::Shared::Condvar->new($path);
my $cv = Data::Sync::Shared::Condvar->new(undef);
my $cv = Data::Sync::Shared::Condvar->new_memfd($name);
my $cv = Data::Sync::Shared::Condvar->new_from_fd($fd);

Operations

$cv->lock;                     # acquire built-in mutex
$cv->unlock;                   # release built-in mutex
my $ok = $cv->try_lock;        # non-blocking

my $ok = $cv->wait;            # unlock, wait for signal, re-lock
my $ok = $cv->wait($timeout);  # with timeout
$cv->signal;                   # wake one waiter
$cv->broadcast;                # wake all waiters

my $ok = $cv->wait_while(\&pred);           # loop until pred returns false
my $ok = $cv->wait_while(\&pred, $timeout); # with timeout

wait must be called while holding the mutex. Returns 1 on signal/broadcast, 0 on timeout. The mutex is always re-acquired before wait returns.

wait_while calls wait in a loop until the predicate coderef returns false. Returns 1 if predicate became false, 0 on timeout.

Guard

my $g = $cv->lock_guard;       # unlock on scope exit

Data::Sync::Shared::Once

Constructors

my $once = Data::Sync::Shared::Once->new($path);
my $once = Data::Sync::Shared::Once->new(undef);
my $once = Data::Sync::Shared::Once->new_memfd($name);
my $once = Data::Sync::Shared::Once->new_from_fd($fd);

Operations

my $init = $once->enter;             # try + wait, infinite
my $init = $once->enter($timeout);   # with timeout
$once->done;                         # mark initialization complete
my $ok  = $once->is_done;            # check without blocking
$once->reset;                        # reset to uninitialized state

enter returns true for exactly one process (the initializer). All others block until done is called, then return false. With a $timeout, a waiter that times out before initialization completes also returns false: a false return means "not the initializer", not necessarily "initialization complete", so use is_done to tell a finished gate from a timed-out wait. If the initializer dies, stale PID detection elects a new one.

Common Methods

All primitives support:

my $p  = $obj->path;           # backing file path (undef if anon)
my $fd = $obj->memfd;          # memfd fd (-1 if file-backed/anon)
$obj->sync;                    # msync -- flush to disk
$obj->unlink;                  # remove backing file
Class->unlink($path);          # class method form
my $s  = $obj->stats;          # diagnostic hashref

Stats keys vary by type. All counters are approximate under concurrency.

Semaphore: value, max, waiters, mmap_size, acquires, releases, waits, timeouts, recoveries.

Barrier: parties, arrived, generation, waiters, mmap_size, waits, releases, timeouts.

RWLock: state ("unlocked", "read_locked", "write_locked"), readers, waiters, mmap_size, acquires, releases, recoveries.

Condvar: waiters, signals, mmap_size, acquires, releases, waits, timeouts, recoveries.

Once: state ("init", "running", "done"), is_done, waiters, mmap_size, acquires, releases, waits, timeouts, recoveries.

eventfd Integration

my $fd = $obj->eventfd;        # create eventfd, returns fd
$obj->eventfd_set($fd);        # use existing fd (e.g. from fork)
my $fd = $obj->fileno;         # current eventfd (-1 if none)
$obj->notify;                  # signal eventfd
my $n  = $obj->eventfd_consume;  # drain notification counter

Notification is opt-in. Use with EV or other event loops.

CRASH SAFETY

An interrupted create is recovered too. A creator killed after the backing file is sized but before its header is committed leaves a full-size, all-zero file. new re-initializes such a file automatically, but only when it is exactly the size the requested geometry needs, is owned by your effective uid, and is still entirely zero -- a file holding data is never re-initialized. If the creator got as far as writing part of the header, the file cannot be told apart from a corrupt one and new croaks with incomplete sync file left by an interrupted create; remove it and retry. A file left behind by an interrupted create never held data, so removing it is safe -- but a file whose header was corrupted after the fact reaches the same croak, so confirm it is an abandoned create before deleting anything you care about.

SECURITY

Backing files are created with mode 0600 (owner-only) by default, so only the creating user can open and attach them. To share a backing file across users, pass an explicit octal file mode such as 0660 as the last argument to new -- Semaphore->new($path, $max, $initial, $mode), Barrier->new($path, $parties, $mode), RWLock->new($path, $mode), Condvar->new($path, $mode) and Once->new($path, $mode). The mode is applied when the file is created, and when a file left behind by an interrupted create is re-initialized (see "CRASH SAFETY"); a file already in use keeps its own permissions. The file is opened with O_NOFOLLOW, so a symlink planted at the path is refused, and created with O_EXCL; the on-disk header is validated when the file is attached. Any process you grant write access to a shared mapping is trusted not to corrupt its contents while other processes are using it -- a primitive whose header is rewritten underneath it can leave waiters parked, which no amount of validation at attach time can undo.

SEE ALSO

Data::Buffer::Shared - typed shared array

Data::HashMap::Shared - concurrent hash table

Data::Queue::Shared - FIFO queue

Data::PubSub::Shared - publish-subscribe ring

Data::ReqRep::Shared - request-reply

Data::Pool::Shared - fixed-size object pool

Data::Stack::Shared - LIFO stack

Data::Deque::Shared - double-ended queue

Data::Log::Shared - append-only log (WAL)

Data::Heap::Shared - priority queue

Data::Graph::Shared - directed weighted graph

Data::BitSet::Shared - shared bitset (lock-free per-bit ops)

Data::RingBuffer::Shared - fixed-size overwriting ring buffer

AUTHOR

vividsnow

LICENSE

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