xchan.rb 0.19.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a87a4e61f65ec4df37ecc2b09efd3d9abd4d39e57ac936db27e43ace4e99818d
-  data.tar.gz: 1ac4be7c20abcdee66a441088e1a7bf67b92b96f63b16b3401227bb978afa6de
+  metadata.gz: e8936112cb188471884a6fa66ee0db2b61d5229ac75acb8953c78e5b76587bc8
+  data.tar.gz: e76eb21f0f7f2a11e465ee3d4834b3abd48b54269949ee3623e2b2c2bdc1a17c
 SHA512:
-  metadata.gz: fc46a04ae48123fbf24371bd3438013cfcb070e353993811d10b4ea9d8b63628b577bed465d441fab1d964a0dab4ec9a2040e293c59272faa6c2081819788383
-  data.tar.gz: 267dd70488de1b49c345c49a87c5f28a7bdf0713c20fdeeba2efbef13e2d114960dc021e3b1ec77df90ad3c1189772e3075dff3ce0f2ebfac27b727acc4a56a8
+  metadata.gz: d6ff8db4154e29a41a41b3878a93355ab3ce8092112f76f7fa4a61042a9747138f9a270217decf0e39cc5a9890f7ce5f34ebaa8a93e74aeb68d1cf5b0d470a09
+  data.tar.gz: bbe432d09de33e607b7940005a1d29ee0c1de6c14d3a2a56105c5fa26e32ea81a6327a87a6e520163f34836ffe820296674bf29a46c72cc45c603872500f090f

data/README.md

@@ -1,9 +1,25 @@
 ## About
 
-xchan.rb is an easy to use library for InterProcess
-Communication (IPC). The library provides a channel
-that can help facilitate communication between Ruby
+xchan.rb is an easy to use library for InterProcess Communication (IPC).
+
+The library provides a channel that can help facilitate communication between Ruby
 processes who have a parent <=> child relationship.
+A channel lock is provided by
+[lockf(3)](https://man.freebsd.org/cgi/man.cgi?query=lockf&sektion=3) and a temporary, unlinked file to protect against race conditions
+that can happen when multiple processes access the same channel
+at the same time.
+
+## Features
+
+* Minimalist Inter-Process Communication (IPC) for parent <=> child processes.
+* Channel-based communication.
+* Support for multiple serializers (`:marshal`, `:json`, `:yaml`) and raw string communication (`:pure`).
+* Blocking (`#send`, `#recv`) and non-blocking (`#send_nonblock`, `#recv_nonblock`) operations.
+* Built-in file-based locking ([lockf(3)](https://man.freebsd.org/cgi/man.cgi?query=lockf&sektion=3)) to prevent race conditions.
+* Option to use a null lock for scenarios where locking is not needed.
+* Access to underlying UNIX sockets for fine-grained control over socket options.
+* Mac, BSD, and Linux support.
+* Good docs.
 
 ## Examples
 
@@ -26,7 +42,7 @@ require "xchan"
 # Marshal as the serializer
 ch = xchan(:marshal)
 Process.wait fork { ch.send(5) }
-print "#{ch.recv} + 7 = 12", "\n"
+puts "#{ch.recv} + 7 = 12"
 ch.close
 
 ##
@@ -40,7 +56,7 @@ ch.close
 The `ch.recv` method performs a blocking read. A read
 can block when a lock is held by another process, or
 when a read from
-[Chan::UNIXSocket#r](https://0x1eef.github,io/x/xchan.rb/Chan/UNIXSocket.html#r-instance_method)
+[Chan::UNIXSocket#r](https://0x1eef.github.io/x/xchan.rb/Chan/UNIXSocket.html#r-instance_method)
 blocks. The example performs a read that blocks until
 the parent process writes to the channel:
 
@@ -53,7 +69,7 @@ fork do
   print "Received a random number (child process): ", ch.recv, "\n"
 end
 sleep(1)
-print "Send a random number (from parent process)", "\n"
+puts "Send a random number (from parent process)"
 ch.send(rand(21))
 ch.close
 Process.wait
@@ -69,7 +85,7 @@ The non-blocking counterpart to `#recv` is `#recv_nonblock`.
 The `#recv_nonblock` method raises `Chan::WaitLockable` when
 a read blocks because of a lock held by another process, and
 the method raises `Chan::WaitReadable` when a read from
-[Chan::UNIXSocket#r](https://0x1eef.github,io/x/xchan.rb/Chan/UNIXSocket.html#r-instance_method)
+[Chan::UNIXSocket#r](https://0x1eef.github.io/x/xchan.rb/Chan/UNIXSocket.html#r-instance_method)
 blocks:
 
 ```ruby
@@ -79,11 +95,12 @@ require "xchan"
 def read(ch)
   ch.recv_nonblock
 rescue Chan::WaitReadable
-  print "Wait 1 second for channel to be readable", "\n"
+  puts "Wait 1 second for channel to be readable"
   ch.wait_readable(1)
   retry
 rescue Chan::WaitLockable
-  sleep 0.01
+  puts "Wait 1 second for channel to be lockable"
+  ch.wait_lockable(1)
   retry
 end
 trap("SIGINT") { exit(1) }
@@ -102,7 +119,7 @@ read(xchan(:marshal))
 The `ch.send` method performs a blocking write.
 A write can block when a lock is held by another
 process, or when a write to
-[Chan::UNIXSocket#w](https://0x1eef.github,io/x/xchan.rb/Chan/UNIXSocket.html#w-instance_method)
+[Chan::UNIXSocket#w](https://0x1eef.github.io/x/xchan.rb/Chan/UNIXSocket.html#w-instance_method)
 blocks. The example fills the send buffer:
 
 ```ruby
@@ -123,7 +140,7 @@ The non-blocking counterpart to `#send` is
 `Chan::WaitLockable` when a write blocks because of
 a lock held by another process, and the method raises
 `Chan::WaitWritable` when a write to
-[Chan::UNIXSocket#w](https://0x1eef.github,io/x/xchan.rb/Chan/UNIXSocket.html#w-instance_method)
+[Chan::UNIXSocket#w](https://0x1eef.github.io/x/xchan.rb/Chan/UNIXSocket.html#w-instance_method)
 blocks. The example frees space on the send buffer:
 
 ```ruby
@@ -133,11 +150,11 @@ require "xchan"
 def send_nonblock(ch, buf)
   ch.send_nonblock(buf)
 rescue Chan::WaitWritable
-  print "Blocked - free send buffer", "\n"
+  puts "Blocked - free send buffer"
   ch.recv
   retry
 rescue Chan::WaitLockable
-  sleep 0.01
+  ch.wait_lockable
   retry
 end
 
@@ -166,6 +183,9 @@ processes:
 #!/usr/bin/env ruby
 require "xchan"
 
+##
+# 'lock: :file' is added just for the example
+# It is the default behavior, and not necessary
 ch = xchan(:marshal, lock: :file)
 5.times.map do
   fork do
@@ -179,7 +199,7 @@ end.each { Process.wait(_1) }
 The null lock is the same as using no lock at all. The null lock is
 implemented as a collection of no-op operations. The null lock is
 implemented in the
-[Chan::NullLock](https://0x1eef.github,io/x/xchan.rb/Chan/NullLock.html)
+[Chan::NullLock](https://0x1eef.github.io/x/xchan.rb/Chan/NullLock.html)
 class, and in certain situations, it can be useful and preferable
 to using a file lock:
 
@@ -200,9 +220,9 @@ Process.wait
 
 A channel has one socket for read operations and another
 socket for write operations.
-[Chan::UNIXSocket#r](https://0x1eef.github,io/x/xchan.rb/Chan/UNIXSocket.html#r-instance_method)
+[Chan::UNIXSocket#r](https://0x1eef.github.io/x/xchan.rb/Chan/UNIXSocket.html#r-instance_method)
 returns the socket used for read operations, and
-[Chan::UNIXSocket#w](https://0x1eef.github,io/x/xchan.rb/Chan/UNIXSocket.html#w-instance_method)
+[Chan::UNIXSocket#w](https://0x1eef.github.io/x/xchan.rb/Chan/UNIXSocket.html#w-instance_method)
 returns the socket used for write operations:
 
 ```ruby

data/lib/xchan/bytes.rb

@@ -7,7 +7,6 @@
 # increases in size, and when an object is read from
 # a channel, the collection decreases in size.
 class Chan::Bytes
-  require "json"
   require_relative "counter"
 
   ##
@@ -15,7 +14,8 @@ class Chan::Bytes
   #  Directory where temporary files are stored
   # @return [Chan::Bytes]
   def initialize(tmpdir)
-    @io = Chan.temporary_file(%w[bytes .json], tmpdir:)
+    @io = Chan.temporary_file(%w[bytes .bin], tmpdir:)
+    @io.binmode
     @io.sync = true
     write(@io, [])
   end
@@ -79,15 +79,17 @@ class Chan::Bytes
   end
 
   def write(io, bytes)
+    io.rewind
     io.truncate(0)
-    io.write(serialize(bytes)).tap { io.rewind }
+    io.write(serialize(bytes))
+    io.rewind
   end
 
   def serialize(bytes)
-    JSON.dump(bytes)
+    bytes.pack("Q>*")
   end
 
   def deserialize(bytes)
-    JSON.parse(bytes)
+    bytes.unpack("Q>*")
   end
 end

data/lib/xchan/counter.rb

@@ -5,57 +5,72 @@
 # for the number of written and received bytes on a
 # given channel.
 class Chan::Counter
-  require "json"
-
   ##
   # @param [String] tmpdir
   #  Directory where temporary files are stored
   # @return [Chan::Counter]
   def initialize(tmpdir)
-    @io = Chan.temporary_file(%w[counter .json], tmpdir:)
-    write(@io, {"bytes_read" => 0, "bytes_written" => 0})
+    @io = Chan.temporary_file(%w[counter .bin], tmpdir:)
+    @io.binmode
+    @io.sync = true
+    write(@io, 0, 0)
   end
 
   ##
   # @return [Integer]
   #  Returns the number of bytes written to a channel
   def bytes_written
-    read(@io).fetch("bytes_written")
+    _, bytes = read(@io)
+    bytes
   end
 
   ##
   # @return [Integer]
   #  Returns the number of bytes read from a channel
   def bytes_read
-    read(@io).fetch("bytes_read")
+    bytes, _ = read(@io)
+    bytes
   end
 
   ##
-  # @param [Hash] new_stat
+  # @param [Integer] bytes_read
+  #  Number of bytes read to increment the counter by
+  # @param [Integer] bytes_written
+  #  Number of bytes written to increment the counter by
   # @return [void]
   # @private
-  def increment!(new_stat)
-    stat = read(@io)
-    new_stat.each { stat[_1.to_s] += _2 }
-    write(@io, stat)
+  def increment!(bytes_read: 0, bytes_written: 0)
+    bytes_in, bytes_out = read(@io)
+    bytes_in += bytes_read
+    bytes_out += bytes_written
+    write(@io, bytes_in, bytes_out)
+  end
+
+  ##
+  # Close the counter
+  # @return [void]
+  def close
+    @io.close
   end
 
   private
 
-  def write(io, o)
+  def write(io, bytes_read, bytes_written)
+    io.rewind
     io.truncate(0)
-    io.write(serialize(o)).tap { io.rewind }
+    io.write(serialize(bytes_read, bytes_written))
+    io.rewind
   end
 
   def read(io)
     deserialize(io.read).tap { io.rewind }
   end
 
-  def serialize(bytes)
-    JSON.dump(bytes)
+  def serialize(bytes_read, bytes_written)
+    [bytes_read, bytes_written].pack("Q>Q>")
   end
 
-  def deserialize(bytes)
-    JSON.parse(bytes)
+  def deserialize(payload)
+    payload.unpack("Q>Q>")
   end
 end

data/lib/xchan/null_lock.rb

@@ -36,9 +36,9 @@ class Chan::NullLock
   end
 
   ##
-  # @return [void]
-  #  This method always returns false
-  def self.locked?
-    false
+  # @return [true]
+  #  Always returns true
+  def self.lockable?
+    true
   end
 end

data/lib/xchan/unix_socket.rb

@@ -45,6 +45,7 @@ class Chan::UNIXSocket
     @bytes = Chan::Bytes.new(tmpdir)
     @counter = Chan::Counter.new(tmpdir)
     @lock = Chan.locks[lock]&.call(tmpdir) || lock
+    @mutex = Mutex.new
   end
 
   ##
@@ -61,8 +62,8 @@ class Chan::UNIXSocket
   # @return [void]
   def close
     @lock.lock
-    raise IOError, "channel is closed" if closed?
-    [@r, @w, @bytes, @lock].each(&:close)
+    raise IOError, "closed channel" if closed?
+    [@r, @w, @bytes, @counter, @lock].each(&:close)
   rescue IOError => ex
     @lock.release
     raise(ex)
@@ -81,7 +82,11 @@ class Chan::UNIXSocket
   #  Returns the number of bytes written to the channel
   def send(object)
     send_nonblock(object)
-  rescue Chan::WaitWritable, Chan::WaitLockable
+  rescue Chan::WaitWritable
+    wait_writable
+    retry
+  rescue Chan::WaitLockable
+    wait_lockable
     retry
   end
   alias_method :write, :send
@@ -99,17 +104,19 @@ class Chan::UNIXSocket
   # @return [Integer, nil]
   #  Returns the number of bytes written to the channel
   def send_nonblock(object)
-    @lock.lock_nonblock
-    raise IOError, "channel closed" if closed?
-    len = @w.write_nonblock(serialize(object))
-    @bytes.push(len)
-    @counter.increment!(bytes_written: len)
-    len.tap { @lock.release }
-  rescue IOError, IO::WaitWritable, Errno::ENOBUFS => ex
-    @lock.release
-    raise Chan::WaitWritable, ex.message
-  rescue Errno::EWOULDBLOCK => ex
-    raise Chan::WaitLockable, ex.message
+    @mutex.synchronize do
+      @lock.lock_nonblock
+      raise IOError, "channel closed" if closed?
+      len = @w.write_nonblock(serialize(object))
+      @bytes.push(len)
+      @counter.increment!(bytes_written: len)
+      len.tap { @lock.release }
+    rescue IOError, IO::WaitWritable, Errno::ENOBUFS => ex
+      @lock.release
+      raise Chan::WaitWritable, ex.message
+    rescue Errno::EWOULDBLOCK => ex
+      raise Chan::WaitLockable, ex.message
+    end
   end
   alias_method :write_nonblock, :send_nonblock
 
@@ -131,6 +138,7 @@ class Chan::UNIXSocket
     wait_readable
     retry
   rescue Chan::WaitLockable
+    wait_lockable
     retry
   end
   alias_method :read, :recv
@@ -146,21 +154,23 @@ class Chan::UNIXSocket
   # @return [Object]
   #  Returns an object from the channel
   def recv_nonblock
-    @lock.lock_nonblock
-    raise IOError, "closed channel" if closed?
-    len = @bytes.shift
-    obj = deserialize(@r.read_nonblock(len.zero? ? 1 : len))
-    @counter.increment!(bytes_read: len)
-    obj.tap { @lock.release }
-  rescue IOError => ex
-    @lock.release
-    raise(ex)
-  rescue IO::WaitReadable => ex
-    @bytes.unshift(len)
-    @lock.release
-    raise Chan::WaitReadable, ex.message
-  rescue Errno::EAGAIN => ex
-    raise Chan::WaitLockable, ex.message
+    @mutex.synchronize do
+      @lock.lock_nonblock
+      raise IOError, "closed channel" if closed?
+      len = @bytes.shift
+      obj = deserialize(@r.read_nonblock(len.zero? ? 1 : len))
+      @counter.increment!(bytes_read: len)
+      obj.tap { @lock.release }
+    rescue IOError => ex
+      @lock.release
+      raise(ex)
+    rescue IO::WaitReadable => ex
+      @bytes.unshift(len)
+      @lock.release
+      raise Chan::WaitReadable, ex.message
+    rescue Errno::EAGAIN => ex
+      raise Chan::WaitLockable, ex.message
+    end
   end
   alias_method :read_nonblock, :recv_nonblock
 
@@ -222,22 +232,40 @@ class Chan::UNIXSocket
 
   ##
   # Waits for the channel to become readable
-  # @param [Float, Integer, nil] s
-  #  The number of seconds to wait. Waits indefinitely with no arguments.
+  # @param [Float, Integer, nil] timeout
+  #  The number of seconds to wait before timeout.
+  #  Waits indefinitely with no arguments
   # @return [Chan::UNIXSocket, nil]
   #  Returns self when the channel is readable, otherwise returns nil
-  def wait_readable(s = nil)
-    @r.wait_readable(s) and self
+  def wait_readable(timeout = nil)
+    @r.wait_readable(timeout) and self
   end
 
   ##
   # Waits for the channel to become writable
-  # @param [Float, Integer, nil] s
-  #  The number of seconds to wait. Waits indefinitely with no arguments.
+  # @param [Float, Integer, nil] timeout
+  #  The number of seconds to wait before timeout.
+  #  Waits indefinitely with no arguments
   # @return [Chan::UNIXSocket, nil]
   #  Returns self when the channel is writable, otherwise returns nil
-  def wait_writable(s = nil)
-    @w.wait_writable(s) and self
+  def wait_writable(timeout = nil)
+    @w.wait_writable(timeout) and self
+  end
+
+  ##
+  # Waits for the channel to become lockable
+  # @param [Float, Integer, nil] timeout
+  #  The number of seconds to wait before timeout.
+  #  Waits indefinitely with no arguments
+  # @return [Chan::UNIXSocket, nil]
+  #  Returns self when the channel is lockable, otherwise returns nil
+  def wait_lockable(timeout = nil)
+    start = (timeout ? gettime : nil)
+    loop do
+      break(nil) if start && (gettime - start) >= timeout
+      break(self) if @lock.lockable?
+      sleep 0.01
+    end
   end
 
   ##
@@ -259,4 +287,8 @@ class Chan::UNIXSocket
   def deserialize(str)
     @s.load(str)
   end
+
+  def gettime
+    Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
 end

data/lib/xchan/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Chan
-  VERSION = "0.19.0"
+  VERSION = "0.21.0"
 end

data/lib/xchan.rb

@@ -65,7 +65,7 @@ module Chan
   def self.locks
     {
       null: lambda { |_tmpdir| Chan::NullLock },
-      file: lambda { |tmpdir| Lock::File.new Chan.temporary_file(%w[xchan lock], tmpdir:) }
+      file: lambda { |tmpdir| Lockf.new Chan.temporary_file(%w[xchan lock], tmpdir:) }
     }
   end
 end

data/test/thread_safety_test.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "xchan"
+require "test/unit"
+
+class ThreadSafetyTest < Test::Unit::TestCase
+  ##
+  # Without a Mutex wrapping the critical sections in send_nonblock and
+  # recv_nonblock, lockf(3) record locks do not provide thread safety
+  # because they are per-process (PID-based). Two threads sharing the
+  # same channel can both acquire the lock simultaneously, causing the
+  # @bytes and @counter tempfiles to be read and written concurrently.
+  #
+  # This test reproduces the race by having one thread write many
+  # messages while another reads them. A mismatch between the byte
+  # length recorded by @bytes.push and the actual data read from the
+  # socket triggers Marshal.load errors.
+  def test_concurrent_send_and_recv
+    ch = xchan(:marshal)
+    n = 1000
+    writer = Thread.new do
+      n.times { ch.send("hello") }
+    end
+    reader = Thread.new do
+      count = 0
+      n.times do
+        ch.recv
+        count += 1
+      end
+      count
+    end
+    count = [writer, reader].map(&:value).last
+    assert_equal n, count
+  ensure
+    ch.close unless ch.closed?
+  end
+
+  def test_concurrent_send_nonblock_and_recv_nonblock
+    ch = xchan(:marshal)
+    n = 1000
+    writer = Thread.new do
+      n.times { ch.send("world") }
+    end
+    reader = Thread.new do
+      count = 0
+      n.times do
+        ch.recv
+        count += 1
+      end
+      count
+    end
+    count = [writer, reader].map(&:value).last
+    assert_equal n, count
+  ensure
+    ch.close unless ch.closed?
+  end
+end

data/test/xchan_test.rb

@@ -223,3 +223,42 @@ class Chan::TemporaryFileTest < Chan::Test
     @file ||= Chan.temporary_file %w[foobar .txt]
   end
 end
+
+##
+# Chan::UNIXSocket#wait_lockable
+class Chan::WaitLockableTest < Chan::Test
+  def test_wait_lockable_on_lockable_channel
+    assert_instance_of Chan::UNIXSocket, ch.wait_lockable
+  end
+
+  def test_wait_lockable_on_locked_channel
+    aux = xchan(:pure)
+    lock! do
+      Process.wait fork { aux.send ch.wait_lockable(0.1).class.to_s }
+    end
+    assert_equal "NilClass", aux.recv
+  ensure
+    aux.close
+  end
+
+  def test_wait_lockable_on_null_lock
+    ch = xchan(:pure, lock: :null)
+    assert_instance_of Chan::UNIXSocket, ch.wait_lockable
+  ensure
+    ch.close
+  end
+
+  private
+
+  def lock!
+    ch.instance_variable_get(:@lock).lock
+    yield
+  ensure
+    release!
+  end
+
+  def release!
+    ch.instance_variable_get(:@lock).release
+  end
+end
+

data/xchan.rb.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.summary = "An easy to use InterProcess Communication (IPC) library"
   gem.description = gem.summary
-  gem.add_runtime_dependency "lockf.rb", "~> 2.1"
+  gem.add_runtime_dependency "lockf.rb", "~> 3.0"
   gem.add_development_dependency "test-unit", "~> 3.5.7"
   gem.add_development_dependency "yard", "~> 0.9"
   gem.add_development_dependency "kramdown", "~> 2.5"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: xchan.rb
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.21.0
 platform: ruby
 authors:
 - '0x1eef'
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-09 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lockf.rb
@@ -16,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: test-unit
   requirement: !ruby/object:Gem::Requirement
@@ -147,13 +146,13 @@ files:
 - share/xchan.rb/examples/write_operations/2_nonblocking_write.rb
 - test/readme_test.rb
 - test/setup.rb
+- test/thread_safety_test.rb
 - test/xchan_test.rb
 - xchan.rb.gemspec
 homepage: https://github.com/0x1eef/xchan.rb#readme
 licenses:
 - 0BSD
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -168,8 +167,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.23
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: An easy to use InterProcess Communication (IPC) library
 test_files: []