xchan.rb 0.16.5 → 0.17.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5030f45f888a9c83fadde357be0c919cece744735af66016d80bcd5a9970dcc
-  data.tar.gz: b9de8383ad5af12a57586087c0c95b37d08ff07e7838b12471583c06ebec214b
+  metadata.gz: 5509107cf1cda5e847f3c15e19c81ba9323c2dbb524a7ef808eeb820d5bcdeb9
+  data.tar.gz: 43deff543ee38ace3ca8a083a043eb1c6bbedec9143bd2c8e17de50f13127031
 SHA512:
-  metadata.gz: 6716dcd591f6384a8665e2601fcc10d17f7ecb2842ed656ffc13de90d785bf5bd2e089fcc2ef5bba2a58ebde0b544014cc769cec6315413d0ac7c32d99724930
-  data.tar.gz: 578c4aedba9104f7eeec52d1780df6ac7e7caed3040f19da4e4f20b436031e60f79ce2e7300e5ce6abbd6d638406143b5bcb0a4335b4400ae27cba05743f0db2
+  metadata.gz: d5455dd6c714bc4060ec1f563b46d8a9eaee32e5aa58c2a2508de99f53fc29e346d07ac04e719822bc394b66ac6ba6ddf5585bf7958c606a0f1f375c113b4310
+  data.tar.gz: '09bd28506d18a63e8e917ad1189c708cc6643b852707508ee0edf563064bd3618d3ae251d85e06f618672c414537b4da3db0538b61e4c11c2a6c64fff3394f38'

data/.github/workflows/tests.yml

@@ -12,7 +12,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest]
-        ruby: [3.1, 3.2]
+        ruby: [3.1, 3.2, 3.3]
     runs-on: ${{ matrix.os }}
     steps:
     - uses: actions/checkout@v2
@@ -23,4 +23,4 @@ jobs:
     - run: SERIALIZER=marshal bundle exec rake
     - run: SERIALIZER=json bundle exec rake
     - run: SERIALIZER=yaml bundle exec rake
-    - run: SERIALIZER=plain bundle exec rake
+    - run: SERIALIZER=pure bundle exec rake

data/.gitlab-ci.yml

@@ -9,4 +9,4 @@ test-ruby32:
     - SERIALIZER=marshal bundle exec rake
     - SERIALIZER=json bundle exec rake
     - SERIALIZER=yaml bundle exec rake
-    - SERIALIZER=plain bundle exec rake
+    - SERIALIZER=pure bundle exec rake

data/.projectile

@@ -1 +1,4 @@
 +.
+-/doc/
+-/.yardoc/
+-/.gems/

data/Gemfile

@@ -1,6 +1,4 @@
 # frozen_string_literal: true
 
 source "https://rubygems.org"
-gem "lockf.rb", github: "0x1eef/lockf.rb", tag: "v0.10.6"
-gem "test-cmd.rb", github: "0x1eef/test-cmd.rb", tag: "v0.2.0"
 gemspec

data/README.md

@@ -1,9 +1,9 @@
 ## About
 
-xchan.rb is an easy to use library that provides a channel for
-InterProcess Communication (IPC) between a parent Ruby process,
-and its child processes. The channel is implemented through both
-serialization, and an unbound unix socket.
+xchan.rb is an easy to use library for InterProcess
+Communication (IPC). The library provides a channel
+that can transfer Ruby objects between Ruby processes
+with a parent <-> child relationship.
 
 ## Examples
 
@@ -11,58 +11,53 @@ serialization, and an unbound unix socket.
 
 #### Options
 
-When a channel is written to or read from, a Ruby object is serialized
-(on write) or deserialized (on read). The default serializers are available as
-`xchan(:marshal)`, `xchan(:json)`, and `xchan(:yaml)`. For scenarios where it
-is preferred to send and receive plain strings, the "plain" serializer is
-available as `xchan(:plain)`. This example uses
+The first argument given to xchan is the serializer
+that it should use. A channel that will communicate
+in pure strings (ie with no serialization) is
+available as `xchan(:pure)`.
+
+Otherwise, when a channel is written to or read from,
+a Ruby object is serialized (on write) or deserialized
+(on read). The serializers available to choose from
+are `xchan(:marshal)`, `xchan(:json)`, and `xchan(:yaml)`.
+The example uses
 [`Marshal`](https://www.rubydoc.info/stdlib/core/Marshal):
 
 ```ruby
 require "xchan"
 
 ##
-# This channel uses Marshal to serialize objects.
-ch = xchan
-pid = fork { print "Received message: ", ch.recv[:msg], "\n" }
-ch.send(msg: "serialized by Marshal")
-ch.close
-Process.wait(pid)
-
-##
-# This channel also uses Marshal to serialize objects.
+# This channel uses Marshal to serialize objects
 ch = xchan(:marshal)
-pid = fork { print "Received message: ", ch.recv[:msg], "\n"
-ch.send(msg: "serialized by Marshal")
+Process.wait fork { ch.send(5) }
+print "There are ", ch.recv + 7, " disciples and the same number of tribes", "\n"
 ch.close
-Process.wait(pid)
 
 ##
-# Received message: serialized by Marshal
-# Received message: serialized by Marshal
+# There are 12 disciples and the same number of tribes
 ```
 
 ### Read operations
 
 #### `#recv`
 
-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 the underlying
-socket blocks. This example performs a read that blocks in a child
-process until the parent process writes to the channel:
+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)
+blocks. The example performs a read that blocks until
+the parent process writes to the channel:
 
 ```ruby
 require "xchan"
 
-ch = xchan
-pid = fork do
+ch = xchan(:marshal)
+Process.detach fork {
   print "Received a random number (child process): ", ch.recv, "\n"
-end
-# Delay for a second to let a process fork, and call "ch.recv"
+}
 sleep(1)
 print "Send a random number (from parent process)", "\n"
 ch.send(rand(21))
-Process.wait(pid)
 ch.close
 
 ##
@@ -72,11 +67,12 @@ ch.close
 
 #### `#recv_nonblock`
 
-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 on the
-underlying socket blocks. This example performs a read that will
-raise `Chan::WaitReadable`:
+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)
+blocks:
 
 ```ruby
 require "xchan"
@@ -92,7 +88,7 @@ rescue Chan::WaitLockable
   retry
 end
 trap("SIGINT") { exit(1) }
-read(xchan)
+read(xchan(:marshal))
 
 ##
 # Wait 1 second for channel to be readable
@@ -104,15 +100,17 @@ read(xchan)
 
 #### `#send`
 
-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 the underlying socket blocks.
-This example performs a write that will block when the send buffer becomes full:
+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)
+blocks. The example fills the send buffer:
 
 ```ruby
 require "xchan"
 
 ch = xchan(:marshal, sock_type: Socket::SOCK_STREAM)
-sndbuf = ch.getsockopt(:reader, Socket::SOL_SOCKET, Socket::SO_SNDBUF)
+sndbuf = ch.w.getsockopt(Socket::SOL_SOCKET, Socket::SO_SNDBUF)
 while ch.bytes_sent <= sndbuf.int
   ch.send(1)
 end
@@ -120,11 +118,13 @@ end
 
 #### `#send_nonblock`
 
-The non-blocking counterpart to `#send` is `#send_nonblock`. The `#send_nonblock`
-method raises `Chan::WaitLockable` when a write blocks because of a lock held
-by another process, and the method raises `Chan::WaitReadable` when a write to
-the underlying socket blocks. This example builds on the previous example by
-freeing space on the send buffer when a write is found to block:
+The non-blocking counterpart to `#send` is
+`#send_nonblock`. The `#send_nonblock` method raises
+`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)
+blocks. The example frees space on the send buffer:
 
 ```ruby
 require "xchan"
@@ -141,7 +141,7 @@ rescue Chan::WaitLockable
 end
 
 ch = xchan(:marshal, sock_type: Socket::SOCK_STREAM)
-sndbuf = ch.getsockopt(:writer, Socket::SOL_SOCKET, Socket::SO_SNDBUF)
+sndbuf = ch.w.getsockopt(Socket::SOL_SOCKET, Socket::SO_SNDBUF)
 while ch.bytes_sent <= sndbuf.int
   send_nonblock(ch, 1)
 end
@@ -152,31 +152,14 @@ end
 
 ### Socket
 
-#### Types
-
-A channel can be created with one of three sockets types:
-
-* `Socket::SOCK_DGRAM`
-* `Socket::SOCK_STREAM`
-* `Socket::SOCK_SEQPACKET`
-
-The default is `Socket::SOCK_DGRAM` because its default settings
-provide the most buffer space. The socket type can be specified as
-a keyword argument:
-
-```ruby
-require "xchan"
-ch = xchan(:marshal, sock_type: Socket::SOCK_STREAM)
-```
-
 #### Options
 
-A channel is composed of two sockets, one for reading and the other for writing.
-Socket options can be read and set on either of the two sockets with the
-`Chan::UNIXSocket#getsockopt`, and `Chan::UNIXSocket#setsockopt` methods.
-Besides the first argument (`:reader`, or `:writer`), the rest of the arguments
-are identical to `Socket#{getsockopt,setsockopt}`. This example's results can
-vary depending on the operating system it is run on:
+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)
+returns the socket used for read operations, and
+[Chan::UNIXSocket#w](https://0x1eef.github,io/x/xchan.rb/Chan/UNIXSocket.html#w-instance_method)
+returns the socket used for write operations:
 
 ```ruby
 require "xchan"
@@ -184,12 +167,12 @@ ch = xchan(:marshal)
 
 ##
 # Print the value of SO_RCVBUF
-rcvbuf = ch.getsockopt(:reader, Socket::SOL_SOCKET, Socket::SO_RCVBUF)
+rcvbuf = ch.r.getsockopt(Socket::SOL_SOCKET, Socket::SO_RCVBUF)
 print "The read buffer can contain a maximum of: ", rcvbuf.int, " bytes.\n"
 
 ##
 # Print the value of SO_SNDBUF
-sndbuf = ch.getsockopt(:writer, Socket::SOL_SOCKET, Socket::SO_SNDBUF)
+sndbuf = ch.w.getsockopt(Socket::SOL_SOCKET, Socket::SO_SNDBUF)
 print "The maximum size of a single message is: ", sndbuf.int, " bytes.\n"
 
 ##
@@ -197,50 +180,22 @@ print "The maximum size of a single message is: ", sndbuf.int, " bytes.\n"
 # The maximum size of a single message is: 2048 bytes.
 ```
 
-### Temporary files
+## Documentation
 
-#### tmpdir
+A complete API reference is available at
+[0x1eef.github.io/x/xchan.rb](https://0x1eef.github.io/x/xchan.rb/).
 
-A single channel creates three temporary files that are removed
-from the filesystem as soon as they are created. By default the
-files are stored - for a short time - in `Dir.tmpdir`. Read and
-write permissions are reserved for the process that created
-them, inclusive of its child processes.
+## Install
 
-The parent directory of the temporary files can be changed with the
-`tmpdir` option:
+xchan.rb can be installed via rubygems.org:
 
-```ruby
-require "xchan"
-ch = xchan(:marshal, tmpdir: Dir.home)
-```
+    gem install xchan.rb
 
 ## Sources
 
 * [Source code (GitHub)](https://github.com/0x1eef/xchan.rb#readme)
 * [Source code (GitLab)](https://gitlab.com/0x1eef/xchan.rb#about)
 
-## Install
-
-**Git**
-
-xchan.rb is distributed as a RubyGem through its git repositories. <br>
-[GitHub](https://github.com/0x1eef/xchan.rb),
-and
-[GitLab](https://gitlab.com/0x1eef/xchan.rb)
-are available as sources.
-
-``` ruby
-# Gemfile
-gem "xchan.rb", github: "0x1eef/xchan.rb", tag: "v0.16.5"
-```
-
-**Rubygems.org**
-
-xchan.rb can also be installed via rubygems.org.
-
-    gem install xchan.rb
-
 ## <a id="license"> License </a>
 
 [BSD Zero Clause](https://choosealicense.com/licenses/0bsd/).

data/lib/xchan/bytes.rb

@@ -1,39 +1,31 @@
 # frozen_string_literal: true
 
 ##
-# The {Chan::Bytes Chan::Bytes} class is similar
-# to an array, where each element represents the
-# number of bytes used to store an object on a
-# channel. When an object is written to a channel,
-# the array increases in size, and when an object
-# is read from a channel, the array decreases in
-# size.
+# {Chan::Bytes Chan::Bytes} represents a collection
+# of byte counts for each object stored on a channel.
+# When an object is written to a channel, the collection
+# increases in size, and when an object is read from
+# a channel, the collection decreases in size.
 class Chan::Bytes
   require "json"
-  require_relative "stat"
-
-  ##
-  # @return [Chan::Stat]
-  attr_reader :stat
+  require_relative "counter"
 
   ##
   # @param [String] tmpdir
-  #  Path to a directory where temporary files will be stored.
+  #  Directory where temporary files are stored
   #
   # @return [Chan::Bytes]
   def initialize(tmpdir)
-    @serializer = JSON
     @io = Chan.temporary_file("xchan.bytes", tmpdir:)
     @io.sync = true
-    @stat = Chan::Stat.new(tmpdir)
     write(@io, [])
   end
 
   ##
-  # Insert a byte count at the head of the array
+  # Adds a count to the start of the collection
   #
   # @param [Integer] len
-  #  Number of bytes
+  #  The bytesize of an object
   #
   # @return [void]
   def unshift(len)
@@ -41,15 +33,14 @@ class Chan::Bytes
     bytes = read(@io)
     bytes.unshift(len)
     write(@io, bytes)
-    @stat.store(bytes_written: len)
     len
   end
 
   ##
-  # Insert a byte count at the tail of the array
+  # Adds a count to the end of the collection
   #
   # @param [Integer] len
-  #  Number of bytes
+  #  The bytesize of an object
   #
   # @return [void]
   def push(len)
@@ -57,25 +48,25 @@ class Chan::Bytes
     bytes = read(@io)
     bytes.push(len)
     write(@io, bytes)
-    @stat.store(bytes_written: len)
     len
   end
 
   ##
+  # Removes a count from the start of the collection
+  #
   # @return [Integer]
-  #  Returns (and removes) a byte count from the head of the array
+  #  Returns the removed byte count
   def shift
     bytes = read(@io)
     return 0 if bytes.size.zero?
     len = bytes.shift
     write(@io, bytes)
-    @stat.store(bytes_read: len)
     len
   end
 
   ##
   # @return [Integer]
-  #  Returns the size of the array
+  #  Returns the number of objects in the collection
   def size
     read(@io).size
   end
@@ -100,10 +91,10 @@ class Chan::Bytes
   end
 
   def serialize(bytes)
-    @serializer.dump(bytes)
+    JSON.dump(bytes)
   end
 
   def deserialize(bytes)
-    @serializer.load(bytes)
+    JSON.load(bytes)
   end
 end

data/lib/xchan/{stat.rb → counter.rb}

@@ -1,33 +1,32 @@
 # frozen_string_literal: true
 
 ##
-# The {Chan::Stat Chan::Stat} class provides statistics
-# (eg number of bytes read, number of bytes written) for
-# a given channel.
-class Chan::Stat
+# {Chan::Counter Chan::Counter} provides a counter
+# for the number of written and received bytes on a
+# given channel.
+class Chan::Counter
   require "json"
 
   ##
   # @param [String] tmpdir
-  #  Path to a directory where temporary files will be stored.
+  #  Directory where temporary files are stored
   #
-  # @return [Chan::Stat]
+  # @return [Chan::Counter]
   def initialize(tmpdir)
-    @serializer = JSON
-    @io = Chan.temporary_file("xchan.stat", tmpdir:)
+    @io = Chan.temporary_file("xchan.counter", tmpdir:)
     write(@io, {"bytes_read" => 0, "bytes_written" => 0})
   end
 
   ##
   # @return [Integer]
-  #  Returns the number of bytes written to a channel.
+  #  Returns the number of bytes written to a channel
   def bytes_written
     read(@io).fetch("bytes_written")
   end
 
   ##
   # @return [Integer]
-  #  Returns the number of bytes read from a channel.
+  #  Returns the number of bytes read from a channel
   def bytes_read
     read(@io).fetch("bytes_read")
   end
@@ -36,7 +35,7 @@ class Chan::Stat
   # @param [Hash] new_stat
   # @return [void]
   # @private
-  def store(new_stat)
+  def increment!(new_stat)
     stat = read(@io)
     new_stat.each { stat[_1.to_s] += _2 }
     write(@io, stat)
@@ -54,10 +53,10 @@ class Chan::Stat
   end
 
   def serialize(bytes)
-    @serializer.dump(bytes)
+    JSON.dump(bytes)
   end
 
   def deserialize(bytes)
-    @serializer.load(bytes)
+    JSON.load(bytes)
   end
 end

data/lib/xchan/tempfile.rb

@@ -2,11 +2,7 @@ require 'delegate'
 require 'tmpdir'
 
 ##
-# {Chan::Tempfile Chan::Tempfile} is a fork of Tempfile from
-# Ruby's standard library. The primary difference between
-# {Chan::Tempfile Chan::Tempfile}, and the standard library is
-# that [ruby/tempfile#22](https://github.com/ruby/tempfile/pull/22)
-# is applied in this fork.
+# @private
 class Chan::Tempfile < DelegateClass(File)
   VERSION = "0.1.3"
 
@@ -260,63 +256,63 @@ class Chan::Tempfile < DelegateClass(File)
   end
 end
 
-# Creates a file in the underlying file system;
-# returns a new \File object based on that file.
-#
-# With no block given and no arguments, creates and returns file whose:
-#
-# - Class is {File}[https://docs.ruby-lang.org/en/master/File.html] (not \Tempfile).
-# - Directory is the system temporary directory (system-dependent).
-# - Generated filename is unique in that directory.
-# - Permissions are <tt>0600</tt>;
-#   see {File Permissions}[https://docs.ruby-lang.org/en/master/File.html#label-File+Permissions].
-# - Mode is <tt>'w+'</tt> (read/write mode, positioned at the end).
-#
-# With no block, the file is not removed automatically,
-# and so should be explicitly removed.
-#
-# Example:
-#
-#   f = Tempfile.create     # => #<File:/tmp/20220505-9795-17ky6f6>
-#   f.class                 # => File
-#   f.path                  # => "/tmp/20220505-9795-17ky6f6"
-#   f.stat.mode.to_s(8)     # => "100600"
-#   File.exist?(f.path)     # => true
-#   File.unlink(f.path)
-#   File.exist?(f.path)     # => false
-#
-# Argument +basename+, if given, may be one of:
-#
-# - A string: the generated filename begins with +basename+:
-#
-#     Tempfile.create('foo') # => #<File:/tmp/foo20220505-9795-1gok8l9>
-#
-# - An array of two strings <tt>[prefix, suffix]</tt>:
-#   the generated filename begins with +prefix+ and ends with +suffix+:
-#
-#     Tempfile.create(%w/foo .jpg/) # => #<File:/tmp/foo20220505-17839-tnjchh.jpg>
-#
-# With arguments +basename+ and +tmpdir+, the file is created in directory +tmpdir+:
-#
-#   Tempfile.create('foo', '.') # => #<File:./foo20220505-9795-1emu6g8>
-#
-# Keyword arguments +mode+ and +options+ are passed directly to method
-# {File.open}[https://docs.ruby-lang.org/en/master/File.html#method-c-open]:
-#
-# - The value given with +mode+ must be an integer,
-#   and may be expressed as the logical OR of constants defined in
-#   {File::Constants}[https://docs.ruby-lang.org/en/master/File/Constants.html].
-# - For +options+, see {Open Options}[https://docs.ruby-lang.org/en/master/IO.html#class-IO-label-Open+Options].
-#
-# With a block given, creates the file as above, passes it to the block,
-# and returns the block's value;
-# before the return, the file object is closed and the underlying file is removed:
-#
-#   Tempfile.create {|file| file.path } # => "/tmp/20220505-9795-rkists"
-#
-# Related: Tempfile.new.
-#
 module Chan
+  # Creates a file in the underlying file system;
+  # returns a new \File object based on that file.
+  #
+  # With no block given and no arguments, creates and returns file whose:
+  #
+  # - Class is {File}[https://docs.ruby-lang.org/en/master/File.html] (not \Tempfile).
+  # - Directory is the system temporary directory (system-dependent).
+  # - Generated filename is unique in that directory.
+  # - Permissions are <tt>0600</tt>;
+  #   see {File Permissions}[https://docs.ruby-lang.org/en/master/File.html#label-File+Permissions].
+  # - Mode is <tt>'w+'</tt> (read/write mode, positioned at the end).
+  #
+  # With no block, the file is not removed automatically,
+  # and so should be explicitly removed.
+  #
+  # Example:
+  #
+  #   f = Tempfile.create     # => #<File:/tmp/20220505-9795-17ky6f6>
+  #   f.class                 # => File
+  #   f.path                  # => "/tmp/20220505-9795-17ky6f6"
+  #   f.stat.mode.to_s(8)     # => "100600"
+  #   File.exist?(f.path)     # => true
+  #   File.unlink(f.path)
+  #   File.exist?(f.path)     # => false
+  #
+  # Argument +basename+, if given, may be one of:
+  #
+  # - A string: the generated filename begins with +basename+:
+  #
+  #     Tempfile.create('foo') # => #<File:/tmp/foo20220505-9795-1gok8l9>
+  #
+  # - An array of two strings <tt>[prefix, suffix]</tt>:
+  #   the generated filename begins with +prefix+ and ends with +suffix+:
+  #
+  #     Tempfile.create(%w/foo .jpg/) # => #<File:/tmp/foo20220505-17839-tnjchh.jpg>
+  #
+  # With arguments +basename+ and +tmpdir+, the file is created in directory +tmpdir+:
+  #
+  #   Tempfile.create('foo', '.') # => #<File:./foo20220505-9795-1emu6g8>
+  #
+  # Keyword arguments +mode+ and +options+ are passed directly to method
+  # {File.open}[https://docs.ruby-lang.org/en/master/File.html#method-c-open]:
+  #
+  # - The value given with +mode+ must be an integer,
+  #   and may be expressed as the logical OR of constants defined in
+  #   {File::Constants}[https://docs.ruby-lang.org/en/master/File/Constants.html].
+  # - For +options+, see {Open Options}[https://docs.ruby-lang.org/en/master/IO.html#class-IO-label-Open+Options].
+  #
+  # With a block given, creates the file as above, passes it to the block,
+  # and returns the block's value;
+  # before the return, the file object is closed and the underlying file is removed:
+  #
+  #   Tempfile.create {|file| file.path } # => "/tmp/20220505-9795-rkists"
+  #
+  # Related: Tempfile.new.
+  #
   def Tempfile.create(basename="", tmpdir=nil, mode: 0, perm: 0600, **options)
     tmpfile = nil
     Dir::Tmpname.create(basename, tmpdir, **options) do |tmpname, n, opts|

data/lib/xchan/unix_socket.rb

@@ -1,13 +1,22 @@
 # frozen_string_literal: true
 
 ##
-# The {Chan::UNIXSocket Chan::UNIXSocket} class implements a channel
-# for interprocess communication (IPC) using an unnamed UNIXSocket.
+# An easy-to-use InterProcess Communication (IPC) library.
 class Chan::UNIXSocket
   require "socket"
   require "lockf"
   require_relative "bytes"
 
+  ##
+  # @return [UNIXSocket]
+  #  Returns a socket used for read operations
+  attr_reader :r
+
+  ##
+  # @return [UNIXSocket]
+  #  Returns a socket used for write operations
+  attr_reader :w
+
   ##
   # @example
   #   ch = Chan::UNIXSocket.new(:marshal)
@@ -16,39 +25,40 @@ class Chan::UNIXSocket
   #   ch.close
   #
   # @param [Symbol, <#dump, #load>] serializer
-  #  A serializer.
+  #  The name of a serializer
   #
   # @param [Integer] sock_type
-  #  A socket type (eg Socket::SOCK_STREAM).
+  #  Type of socket (eg `Socket::SOCK_STREAM`)
   #
   # @param [String] tmpdir
-  #  Path to a directory where temporary files will be stored.
+  #  Directory where temporary files can be stored
   #
   # @return [Chan::UNIXSocket]
-  #  Returns an instance of {Chan::UNIXSocket Chan::UNIXSocket}.
-  def initialize(serializer, tmpdir: Dir.tmpdir, sock_type: Socket::SOCK_DGRAM)
+  #  Returns an instance of {Chan::UNIXSocket Chan::UNIXSocket}
+  def initialize(serializer, sock_type: Socket::SOCK_DGRAM, tmpdir: Dir.tmpdir)
     @serializer = Chan.serializers[serializer]&.call || serializer
     @r, @w = ::UNIXSocket.pair(sock_type)
     @bytes = Chan::Bytes.new(tmpdir)
+    @counter = Chan::Counter.new(tmpdir)
     @lock = LockFile.new Chan.temporary_file("xchan.lock", tmpdir:)
   end
 
   ##
   # @return [<#dump, #load>]
-  #  Returns the serializer used by the channel.
+  #  Returns the serializer used by the channel
   def serializer
     @serializer
   end
 
   ##
   # @return [Boolean]
-  #  Returns true when the channel is closed.
+  #  Returns true when the channel is closed
   def closed?
     @r.closed? and @w.closed?
   end
 
   ##
-  # Closes the channel.
+  # Closes the channel
   #
   # @raise [IOError]
   #  When the channel is closed.
@@ -70,13 +80,13 @@ class Chan::UNIXSocket
   # Performs a blocking write
   #
   # @param [Object] object
-  #  An object to write to the channel.
+  #  An object
   #
   # @raise [IOError]
-  #  When the channel is closed.
+  #  When the channel is closed
   #
   # @return [Object]
-  #  Returns the number of bytes written to the channel.
+  #  Returns the number of bytes written to the channel
   def send(object)
     send_nonblock(object)
   rescue Chan::WaitWritable, Chan::WaitLockable
@@ -88,24 +98,25 @@ class Chan::UNIXSocket
   # Performs a non-blocking write
   #
   # @param [Object] object
-  #  An object to write to the channel.
+  #  An object
   #
   # @raise [IOError]
-  #  When the channel is closed.
+  #  When the channel is closed
   #
   # @raise [Chan::WaitWritable]
-  #  When a write to the underlying IO blocks.
+  #  When a write to {#w} blocks
   #
   # @raise [Chan::WaitLockable]
-  #  When a write blocks because of a lock held by another process.
+  #  When a write blocks because of a lock held by another process
   #
   # @return [Integer, nil]
-  #  Returns the number of bytes written to the channel.
+  #  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
@@ -125,10 +136,10 @@ class Chan::UNIXSocket
   # Performs a blocking read
   #
   # @raise [IOError]
-  #  When the channel is closed.
+  #  When the channel is closed
   #
   # @return [Object]
-  #  Returns an object from the channel.
+  #  Returns an object from the channel
   def recv
     recv_nonblock
   rescue Chan::WaitReadable
@@ -143,21 +154,22 @@ class Chan::UNIXSocket
   # Performs a non-blocking read
   #
   # @raise [IOError]
-  #  When the channel is closed.
+  #  When the channel is closed
   #
   # @raise [Chan::WaitReadable]
-  #  When a read from the underlying IO blocks.
+  #  When a read from {#r} blocks
   #
   # @raise [Chan::WaitLockable]
-  #  When a read blocks because of a lock held by another process.
+  #  When a read blocks because of a lock held by another process
   #
   # @return [Object]
-  #  Returns an object from the channel.
+  #  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
@@ -181,7 +193,7 @@ class Chan::UNIXSocket
   #   ch.to_a.last # => 4
   #
   # @return [Array<Object>]
-  #  Returns the consumed contents of the channel.
+  #  Returns the contents of the channel
   def to_a
     lock do
       [].tap { _1.push(recv) until empty? }
@@ -190,28 +202,28 @@ class Chan::UNIXSocket
 
   ##
   # @return [Boolean]
-  #  Returns true when the channel is empty.
+  #  Returns true when the channel is empty
   def empty?
     return true if closed?
     lock { size.zero? }
   end
 
   ##
-  # @group Size methods
+  # @group Stat methods
 
   ##
   # @return [Integer]
-  #  Returns the total number of bytes written to the channel.
+  #  Returns the total number of bytes written to the channel
   def bytes_sent
-    lock { @bytes.stat.bytes_written }
+    lock { @counter.bytes_written }
   end
   alias_method :bytes_written, :bytes_sent
 
   ##
   # @return [Integer]
-  #  Returns the total number of bytes read from the channel.
+  #  Returns the total number of bytes read from the channel
   def bytes_received
-    lock { @bytes.stat.bytes_read }
+    lock { @counter.bytes_read }
   end
   alias_method :bytes_read, :bytes_received
 
@@ -255,61 +267,6 @@ class Chan::UNIXSocket
   ##
   # @endgroup
 
-  ##
-  # @group Socket options
-
-  ##
-  # @param [String, Symbol] target
-  #  `:reader`, or `:writer`.
-  #
-  # @param [Integer] level
-  #  The level (eg `Socket::SOL_SOCKET` for the socket level).
-  #
-  # @param [Integer] option_name
-  #  The name of an option (eg `Socket::SO_RCVBUF`).
-  #
-  # @param [Boolean, Integer] option_value
-  #  The option value (eg 12345)
-  #
-  # @return [Integer]
-  #  Returns 0 on success.
-  def setsockopt(target, level, option_name, option_value)
-    @lock.lock
-    if !%w[reader writer].include?(target.to_s)
-      raise ArgumentError, "target can be ':reader', or ':writer'"
-    end
-    target = (target == :reader) ? @r : @w
-    target.setsockopt(level, option_name, option_value)
-  ensure
-    @lock.release
-  end
-
-  ##
-  # @param [String, Symbol] target
-  #  `:reader`, or `:writer`.
-  #
-  # @param [Integer] level
-  #  The level (eg `Socket::SOL_SOCKET` for the socket level).
-  #
-  # @param [Integer] option_name
-  #  The name of an option (eg `Socket::SO_RCVBUF`).
-  #
-  # @return [Socket::Option]
-  #  Returns an instance of `Socket::Option`.
-  def getsockopt(target, level, option_name)
-    @lock.lock
-    if !%w[reader writer].include?(target.to_s)
-      raise ArgumentError, "target can be ':reader', or ':writer'"
-    end
-    target = (target == :reader) ? @r : @w
-    target.getsockopt(level, option_name)
-  ensure
-    @lock.release
-  end
-
-  ##
-  # @endgroup
-
   private
 
   def lock

data/lib/xchan/version.rb

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

data/lib/xchan.rb

@@ -4,12 +4,25 @@ module Chan
   require_relative "xchan/version"
   require_relative "xchan/unix_socket"
   require_relative "xchan/tempfile"
-  require_relative "xchan/mixin"
 
   WaitReadable = Class.new(IO::EAGAINWaitReadable)
   WaitWritable = Class.new(IO::EAGAINWaitWritable)
   WaitLockable = Class.new(Errno::EWOULDBLOCK)
-  Plain = Class.new do
+
+  ##
+  # The Pure serializer won't perform
+  # serialization that goes beyond calling
+  # `.to_s` on the object it is given. It
+  # can be useful when you want to communicate
+  # purely in strings.
+  #
+  # @example
+  #   ch = xchan(:pure)
+  #   Process.wait fork {
+  #     ch.send "Hello world"
+  #   }
+  #   puts ch.recv
+  Pure = Class.new do
     def self.dump(str) = str.to_s
     def self.load(str) = str.to_s
   end
@@ -21,20 +34,23 @@ module Chan
   # processes other than that.
   #
   # @param [String] basename
-  #  Basename of the temporary file.
+  #  Basename of the temporary file
   #
   # @param [String] tmpdir
-  #  Parent directory of the temporary file.
+  #  Parent directory of the temporary file
   #
   # @return [Chan::Tempfile]
-  #  Returns an instance of {Chan::Tempfile Chan::Tempfile}.
+  #  Returns an instance of {Chan::Tempfile Chan::Tempfile}
   def self.temporary_file(basename, tmpdir: Dir.tmpdir)
     Chan::Tempfile.new(basename, tmpdir, perm: 0).tap(&:unlink)
   end
 
+  ##
+  # @return [Hash<Symbol, Proc>]
+  #  A mapping of serializers
   def self.serializers
     {
-      plain: lambda { Plain },
+      pure: lambda { Pure },
       marshal: lambda { Marshal },
       json: lambda {
         require "json" unless defined?(JSON)
@@ -48,6 +64,19 @@ module Chan
   end
 end
 
-class Object
-  include Chan::Mixin
+module Kernel
+  ##
+  # @example
+  #   ch = xchan
+  #   ch.send([1,2,3])
+  #   ch.recv.pop # => 3
+  #   ch.close
+  #
+  # @param serializer (see Chan::UNIXSocket#initialize)
+  # @param sock_type (see Chan::UNIXSocket#initialize)
+  # @param tmpdir (see Chan::UNIXSocket#initialize)
+  # @return (see Chan::UNIXSocket#initialize)
+  def xchan(serializer, **kw_args)
+    Chan::UNIXSocket.new(serializer, **kw_args)
+  end
 end

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

@@ -4,15 +4,13 @@ require_relative "../setup"
 require "xchan"
 
 $stdout.sync = true
-ch = xchan
-pid = fork do
+ch = xchan(:marshal)
+Process.detach fork {
   print "Received random number (child process): ", ch.recv, "\n"
-end
-# Delay for a second to let a process fork, and call "ch.recv"
+}
 sleep(1)
 print "Send a random number (from parent process)", "\n"
 ch.send(rand(21))
-Process.wait(pid)
 ch.close
 
 ##

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

@@ -14,4 +14,4 @@ rescue Chan::WaitLockable
   retry
 end
 trap("SIGINT") { exit(1) }
-read(xchan)
+read(xchan(:marshal))

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

@@ -4,17 +4,11 @@ require_relative "../setup"
 require "xchan"
 
 ##
-# This channel uses Marshal to serialize objects.
-ch = xchan
-pid = fork { print "Received message: ", ch.recv[:msg], "\n" }
-ch.send(msg: "serialized by Marshal")
+# This channel uses Marshal to serialize objects
+ch = xchan(:marshal)
+Process.wait fork { ch.send(5) }
+print "There are ", ch.recv + 7, " disciples and the same number of tribes", "\n"
 ch.close
-Process.wait(pid)
 
 ##
-# This channel also uses Marshal to serialize objects.
-ch = xchan(:marshal)
-pid = fork { print "Received message: ", ch.recv[:msg], "\n" }
-ch.send(msg: "serialized by Marshal")
-ch.close
-Process.wait(pid)
+# There are 12 disciples and the same number of tribes

data/share/xchan.rb/examples/socket/2_options.rb

@@ -3,10 +3,10 @@ ch = xchan(:marshal)
 
 ##
 # Print the value of SO_RCVBUF
-rcvbuf = ch.getsockopt(:reader, Socket::SOL_SOCKET, Socket::SO_RCVBUF)
+rcvbuf = ch.r.getsockopt(Socket::SOL_SOCKET, Socket::SO_RCVBUF)
 print "The read buffer can contain a maximum of: ", rcvbuf.int, " bytes.\n"
 
 ##
 # Print the value of SO_SNDBUF
-sndbuf = ch.getsockopt(:writer, Socket::SOL_SOCKET, Socket::SO_SNDBUF)
+sndbuf = ch.w.getsockopt(Socket::SOL_SOCKET, Socket::SO_SNDBUF)
 print "The maximum size of a single message is: ", sndbuf.int, " bytes.\n"

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

@@ -4,7 +4,7 @@ require_relative "../setup"
 require "xchan"
 
 ch = xchan(:marshal, sock_type: Socket::SOCK_STREAM)
-sndbuf = ch.getsockopt(:reader, Socket::SOL_SOCKET, Socket::SO_SNDBUF)
+sndbuf = ch.w.getsockopt(Socket::SOL_SOCKET, Socket::SO_SNDBUF)
 while ch.bytes_sent <= sndbuf.int
   ch.send(1)
 end

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

@@ -15,7 +15,7 @@ rescue Chan::WaitLockable
 end
 
 ch = xchan(:marshal, sock_type: Socket::SOCK_STREAM)
-sndbuf = ch.getsockopt(:writer, Socket::SOL_SOCKET, Socket::SO_SNDBUF)
+sndbuf = ch.w.getsockopt(Socket::SOL_SOCKET, Socket::SO_SNDBUF)
 while ch.bytes_sent <= sndbuf.int
   send_nonblock(ch, 1)
 end

data/test/readme_test.rb

@@ -4,10 +4,8 @@ require_relative "setup"
 require "test/cmd"
 
 class Chan::ReadmeTest < Test::Unit::TestCase
-  include Test::Cmd
-
   def test_serialization_1_serializers
-    assert_equal "Received message: serialized by Marshal\n" * 2,
+    assert_equal "There are 12 disciples and the same number of tribes\n",
                  readme_example("serialization/1_serializers.rb").stdout
   end
 

data/test/xchan_test.rb

@@ -4,7 +4,7 @@ require_relative "setup"
 
 class Chan::Test < Test::Unit::TestCase
   def setup
-    @ch = xchan ENV.fetch("SERIALIZER", "marshal").to_sym
+    @ch = xchan(serializer)
   end
 
   def teardown
@@ -17,9 +17,13 @@ class Chan::Test < Test::Unit::TestCase
     @ch
   end
 
+  def serializer
+    ENV.fetch("SERIALIZER", "pure").to_sym
+  end
+
   def object
-    case ENV["SERIALIZER"]
-    when "plain" then "xchan"
+    case serializer
+    when :pure then "xchan"
     else %w[xchan]
     end
   end

data/xchan.rb.gemspec

@@ -10,13 +10,13 @@ Gem::Specification.new do |gem|
   gem.licenses = ["0BSD"]
   gem.files = `git ls-files`.split($/)
   gem.require_paths = ["lib"]
-  gem.summary = "An easy to use InterProcess Communication (IPC) library."
+  gem.summary = "An easy to use InterProcess Communication (IPC) library"
   gem.description = gem.summary
-  gem.add_runtime_dependency "lockf.rb", "~> 0.10.6"
+  gem.add_runtime_dependency "lockf.rb", "~> 1.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 "standard", "~> 1.13"
-  gem.add_development_dependency "test-cmd.rb", "~> 0.2"
+  gem.add_development_dependency "test-cmd.rb", "~> 0.8"
   gem.add_development_dependency "rake", "~> 13.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xchan.rb
 version: !ruby/object:Gem::Version
-  version: 0.16.5
+  version: 0.17.1
 platform: ruby
 authors:
 - '0x1eef'
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-06 00:00:00.000000000 Z
+date: 2024-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lockf.rb
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.6
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.6
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: test-unit
   requirement: !ruby/object:Gem::Requirement
@@ -86,14 +86,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.8'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -108,7 +108,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.1'
-description: An easy to use InterProcess Communication (IPC) library.
+description: An easy to use InterProcess Communication (IPC) library
 email:
 - 0x1eef@protonmail.com
 executables: []
@@ -127,8 +127,7 @@ files:
 - Rakefile.rb
 - lib/xchan.rb
 - lib/xchan/bytes.rb
-- lib/xchan/mixin.rb
-- lib/xchan/stat.rb
+- lib/xchan/counter.rb
 - lib/xchan/tempfile.rb
 - lib/xchan/unix_socket.rb
 - lib/xchan/version.rb
@@ -163,8 +162,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
-summary: An easy to use InterProcess Communication (IPC) library.
+summary: An easy to use InterProcess Communication (IPC) library
 test_files: []

data/lib/xchan/mixin.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-##
-# A module that is included into Ruby's {Object} class.
-module Chan::Mixin
-  ##
-  # @example
-  #   ch = xchan
-  #   ch.send([1,2,3])
-  #   ch.recv.pop # => 3
-  #   ch.close
-  #
-  # @param serializer (see Chan::UNIXSocket#initialize)
-  # @param sock_type (see Chan::UNIXSocket#initialize)
-  # @param tmpdir (see Chan::UNIXSocket#initialize)
-  # @return (see Chan::UNIXSocket#initialize)
-  def xchan(serializer = :marshal, **kw_args)
-    Chan::UNIXSocket.new(serializer, **kw_args)
-  end
-end