shm

Fiber-safe, cross-process shared-memory primitives for Crystal.

shm maps a POSIX shared-memory segment (shm_open/mmap) and layers a readers-writer lock over it that coordinates both fibers within a process (a local Sync::RWLock) and separate processes (a futex-backed cross-process lock). The cross-process lock detects and recovers from a peer that died while holding a lock, using PID plus start-time liveness so a recycled PID never masks a dead owner.

Two views sit on top of a segment: Region for a single typed value, and Buffer for raw bytes with an IO streaming interface.

Features

• Two views — Region(T) for a single typed value, Buffer for raw bytes with a streaming IO API.
• Fiber- and process-safe — a local Sync::RWLock pairs with a futex-backed CrossLock in one place.
• Crash recovery — a peer that dies mid-write is detected and reaped; readers/writers can repair the torn payload instead of corrupting silently.
• Type-stamped segments — a segment remembers the size and identity of its type; reopening it as a mismatched type raises LayoutError.
• Zero-copy access — reads and writes go straight to the mapped payload.

Requirements

Linux only. The recovery path reads /proc/<pid>/stat and the lock uses the futex syscall directly.

• Crystal >= 1.0.0

Installation

Add the dependency to your shard.yml:

dependencies:
  shm:
    github: shpeckman/shm
    version: ~> 1.0.0

Then run:

shards install

Quick start

require "shm"

@[Extern]
struct Counter
  property n : Int64

  def initialize
    @n = 0_i64
  end
end

SHM::Region(Counter).create("/demo", destroy: true) do |region|
  region.set(Counter.new)
  SHM.update(region) { |c| c.n += 1 }
  region.get.n # => 1
end

Usage

Segments

A segment is a named region of shared memory. The name is a POSIX shared-memory object name; a leading / is added if you omit one, so "counter" and "/counter" refer to the same segment.

.create makes a new segment and fails if it already exists, .open attaches to an existing segment and fails if it is missing, and .open_or_create attaches if present and otherwise creates.

Every value type stored in a Region must have a well-defined C memory layout, so it must be an @[Extern] struct or a primitive. A segment created for one type is stamped with that type's size and identity; opening it as a differently-sized type raises LayoutError instead of silently corrupting.

Only the process that created a segment should destroy it. Segment#close detaches the current handle, and Segment#unlink removes the segment name so it is freed once every handle closes.

Regions

# Producer process
region = SHM::Region(Counter).create("/counter")
region.set(Counter.new)

# Any process
region = SHM::Region(Counter).open("/counter")
region.update { |c| c.n += 1 }
region.get.n

# Conditional update — return nil to abandon the write
region.try_update { |c| c.n < 100 ? Counter.new.tap { |x| x.n = c.n + 1 } : nil }

# Direct pointer access under a write lock
region.with_ptr { |ptr| ptr.value.n += 1 }

Buffers

SHM::Buffer.create("/log", 4096) do |buf|
  buf.set("hello shared world")
  buf.string       # => "hello shared world"

  # Streaming IO
  buf.open_write { |io| io.puts("line one") }
  buf.each_line { |line| puts line }
end

Crash recovery

If a process dies while holding the write lock, the payload may be half-written. The next process to take the lock detects the dead owner, reclaims the lock, and marks the segment inconsistent, so the next read or write raises InconsistentError unless recovery was requested.

begin
  region.write { |ptr| ptr.value.n += 1 }
rescue SHM::InconsistentError
  region.repair { |ptr| ptr.value = Counter.new }
end

Pass recover: true to run a block on the torn payload directly instead of raising, then call mark_consistent once the payload is sound again.

---

API Reference

module SHM

Top-level namespace and entry point.

Constants

VERSION = "1.0.0"

Macros

• update(region, recover = false, &block) — reads the value out of region, yields it to the one-parameter block, and writes the block's mutation back, all under a single write lock. Pass recover: true to run against a torn payload after an owner death instead of raising.

---

class SHM::Region(T)

Reference → SHM::Region(T) · includes SHM::Locked

A view over a segment holding a single typed value T. T must have a well-defined C memory layout — an @[Extern] struct or a primitive.

Class methods

Constructors

• .new(segment : Segment) — wraps an already-opened Segment.

Instance methods

---

class SHM::Buffer

Reference → SHM::Buffer · includes SHM::Locked

A view over a segment holding raw bytes, with block-scoped accessors and an IO streaming interface.

Class / constructor methods

Instance methods

---

module SHM::Locked

The locking protocol shared by the segment views, Region and Buffer.

Each view pairs a process-local Sync::RWLock (fiber safety) over a CrossLock (process safety). This module owns that pairing and the owner-death guard, so the recovery contract lives in exactly one place. Block-scoped critical sections go through #guarded_read/#guarded_write; the manual-lifetime streaming paths go through #acquire_read/#acquire_write, which leave both locks held and return a release proc.

Including types must set @local : Sync::RWLock and @cross : CrossLock in their own initializer.

---

struct SHM::CrossLock

Struct → SHM::CrossLock

The futex-backed cross-process readers-writer lock. Detects a dead owner by polling and reaps it via PID/start-time liveness.

Constants

RECOVERY_POLL_NS = 50000000_i64
RECOVERY_POLLS   = 4

---

module SHM::Liveness

PID and start-time liveness checks. Reads /proc/<pid>/stat without yielding to the event loop, so it is safe on the recovery path.

---

class SHM::Segment

Reference → SHM::Segment

The mapped POSIX shared-memory segment: the mmap'd region, its header, and the payload.

---

module SHM::Stream

The streaming IO implementation layered over a segment.

SHM::Stream::Base (abstract, IO → Base) — owns close semantics: on #close it runs on_close, releases the cross lock, and calls the local-release proc if present. Provides #closed?.

SHM::Stream::Reader (Base → Reader) — a read-only IO over the payload, bounded by content length.

SHM::Stream::Writer (Base → Writer) — a write-only IO over the payload, bounded by capacity. truncate: true (default) resets content on open.

---

Errors

All errors inherit from SHM::Error (Exception → SHM::Error), which also provides .from_errno(message : String) : Error for wrapping failed syscalls.

---

Development

git clone https://github.com/shpeckman/shm
cd shm
shards install
crystal spec

Contributing

1. Fork it (https://github.com/shpeckman/shm/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

License

MIT

Contributors

• shpeckman — creator and maintainer