xchan.rb 0.16.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f17c01d5c34d8de2176fa5241ca08bc985798d6a3d7d6b4fa355cd0f2cc6e739
+  data.tar.gz: 0f1908263e8a272e32d2ec6e8026c21e836c1da92ee2ed12a0a9949e69ed1d46
+SHA512:
+  metadata.gz: ac3779d634423270951d4c2d4818c021a856f066837f3b2015365d50af390cb5ccc2453475773f4ee0ed13ce1c19a30787e873ee43d84dc7d1ebd7f744e7a3f9
+  data.tar.gz: d7fccca83af9d0d73302b17b50d7b03843ce1c7d599f711e1a7f5b9252d1a8e9f40f7919134ffb25fb88007ee2578b0a9e7049a51b29c3cb0440df66a5ea0d09

data/.github/workflows/tests.yml

@@ -0,0 +1,26 @@
+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.1, 3.2]
+    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 bundle exec rake
+    - run: SERIALIZER=json bundle exec rake
+    - run: SERIALIZER=yaml bundle exec rake
+    - run: SERIALIZER=plain bundle exec rake

data/.gitignore

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

data/.gitlab-ci.yml

@@ -0,0 +1,12 @@
+stages:
+  - test
+
+test-ruby32:
+  stage: test
+  image: ruby:3.2.0
+  script:
+    - bundle install
+    - SERIALIZER=marshal bundle exec rake
+    - SERIALIZER=json bundle exec rake
+    - SERIALIZER=yaml bundle exec rake
+    - SERIALIZER=plain bundle exec rake

data/.projectile

@@ -0,0 +1 @@
++.

data/.rubocop.yml

@@ -0,0 +1,34 @@
+##
+# 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

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

data/Gemfile

@@ -0,0 +1,6 @@
+# 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/LICENSE

@@ -0,0 +1,15 @@
+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/README.md

@@ -0,0 +1,242 @@
+## 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.
+
+## Examples
+
+### Serialization
+
+#### 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
+[`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.
+ch = xchan(:marshal)
+pid = fork { print "Received message: ", ch.recv[:msg], "\n"
+ch.send(msg: "serialized by Marshal")
+ch.close
+Process.wait(pid)
+
+##
+# Received message: serialized by Marshal
+# Received message: serialized by Marshal
+```
+
+### 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:
+
+```ruby
+require "xchan"
+
+ch = xchan
+pid = fork do
+  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
+
+##
+# Send a random number (from parent process)
+# Received random number (child process): XX
+```
+
+#### `#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`:
+
+```ruby
+require "xchan"
+
+def read(ch)
+  ch.recv_nonblock
+rescue Chan::WaitReadable
+  print "Wait 1 second for channel to be readable", "\n"
+  ch.wait_readable(1)
+  retry
+rescue Chan::WaitLockable
+  sleep 0.01
+  retry
+end
+trap("SIGINT") { exit(1) }
+read(xchan)
+
+##
+# Wait 1 second for channel to be readable
+# Wait 1 second for channel to be readable
+# ^C
+```
+
+### Write operations
+
+#### `#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:
+
+```ruby
+require "xchan"
+
+ch = xchan(:marshal, socket: Socket::SOCK_STREAM)
+sndbuf = ch.getsockopt(:reader, Socket::SOL_SOCKET, Socket::SO_SNDBUF)
+while ch.bytes_sent <= sndbuf.int
+  ch.send(1)
+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:
+
+```ruby
+require "xchan"
+
+def send_nonblock(ch, buf)
+  ch.send_nonblock(buf)
+rescue Chan::WaitWritable
+  print "Blocked - free send buffer", "\n"
+  ch.recv
+  retry
+rescue Chan::WaitLockable
+  sleep 0.01
+  retry
+end
+
+ch = xchan(:marshal, socket: Socket::SOCK_STREAM)
+sndbuf = ch.getsockopt(:writer, Socket::SOL_SOCKET, Socket::SO_SNDBUF)
+while ch.bytes_sent <= sndbuf.int
+  send_nonblock(ch, 1)
+end
+
+##
+# Blocked - free send buffer
+```
+
+### 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, socket: 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:
+
+```ruby
+require "xchan"
+ch = xchan(:marshal)
+
+##
+# Print the value of SO_RCVBUF
+rcvbuf = ch.getsockopt(:reader, 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)
+print "The maximum size of a single message is: ", sndbuf.int, " bytes.\n"
+
+##
+# The read buffer can contain a maximum of: 16384 bytes.
+# The maximum size of a single message is: 2048 bytes.
+```
+
+### Temporary files
+
+#### tmpdir
+
+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.
+
+The parent directory of the temporary files can be changed with the
+`tmpdir` option:
+
+```ruby
+require "xchan"
+ch = xchan(:marshal, tmpdir: Dir.home)
+```
+
+## Sources
+
+* [Source code (GitHub)](https://github.com/0x1eef/xchan.rb#readme)
+* [Source code (GitLab)](https://gitlab.com/0x1eef/xchan.rb#about)
+
+## Install
+
+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.
+
+**Gemfile**
+
+```ruby
+gem "xchan.rb", github: "0x1eef/xchan.rb", tag: "v0.16.3"
+gem "lockf.rb", github: "0x1eef/lockf.rb", tag: "v0.10.6"
+```
+
+## <a id="license"> License </a>
+
+[BSD Zero Clause](https://choosealicense.com/licenses/0bsd/).
+<br>
+See [LICENSE](./LICENSE).

data/Rakefile.rb

@@ -0,0 +1,9 @@
+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

data/lib/xchan/bytes.rb

@@ -0,0 +1,109 @@
+# 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.
+class Chan::Bytes
+  require "json"
+  require_relative "stat"
+
+  ##
+  # @return [Chan::Stat]
+  attr_reader :stat
+
+  ##
+  # @param [String] tmpdir
+  #  Path to a directory where temporary files will be 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
+  #
+  # @param [Integer] len
+  #  Number of bytes
+  #
+  # @return [void]
+  def unshift(len)
+    return 0 if len.nil? || len.zero?
+    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
+  #
+  # @param [Integer] len
+  #  Number of bytes
+  #
+  # @return [void]
+  def push(len)
+    return 0 if len.nil? || len.zero?
+    bytes = read(@io)
+    bytes.push(len)
+    write(@io, bytes)
+    @stat.store(bytes_written: len)
+    len
+  end
+
+  ##
+  # @return [Integer]
+  #  Returns (and removes) a byte count from the head of the array
+  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
+  def size
+    read(@io).size
+  end
+
+  ##
+  # Close the underlying IO
+  #
+  # @return [void]
+  def close
+    @io.close
+  end
+
+  private
+
+  def read(io)
+    deserialize(io.read).tap { io.rewind }
+  end
+
+  def write(io, bytes)
+    io.truncate(0)
+    io.write(serialize(bytes)).tap { io.rewind }
+  end
+
+  def serialize(bytes)
+    @serializer.dump(bytes)
+  end
+
+  def deserialize(bytes)
+    @serializer.load(bytes)
+  end
+end

data/lib/xchan/mixin.rb

@@ -0,0 +1,20 @@
+# 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 socket (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

data/lib/xchan/stat.rb

@@ -0,0 +1,63 @@
+# 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
+  require "json"
+
+  ##
+  # @param [String] tmpdir
+  #  Path to a directory where temporary files will be stored.
+  #
+  # @return [Chan::Stat]
+  def initialize(tmpdir)
+    @serializer = JSON
+    @io = Chan.temporary_file("xchan.stat", tmpdir:)
+    write(@io, {"bytes_read" => 0, "bytes_written" => 0})
+  end
+
+  ##
+  # @return [Integer]
+  #  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.
+  def bytes_read
+    read(@io).fetch("bytes_read")
+  end
+
+  ##
+  # @param [Hash] new_stat
+  # @return [void]
+  # @private
+  def store(new_stat)
+    stat = read(@io)
+    new_stat.each { stat[_1.to_s] += _2 }
+    write(@io, stat)
+  end
+
+  private
+
+  def write(io, o)
+    io.truncate(0)
+    io.write(serialize(o)).tap { io.rewind }
+  end
+
+  def read(io)
+    deserialize(io.read).tap { io.rewind }
+  end
+
+  def serialize(bytes)
+    @serializer.dump(bytes)
+  end
+
+  def deserialize(bytes)
+    @serializer.load(bytes)
+  end
+end