xchan.rb 0.22.0 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d385aa7803c7861610c50348dec4108760bf2e0a21d36bd6a9402788ec56f62
-  data.tar.gz: 5292469bfb8a3cc8fb581d12ecde445cef46551000604b6e8d1c3b9ca96b2d93
+  metadata.gz: 181f4b9e1add150781f56e06f8d6d011a7474e55a501a6dce1713c975d52280d
+  data.tar.gz: 96b2056582afaa5f67f774c626a21cb9f8feadb09aea346150bcf685660e4dce
 SHA512:
-  metadata.gz: 10b83c2ad3e4861715b4348f0e4aa54e9f84377fa08acf3fb59caaccbb164909326ae1d527afaac5bed6a7401a4981942f75b767a370cb276553784ab0bce2b0
-  data.tar.gz: 990ed1ae55dba125d7f95a4e2d2477353b7bddeaa275149713fc2769fd36cea564ebe179567fe93924b1a37bc18f9e4c51ea7da1310587c34c94190975154fb8
+  metadata.gz: ab568cfe894198659cb45e72759dfa7daa95b290d647a1d633225e83093eb86f28b1a2c13e47b38d8626d2a275cbd80364416b15dbff050c6e2ba4ac36aff76c
+  data.tar.gz: 2a45fd7441fb2312d1fcfce43ad6f53fe60ad7c304a833667a22e7024c06a74ad21b6b235b1950835e71ddd49f43b03c958662ed92b746bc52829cead23db9da

data/README.md

@@ -1,4 +1,16 @@
-## About
+<p align="center">
+  <a href="https://r.uby.dev">
+    <img
+      src="rubydev.svg"
+      width="400"
+      height="200"
+      border="0"
+      alt="a r.uby.dev project"
+     >
+  </a>
+</p>
+
+> [r.uby.dev](https://r.uby.dev/llm) project.
 
 xchan.rb is an easy to use library for InterProcess Communication (IPC).
 
@@ -245,22 +257,12 @@ print "The maximum size of a single message is: ", sndbuf.int, " bytes.\n"
 # The maximum size of a single message is: 2048 bytes.
 ```
 
-## Documentation
-
-A complete API reference is available at
-[0x1eef.github.io/x/xchan.rb](https://0x1eef.github.io/x/xchan.rb/)
-
 ## Install
 
 xchan.rb can be installed via rubygems.org:
 
     gem install xchan.rb
 
-## Sources
-
-* [github.com/@0x1eef](https://github.com/0x1eef/xchan.rb#readme)
-* [gitlab.com/@0x1eef](https://gitlab.com/0x1eef/xchan.rb#about)
-
 ## License
 
 [BSD Zero Clause](https://choosealicense.com/licenses/0bsd/)

data/lib/xchan/lockf.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "fiddle/import"
+require "tempfile"
+
+##
+# @private
+# {Chan::Lockf Chan::Lockf} provides an object-oriented
+# [lockf(3)](https://man.freebsd.org/cgi/man.cgi?query=lockf&sektion=3)
+# interface backed by Fiddle from the standard library.
+# It supersedes the runtime dependency on the lockf.rb gem.
+class Chan::Lockf
+  module LibC
+    extend Fiddle::Importer
+    dlload Fiddle.dlopen(nil)
+    extern "int lockf(int fd, int cmd, int size)"
+  end
+  private_constant :LibC
+
+  F_ULOCK = 0x0
+  F_LOCK  = 0x1
+  F_TLOCK = 0x2
+  F_TEST  = 0x3
+
+  ##
+  # @return [<#fileno>]
+  #  Returns a file handle
+  attr_reader :file
+
+  ##
+  # @param [<#fileno>] file
+  # @param [Integer] size
+  # @return [Chan::Lockf]
+  #  Returns an instance of {Chan::Lockf Chan::Lockf}
+  def initialize(file, size = 0)
+    @file = file
+    @size = size
+  end
+
+  ##
+  # Acquire lock (blocking)
+  # @raise [SystemCallError]
+  #  Might raise a subclass of SystemCallError
+  # @return [Boolean]
+  #  Returns true when successful
+  def lock = try(F_LOCK)
+
+  ##
+  # Acquire lock (non-blocking)
+  # @raise [SystemCallError]
+  #  Might raise a subclass of SystemCallError
+  # @return [Boolean]
+  #  Returns true when successful
+  def lock_nonblock = try(F_TLOCK)
+
+  ##
+  # Release lock
+  # @raise [SystemCallError]
+  #  Might raise a subclass of SystemCallError
+  # @return [Boolean]
+  #  Returns true when successful
+  def release = try(F_ULOCK)
+
+  ##
+  # @return [Boolean]
+  #  Returns true when lock can be acquired
+  def lockable?
+    try(F_TEST)
+    true
+  rescue Errno::EACCES, Errno::EAGAIN, Errno::EWOULDBLOCK
+    false
+  end
+
+  ##
+  # Closes {Chan::Lockf#file Chan::Lockf#file}
+  # @return [void]
+  def close
+    @file.respond_to?(:close) ? @file.close : nil
+  end
+
+  private
+
+  def try(function, attempts: 3)
+    fileno = @file.respond_to?(:fileno) ? @file.fileno : @file
+    LibC.lockf(fileno, function, @size).zero? ||
+      raise(SystemCallError.new("lockf", Fiddle.last_error))
+  rescue Errno::EINTR => ex
+    attempts -= 1
+    (attempts.zero? ? raise(ex) : retry)
+  end
+end

data/lib/xchan/unix_socket.rb

@@ -4,7 +4,6 @@
 # An easy-to-use InterProcess Communication (IPC) library
 class Chan::UNIXSocket
   require "socket"
-  require "lockf"
   require_relative "bytes"
 
   ##
@@ -286,13 +285,35 @@ class Chan::UNIXSocket
   end
 
   ##
-  # Waits for the channel to become lockable
+  # Waits for the channel to become lockable, and takes the lock.
+  #
+  # Without a timeout the wait is `lockf(F_LOCK)`, which blocks in the
+  # kernel: the releaser wakes the waiter, so there is no interval to poll
+  # on - a lock held for microseconds is released with a wakeup rather than
+  # up to a tick of the loop below.
+  #
+  # **The caller comes back holding the lock**, which is what the retry in
+  # `send` and `recv` expects, and why the release paths are theirs. With a
+  # timeout the channel comes back as it was, because that loop gives up
+  # rather than acquires.
+  #
+  # The acquisition is no longer under `@mutex`, where it used to be - only
+  # the release is. With threads the two ends can therefore belong to
+  # different threads, which is a redundant retry at worst: `lockf` locks
+  # are held per process and give no intra-process exclusion at all, and
+  # every socket operation still happens under a successfully taken
+  # `F_TLOCK`.
+  #
   # @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)
+    if timeout.nil?
+      @lock.lock
+      return self
+    end
     start = (timeout ? gettime : nil)
     loop do
       break(nil) if start && (gettime - start) >= timeout

data/lib/xchan/version.rb

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

data/lib/xchan.rb

@@ -5,6 +5,7 @@ module Chan
   require_relative "xchan/unix_socket"
   require_relative "xchan/null_lock"
   require_relative "xchan/tempfile"
+  require_relative "xchan/lockf"
 
   WaitReadable = Class.new(IO::EAGAINWaitReadable)
   WaitWritable = Class.new(IO::EAGAINWaitWritable)
@@ -65,7 +66,7 @@ module Chan
   def self.locks
     {
       null: lambda { |_tmpdir| Chan::NullLock },
-      file: lambda { |tmpdir| Lockf.new Chan.temporary_file(%w[xchan lock], tmpdir:) }
+      file: lambda { |tmpdir| Chan::Lockf.new Chan.temporary_file(%w[xchan lock], tmpdir:) }
     }
   end
 end

data/test/xchan_test.rb

@@ -227,6 +227,8 @@ end
 ##
 # Chan::UNIXSocket#wait_lockable
 class Chan::WaitLockableTest < Chan::Test
+  include Timeout
+
   def test_wait_lockable_on_lockable_channel
     assert_instance_of Chan::UNIXSocket, ch.wait_lockable
   end
@@ -241,6 +243,27 @@ class Chan::WaitLockableTest < Chan::Test
     aux.close
   end
 
+  ##
+  # Without a timeout the wait is a blocking lock rather than a loop, so
+  # the answer can only arrive because the release woke the child - a lock
+  # that was never contended would answer either way, and a timeout would
+  # answer before the release at all.
+  def test_wait_lockable_without_a_timeout_on_a_locked_channel
+    aux = xchan(:pure)
+    lock! do
+      pid = fork { aux.send ch.wait_lockable.class.to_s }
+      ##
+      # Long enough that the child is inside the lock rather than between
+      # two calls, and then the release.
+      sleep 0.1
+      release!
+      Process.wait(pid)
+    end
+    assert_equal "Chan::UNIXSocket", timeout(5) { 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
@@ -261,4 +284,3 @@ class Chan::WaitLockableTest < Chan::Test
     ch.instance_variable_get(:@lock).release
   end
 end
-

data/xchan.rb.gemspec

@@ -18,7 +18,8 @@ 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", "~> 3.0"
+
+  gem.add_runtime_dependency "fiddle", "~> 1.1"
   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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xchan.rb
 version: !ruby/object:Gem::Version
-  version: 0.22.0
+  version: 0.24.0
 platform: ruby
 authors:
 - '0x1eef'
@@ -10,19 +10,19 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: lockf.rb
+  name: fiddle
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '1.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: test-unit
   requirement: !ruby/object:Gem::Requirement
@@ -132,6 +132,7 @@ files:
 - lib/xchan.rb
 - lib/xchan/bytes.rb
 - lib/xchan/counter.rb
+- lib/xchan/lockf.rb
 - lib/xchan/null_lock.rb
 - lib/xchan/tempfile.rb
 - lib/xchan/unix_socket.rb
@@ -167,7 +168,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.16
 specification_version: 4
 summary: An easy to use InterProcess Communication (IPC) library
 test_files: []