xchan.rb 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a87a4e61f65ec4df37ecc2b09efd3d9abd4d39e57ac936db27e43ace4e99818d
-  data.tar.gz: 1ac4be7c20abcdee66a441088e1a7bf67b92b96f63b16b3401227bb978afa6de
+  metadata.gz: 3faafc7100339e243744b476b137e7ee96591179027c862509006c60df6c7fe1
+  data.tar.gz: b7abc06e3a789f1f80a171e520c2cd3a64126c11e8bc01795bf90c4fcb5601bc
 SHA512:
-  metadata.gz: fc46a04ae48123fbf24371bd3438013cfcb070e353993811d10b4ea9d8b63628b577bed465d441fab1d964a0dab4ec9a2040e293c59272faa6c2081819788383
-  data.tar.gz: 267dd70488de1b49c345c49a87c5f28a7bdf0713c20fdeeba2efbef13e2d114960dc021e3b1ec77df90ad3c1189772e3075dff3ce0f2ebfac27b727acc4a56a8
+  metadata.gz: 1a14ea31ccd8ae96a56d4dfc667fe0141906a8d0123f3ba184e524ad07b4586b205501c870aec02f0af33d47d6ac8b788f023174afcddf8d6d1b90e853a3b40b
+  data.tar.gz: 98c9e23a2abd39852fdd315011c44385b6c57a1a9a000e0d9430580a36a3970091857482d7866c58c765015fce7cbb6523a9b3e411daa2c5520b79f911efaf05

data/README.md

@@ -1,9 +1,29 @@
+> **Designed for minimalism** <br>
+> One direct runtime dependency ([lockf.rb](https://github.com/0x1eef/lockf.rb#readme)) <br>
+> Zero indirect dependencies outside Ruby's standard library
+
 ## About
 
-xchan.rb is an easy to use library for InterProcess
-Communication (IPC). The library provides a channel
+xchan.rb is an easy to use, minimalist library for
+InterProcess Communication (IPC). The library provides a channel
 that can help facilitate communication between Ruby
 processes who have a parent &lt;=&gt; 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 &lt;=&gt; 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 +46,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 +60,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 +73,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 +89,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 +99,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 +123,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 +144,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 +154,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 +187,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 +203,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 +224,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

@@ -61,8 +61,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)
@@ -222,22 +222,36 @@ class Chan::UNIXSocket
 
   ##
   # Waits for the channel to become readable
-  # @param [Float, Integer, nil] s
+  # @param [Float, Integer, nil] timeout
   #  The number of seconds to wait. 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
+  # @param [Float, Integer, nil] timeout
   #  The number of seconds to wait. 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
+  # @return [Chan::UNIXSocket, 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 +273,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.20.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/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.20.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
@@ -153,7 +152,6 @@ homepage: https://github.com/0x1eef/xchan.rb#readme
 licenses:
 - 0BSD
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -168,8 +166,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: []