xchan.rb 0.18.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49c3ec314ad19f47d91dd30c854e94ad184fd70a0cb5ed7fd0139b506b295c6e
-  data.tar.gz: 1ba90eb765464330c3c6c35385c6ce6732f0bd95cd21e85be236576b7a0ba7c5
+  metadata.gz: 3faafc7100339e243744b476b137e7ee96591179027c862509006c60df6c7fe1
+  data.tar.gz: b7abc06e3a789f1f80a171e520c2cd3a64126c11e8bc01795bf90c4fcb5601bc
 SHA512:
-  metadata.gz: d29f66b50713d1277b25ad2900bbcd5a99ac1589a921e0b0a8ccd2028e534204ffc8a382b68f3ba48947aa2be8fda90843adda2fbdf133db3cf9fb230f2a5873
-  data.tar.gz: 218b603663b0cac0af9c6780e942c74decb096045e9a7eef14daf5c6644286bd2ee8e1969445260952425bfad08b4bd2fb588a6a1d1f3be0b45d0913337575b5
+  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
 
@@ -19,13 +39,14 @@ serializers are available by default: `xchan(:marshal)`,
 `xchan(:json)`, and `xchan(:yaml)`.
 
 ```ruby
+#!/usr/bin/env ruby
 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
 
 ##
@@ -39,11 +60,12 @@ 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:
 
 ```ruby
+#!/usr/bin/env ruby
 require "xchan"
 
 ch = xchan(:marshal)
@@ -51,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
@@ -67,20 +89,22 @@ 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
+#!/usr/bin/env ruby
 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) }
@@ -99,13 +123,14 @@ 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
+#!/usr/bin/env ruby
 require "xchan"
 
-ch = xchan(:marshal, sock_type: Socket::SOCK_STREAM)
+ch = xchan(:marshal, sock: Socket::SOCK_STREAM)
 sndbuf = ch.w.getsockopt(Socket::SOL_SOCKET, Socket::SO_SNDBUF)
 while ch.bytes_sent <= sndbuf.int
   ch.send(1)
@@ -119,24 +144,25 @@ 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
+#!/usr/bin/env ruby
 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
 
-ch = xchan(:marshal, sock_type: Socket::SOCK_STREAM)
+ch = xchan(:marshal, sock: Socket::SOCK_STREAM)
 sndbuf = ch.w.getsockopt(Socket::SOL_SOCKET, Socket::SO_SNDBUF)
 while ch.bytes_sent <= sndbuf.int
   send_nonblock(ch, 1)
@@ -146,18 +172,65 @@ end
 # Blocked - free send buffer
 ```
 
+### Lock
+
+#### File
+
+The default lock for a channel is a file lock. The locking mechanism is
+implemented with the
+[lockf](https://man.freebsd.org/cgi/man.cgi?query=lockf&apropos=0&sektion=3&manpath=FreeBSD+14.2-RELEASE+and+Ports&arch=default&format=html)
+function from the C standard library. Nothing special has to be done to
+use it, and it allows a channel to be safely accessed across multiple
+processes:
+
+```ruby
+#!/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
+    ch.send(5)
+  end
+end.each { Process.wait(_1) }
+```
+
+#### Null
+
+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)
+class, and in certain situations, it can be useful and preferable
+to using a file lock:
+
+```ruby
+#!/usr/bin/env ruby
+require "xchan"
+
+ch = xchan(:marshal, lock: :null)
+fork do
+  ch.send(5)
+end
+Process.wait
+```
+
 ### Socket
 
 #### Options
 
 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
+#!/usr/bin/env ruby
 require "xchan"
 ch = xchan(:marshal)
 
@@ -189,11 +262,11 @@ xchan.rb can be installed via rubygems.org:
 
 ## Sources
 
-* [GitHub](https://github.com/0x1eef/xchan.rb#readme)
-* [GitLab](https://gitlab.com/0x1eef/xchan.rb#about)
+* [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/)
 <br>
-See [LICENSE](./LICENSE)
+See [share/xchan.rb/LICENSE](./share/xchan.rb/LICENSE)

data/lib/xchan/bytes.rb

@@ -7,26 +7,23 @@
 # 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"
 
   ##
   # @param [String] tmpdir
   #  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
 
   ##
   # Adds a count to the start of the collection
-  #
   # @param [Integer] len
   #  The bytesize of an object
-  #
   # @return [void]
   def unshift(len)
     return 0 if len.nil? || len.zero?
@@ -38,10 +35,8 @@ class Chan::Bytes
 
   ##
   # Adds a count to the end of the collection
-  #
   # @param [Integer] len
   #  The bytesize of an object
-  #
   # @return [void]
   def push(len)
     return 0 if len.nil? || len.zero?
@@ -53,7 +48,6 @@ class Chan::Bytes
 
   ##
   # Removes a count from the start of the collection
-  #
   # @return [Integer]
   #  Returns the removed byte count
   def shift
@@ -73,7 +67,6 @@ class Chan::Bytes
 
   ##
   # Close the underlying IO
-  #
   # @return [void]
   def close
     @io.close
@@ -86,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,58 +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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+##
+# {Chan::NullLock Chan::NullLock} is a no-op lock that can be used
+# instead of the standard file lock when a lock is not needed
+#
+# @example
+#   ch = xchan(:marshal, lock: Chan::NullLock)
+#   ch.send([1,2,3])
+#   # ditto
+#   ch = xchan(:marshal, lock: :null)
+#   ch.send([1,2,3])
+class Chan::NullLock
+  ##
+  # @return [void]
+  #  This method is a no-op
+  def self.lock
+  end
+
+  ##
+  # @return [void]
+  #  This method is a no-op
+  def self.lock_nonblock
+  end
+
+  ##
+  # @return [void]
+  #  This method is a no-op
+  def self.release
+  end
+
+  ##
+  # @return [void]
+  #  This method is a no-op
+  def self.close
+  end
+
+  ##
+  # @return [true]
+  #  Always returns true
+  def self.lockable?
+    true
+  end
+end

data/lib/xchan/tempfile.rb

@@ -242,8 +242,8 @@ class Chan::Tempfile < DelegateClass(File)
     #   ensure
     #      f.close
     #   end
-    def self.open(*args, **kwargs)
-      tempfile = new(*args, **kwargs)
+    def self.open(*, **)
+      tempfile = new(*, **)
 
       if block_given?
         begin

data/lib/xchan/unix_socket.rb

@@ -29,24 +29,22 @@ class Chan::UNIXSocket
   #   ch.send([1,2,3])
   #   ch.recv.pop # => 3
   #   ch.close
-  #
-  # @param [Symbol, <#dump, #load>] s
+  # @param [Symbol, <#dump, #load>] serializer
   #  The name of a serializer
-  #
-  # @param [Integer] sock_type
+  # @param [Integer] sock
   #  Type of socket (eg `Socket::SOCK_STREAM`)
-  #
   # @param [String] tmpdir
   #  Directory where temporary files can be stored
-  #
+  # @param [Symbol, <Lock::File, Chan::NullLock>] lock
+  #  The name of a lock, or an instance of `Lock::File`, or {Chan::NullLock Chan::NullLock}
   # @return [Chan::UNIXSocket]
   #  Returns an instance of {Chan::UNIXSocket Chan::UNIXSocket}
-  def initialize(s, sock_type: Socket::SOCK_DGRAM, tmpdir: Dir.tmpdir)
-    @s = Chan.serializers[s]&.call || s
-    @r, @w = ::UNIXSocket.pair(sock_type)
+  def initialize(serializer, sock: Socket::SOCK_DGRAM, tmpdir: Dir.tmpdir, lock: :file)
+    @s = Chan.serializers[serializer]&.call || serializer
+    @r, @w = ::UNIXSocket.pair(sock)
     @bytes = Chan::Bytes.new(tmpdir)
     @counter = Chan::Counter.new(tmpdir)
-    @lockf = Lock::File.new Chan.temporary_file(%w[xchan .lock], tmpdir:)
+    @lock = Chan.locks[lock]&.call(tmpdir) || lock
   end
 
   ##
@@ -58,17 +56,15 @@ class Chan::UNIXSocket
 
   ##
   # Closes the channel
-  #
   # @raise [IOError]
   #  When the channel is closed
-  #
   # @return [void]
   def close
-    @lockf.lock
-    raise IOError, "channel is closed" if closed?
-    [@r, @w, @bytes, @lockf].each(&:close)
+    @lock.lock
+    raise IOError, "closed channel" if closed?
+    [@r, @w, @bytes, @counter, @lock].each(&:close)
   rescue IOError => ex
-    @lockf.release
+    @lock.release
     raise(ex)
   end
 
@@ -77,13 +73,10 @@ class Chan::UNIXSocket
 
   ##
   # Performs a blocking write
-  #
   # @param [Object] object
   #  An object
-  #
   # @raise [IOError]
   #  When the channel is closed
-  #
   # @return [Object]
   #  Returns the number of bytes written to the channel
   def send(object)
@@ -95,30 +88,25 @@ class Chan::UNIXSocket
 
   ##
   # Performs a non-blocking write
-  #
   # @param [Object] object
   #  An object
-  #
   # @raise [IOError]
   #  When the channel is closed
-  #
   # @raise [Chan::WaitWritable]
   #  When a write to {#w} blocks
-  #
   # @raise [Chan::WaitLockable]
   #  When a write blocks because of a lock held by another process
-  #
   # @return [Integer, nil]
   #  Returns the number of bytes written to the channel
   def send_nonblock(object)
-    @lockf.lock_nonblock
+    @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 { @lockf.release }
+    len.tap { @lock.release }
   rescue IOError, IO::WaitWritable, Errno::ENOBUFS => ex
-    @lockf.release
+    @lock.release
     raise Chan::WaitWritable, ex.message
   rescue Errno::EWOULDBLOCK => ex
     raise Chan::WaitLockable, ex.message
@@ -133,10 +121,8 @@ class Chan::UNIXSocket
 
   ##
   # Performs a blocking read
-  #
   # @raise [IOError]
   #  When the channel is closed
-  #
   # @return [Object]
   #  Returns an object from the channel
   def recv
@@ -151,31 +137,27 @@ class Chan::UNIXSocket
 
   ##
   # Performs a non-blocking read
-  #
   # @raise [IOError]
   #  When the channel is closed
-  #
   # @raise [Chan::WaitReadable]
   #  When a read from {#r} blocks
-  #
   # @raise [Chan::WaitLockable]
   #  When a read blocks because of a lock held by another process
-  #
   # @return [Object]
   #  Returns an object from the channel
   def recv_nonblock
-    @lockf.lock_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 { @lockf.release }
+    obj.tap { @lock.release }
   rescue IOError => ex
-    @lockf.release
+    @lock.release
     raise(ex)
   rescue IO::WaitReadable => ex
     @bytes.unshift(len)
-    @lockf.release
+    @lock.release
     raise Chan::WaitReadable, ex.message
   rescue Errno::EAGAIN => ex
     raise Chan::WaitLockable, ex.message
@@ -190,7 +172,6 @@ class Chan::UNIXSocket
   #   ch = xchan(:pure)
   #   1.upto(4) { ch.send(_1) }
   #   ch.to_a.last # => "4"
-  #
   # @return [Array<Object>]
   #  Returns the contents of the channel
   def to_a
@@ -241,26 +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
 
   ##
@@ -269,10 +260,10 @@ class Chan::UNIXSocket
   private
 
   def lock
-    @lockf.lock
+    @lock.lock
     yield
   ensure
-    @lockf.release
+    @lock.release
   end
 
   def serialize(obj)
@@ -282,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.18.0"
+  VERSION = "0.20.0"
 end

data/lib/xchan.rb

@@ -3,6 +3,7 @@
 module Chan
   require_relative "xchan/version"
   require_relative "xchan/unix_socket"
+  require_relative "xchan/null_lock"
   require_relative "xchan/tempfile"
 
   WaitReadable = Class.new(IO::EAGAINWaitReadable)
@@ -32,10 +33,8 @@ module Chan
   #
   # @param [String] basename
   #  Basename of the temporary file
-  #
   # @param [String] tmpdir
   #  Parent directory of the temporary file
-  #
   # @return [Chan::Tempfile]
   #  Returns an instance of {Chan::Tempfile Chan::Tempfile}
   def self.temporary_file(basename, tmpdir: Dir.tmpdir)
@@ -59,6 +58,16 @@ module Chan
       }
     }
   end
+
+  ##
+  # @return [Hash<Symbol, Proc>]
+  #  Returns the default locks
+  def self.locks
+    {
+      null: lambda { |_tmpdir| Chan::NullLock },
+      file: lambda { |tmpdir| Lockf.new Chan.temporary_file(%w[xchan lock], tmpdir:) }
+    }
+  end
 end
 
 module Kernel
@@ -68,10 +77,10 @@ module Kernel
   #   ch.send([1,2,3])
   #   ch.recv.pop # => 3
   #   ch.close
-  #
-  # @param s (see Chan::UNIXSocket#initialize)
-  # @param sock_type (see Chan::UNIXSocket#initialize)
+  # @param serializer (see Chan::UNIXSocket#initialize)
+  # @param sock (see Chan::UNIXSocket#initialize)
   # @param tmpdir (see Chan::UNIXSocket#initialize)
+  # @param lock (see Chan::UNIXSocket#initialize)
   # @return (see Chan::UNIXSocket#initialize)
   def xchan(s, ...)
     Chan::UNIXSocket.new(s, ...)

data/share/xchan.rb/examples/read_operations/1_blocking_read.rb

@@ -1,3 +1,4 @@
+#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require_relative "../setup"

data/share/xchan.rb/examples/read_operations/2_nonblocking_read.rb

@@ -1,3 +1,4 @@
+#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require_relative "../setup"

data/share/xchan.rb/examples/serialization/1_serializers.rb

@@ -1,8 +1,8 @@
+#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require_relative "../setup"
 require "xchan"
-require "xchan"
 
 ##
 # Marshal as the serializer

data/share/xchan.rb/examples/socket/{2_options.rb → 1_options.rb}

@@ -1,3 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
 require "xchan"
 ch = xchan(:marshal)
 

data/share/xchan.rb/examples/write_operations/1_blocking_write.rb

@@ -1,9 +1,10 @@
+#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require_relative "../setup"
 require "xchan"
 
-ch = xchan(:marshal, sock_type: Socket::SOCK_STREAM)
+ch = xchan(:marshal, sock: Socket::SOCK_STREAM)
 sndbuf = ch.w.getsockopt(Socket::SOL_SOCKET, Socket::SO_SNDBUF)
 while ch.bytes_sent <= sndbuf.int
   ch.send(1)

data/share/xchan.rb/examples/write_operations/2_nonblocking_write.rb

@@ -1,3 +1,4 @@
+#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require_relative "../setup"
@@ -14,7 +15,7 @@ rescue Chan::WaitLockable
   retry
 end
 
-ch = xchan(:marshal, sock_type: Socket::SOCK_STREAM)
+ch = xchan(:marshal, sock: Socket::SOCK_STREAM)
 sndbuf = ch.w.getsockopt(Socket::SOL_SOCKET, Socket::SO_SNDBUF)
 while ch.bytes_sent <= sndbuf.int
   send_nonblock(ch, 1)

data/test/readme_test.rb

@@ -27,10 +27,10 @@ class Chan::ReadmeTest < Test::Unit::TestCase
   end
 
   def test_socket_2_options
-    r = 'The read buffer can contain a maximum of: \d{1,6} bytes.\s*' \
-        'The maximum size of a single message is: \d{1,6} bytes.\s*'
+    r = 'The read buffer can contain a maximum of: \d{1,7} bytes.\s*' \
+        'The maximum size of a single message is: \d{1,7} bytes.\s*'
     assert_match Regexp.new(r),
-                 cmd("ruby", readme_example("socket/2_options.rb"))
+                 cmd("ruby", readme_example("socket/1_options.rb"))
                    .stdout
                    .tr("\n", " ")
   end

data/test/xchan_test.rb

@@ -84,7 +84,7 @@ class Chan::RecvNonBlockTest < Chan::Test
   end
 
   def test_recv_nonblock_with_a_lock
-    ch.instance_variable_get(:@lockf).lock
+    ch.instance_variable_get(:@lock).lock
     pid = fork do
       ch.recv_nonblock
       exit(1)
@@ -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

@@ -8,15 +8,22 @@ Gem::Specification.new do |gem|
   gem.homepage = "https://github.com/0x1eef/xchan.rb#readme"
   gem.version = Chan::VERSION
   gem.licenses = ["0BSD"]
-  gem.files = `git ls-files`.split($/)
+  gem.files = Dir[
+    "README.md", "LICENSE",
+    "share/xchan.rb/**/*.rb",
+    "lib/*.rb", "lib/**/*.rb",
+    "test/*.rb", "test/**/*.rb",
+    "xchan.rb.gemspec"
+  ]
   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 "redcarpet", "~> 3.5"
+  gem.add_development_dependency "kramdown", "~> 2.5"
   gem.add_development_dependency "standard", "~> 1.13"
   gem.add_development_dependency "test-cmd.rb", "~> 0.12.4"
   gem.add_development_dependency "rake", "~> 13.1"
+  gem.add_development_dependency "irb", "~> 1.14"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: xchan.rb
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.20.0
 platform: ruby
 authors:
 - '0x1eef'
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-30 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
@@ -53,19 +52,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.9'
 - !ruby/object:Gem::Dependency
-  name: redcarpet
+  name: kramdown
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.5'
+        version: '2.5'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.5'
+        version: '2.5'
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +107,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.1'
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
 description: An easy to use InterProcess Communication (IPC) library
 email:
 - 0x1eef@protonmail.com
@@ -115,18 +128,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".github/workflows/tests.yml"
-- ".gitignore"
-- ".projectile"
-- ".rubocop.yml"
-- ".yardopts"
-- Gemfile
-- LICENSE
 - README.md
-- Rakefile.rb
 - lib/xchan.rb
 - lib/xchan/bytes.rb
 - lib/xchan/counter.rb
+- lib/xchan/null_lock.rb
 - lib/xchan/tempfile.rb
 - lib/xchan/unix_socket.rb
 - lib/xchan/version.rb
@@ -134,7 +140,7 @@ files:
 - share/xchan.rb/examples/read_operations/2_nonblocking_read.rb
 - share/xchan.rb/examples/serialization/1_serializers.rb
 - share/xchan.rb/examples/setup.rb
-- share/xchan.rb/examples/socket/2_options.rb
+- share/xchan.rb/examples/socket/1_options.rb
 - share/xchan.rb/examples/stress_tests/1_parallel_access_stress_test.rb
 - share/xchan.rb/examples/write_operations/1_blocking_write.rb
 - share/xchan.rb/examples/write_operations/2_nonblocking_write.rb
@@ -146,7 +152,6 @@ homepage: https://github.com/0x1eef/xchan.rb#readme
 licenses:
 - 0BSD
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -161,8 +166,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: An easy to use InterProcess Communication (IPC) library
 test_files: []

data/.github/workflows/tests.yml

@@ -1,26 +0,0 @@
-name: xchan.rb
-
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
-
-jobs:
-  specs:
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macos-latest]
-        ruby: [3.2, 3.3]
-    runs-on: ${{ matrix.os }}
-    steps:
-    - uses: actions/checkout@v2
-    - uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ matrix.ruby }}
-    - run: bundle install
-    - run: SERIALIZER=marshal; for t in *_test.rb; do ruby test/${t}; done
-    - run: SERIALIZER=json; for t in *_test.rb; do ruby test/${t}; done
-    - run: SERIALIZER=yaml; for t in *_test.rb; do ruby test/${t}; done
-    - run: SERIALIZER=pure; for t in *_test.rb; do ruby test/${t}; done

data/.gitignore

@@ -1,8 +0,0 @@
-*.gem
-.bundle
-Gemfile.lock
-.yardoc/
-.dev/
-doc/
-pkg/
-.gems/

data/.projectile

@@ -1,5 +0,0 @@
-+/
-+/.github/
--/doc/
--/.yardoc/
--/.gems/

data/.rubocop.yml

@@ -1,34 +0,0 @@
-##
-# Plugins
-require:
-  - standard
-
-##
-# Defaults: standard-rb
-inherit_gem:
-  standard: config/base.yml
-
-##
-# All cops
-AllCops:
-  TargetRubyVersion: 3.2
-  Include:
-    - lib/*.rb
-    - lib/**/*.rb
-    - test/*_test.rb
-
-##
-# Enabled
-Style/FrozenStringLiteralComment:
-  Enabled: true
-
-##
-# Disabled
-Layout/ArgumentAlignment:
-  Enabled: false
-Layout/MultilineMethodCallIndentation:
-  Enabled: false
-Layout/EmptyLineBetweenDefs:
-  Enabled: false
-Style/TrivialAccessors:
-  Enabled: false

data/.yardopts

@@ -1,4 +0,0 @@
--m markdown -M redcarpet --no-private
--
-README.md
-LICENSE

data/Gemfile

@@ -1,4 +0,0 @@
-# frozen_string_literal: true
-
-source "https://rubygems.org"
-gemspec

data/LICENSE

@@ -1,15 +0,0 @@
-Copyright (C) 2023 by 0x1eef <0x1eef@protonmail.com>
-
-Permission to use, copy, modify, and/or distribute this
-software for any purpose with or without fee is hereby
-granted.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS
-ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
-EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
-INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
-RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
-ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
-OF THIS SOFTWARE.

data/Rakefile.rb

@@ -1,9 +0,0 @@
-require "rake/testtask"
-require "bundler/setup"
-
-Rake::TestTask.new do |t|
-  t.test_files = FileList['test/*_test.rb']
-  t.verbose = true
-  t.warning = false
-end
-task default: :test