xchan.rb 0.16.4

data/lib/xchan.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+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
+    def self.dump(str) = str.to_s
+    def self.load(str) = str.to_s
+  end
+
+  ##
+  # Returns an unlinked {Chan::Tempfile Chan::Tempfile} object
+  # that can be read from, and written to by the process that
+  # created it, inclusive of its child processes, but not of
+  # processes other than that.
+  #
+  # @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)
+    Chan::Tempfile.new(basename, tmpdir, perm: 0).tap(&:unlink)
+  end
+
+  def self.serializers
+    {
+      plain: lambda { Plain },
+      marshal: lambda { Marshal },
+      json: lambda {
+        require "json" unless defined?(JSON)
+        JSON
+      },
+      yaml: lambda {
+        require "yaml" unless defined?(YAML)
+        YAML
+      }
+    }
+  end
+end
+
+class Object
+  include Chan::Mixin
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "../setup"
+require "xchan"
+
+$stdout.sync = true
+ch = xchan
+pid = fork do
+  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
+
+##
+# Send a random number (from parent process)
+# Received random number (child process): XX

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "../setup"
+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)

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+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")
+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)

data/share/xchan.rb/examples/setup.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+libdir = File.expand_path File.join(__dir__, "..", "lib")
+$LOAD_PATH.unshift(libdir)

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

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

data/share/xchan.rb/examples/stress_tests/1_parallel_access_stress_test.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "../setup"
+require "xchan"
+
+pids = []
+ch = xchan
+pids.concat 50.times.map { fork { ch.send(["a" * rand(200)]) } }
+pids.concat 50.times.map { fork { print "PID: ", Process.pid, ", buf size:", ch.recv[0].size, "\n" } }
+pids.each { Process.wait(_1) }

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "../setup"
+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

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "../setup"
+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

data/test/readme_test.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+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,
+                 readme_example("serialization/1_serializers.rb").stdout
+  end
+
+  def test_read_operations_1_blocking_read
+    r = 'Send a random number \(from parent process\)\s*' \
+        'Received random number \(child process\): \d+'
+    assert_match Regexp.new(r),
+                 readme_example("read_operations/1_blocking_read.rb").stdout
+                                                                     .tr("\n", " ")
+  end
+
+  def test_write_operations_2_non_blocking_write
+    assert_equal ["Blocked - free send buffer\n"],
+                 readme_example("write_operations/2_nonblocking_write.rb").stdout
+                                                                          .each_line
+                                                                          .uniq
+  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*'
+    assert_match Regexp.new(r),
+                 readme_example("socket/2_options.rb").stdout
+                                                      .tr("\n", " ")
+  end
+
+  private
+
+  def readme_example(path)
+    examples_dir = File.join(Dir.getwd, "share", "xchan.rb", "examples")
+    example = File.join(examples_dir, path)
+    cmd "bundle exec ruby #{example}"
+  end
+end

data/test/setup.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require "timeout"
+require "xchan"
+require "test-unit"

data/test/xchan_test.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require_relative "setup"
+
+class Chan::Test < Test::Unit::TestCase
+  def setup
+    @ch = xchan ENV.fetch("SERIALIZER", "marshal").to_sym
+  end
+
+  def teardown
+    ch.close unless ch.closed?
+  end
+
+  private
+
+  def ch
+    @ch
+  end
+
+  def object
+    case ENV["SERIALIZER"]
+    when "plain" then "xchan"
+    else %w[xchan]
+    end
+  end
+
+  def object_size
+    ch.serializer.dump(object).bytesize
+  end
+end
+
+##
+# Chan::UNIXSocket#send
+class Chan::SendTest < Chan::Test
+  def test_send_return_value
+    assert_equal object_size, ch.send(object)
+  end
+
+  def test_send_with_multiple_objects
+    3.times { |i| Process.wait fork { ch.send(object) } }
+    assert_equal [object, object, object], 3.times.map { ch.recv }
+  end
+
+  def test_send_race_condition
+    pids = 4.times.map { fork { exit(ch.recv.to_i) } }
+    sleep(0.1 * 4)
+    pids.each.with_index(1) { ch.send(object) }
+    assert_equal pids.map { 42 }, pids.map { Process.wait2(_1).last.exitstatus }
+  end
+
+  def object
+    42.to_s
+  end
+end
+
+##
+# Chan::UNIXSocket#recv
+class Chan::RecvTest < Chan::Test
+  include Timeout
+
+  def test_recv_with_null_byte
+    ch.send(object.dup << "\x00")
+    assert_equal object.dup << "\x00", ch.recv
+  end
+
+  def test_that_recv_blocks
+    assert_raises(Timeout::Error) do
+      timeout(0.3) { ch.recv }
+    end
+  end
+end
+
+##
+# Chan::UNIXSocket#recv_nonblock
+class Chan::RecvNonBlockTest < Chan::Test
+  include Timeout
+
+  def test_recv_nonblock_with_empty_channel
+    assert_raise(Chan::WaitReadable) { ch.recv_nonblock }
+  end
+
+  def test_recv_nonblock_with_a_lock
+    ch.instance_variable_get(:@lock).lock
+    pid = fork do
+      ch.recv_nonblock
+      exit(1)
+    rescue Chan::WaitLockable
+      exit(0)
+    end
+    Process.wait(pid)
+    assert_equal 0, $?.exitstatus
+  end
+end
+
+##
+# Chan::UNIXSocket#empty?
+class Chan::EmptyTest < Chan::Test
+  def test_empty_with_empty_channel
+    assert_equal true, ch.empty?
+  end
+
+  def test_empty_with_one_object
+    ch.send(object)
+    assert_equal false, ch.empty?
+  end
+
+  def test_empty_after_recv
+    ch.send(object)
+    ch.recv
+    assert_equal true, ch.empty?
+  end
+
+  def test_empty_on_closed_channel
+    ch.send(object)
+    ch.close
+    assert_equal true, ch.empty?
+  end
+end
+
+##
+# Chan::UNIXSocket#size
+class Chan::SizeTest < Chan::Test
+  def test_size_with_one_object
+    ch.send(object)
+    assert_equal 1, ch.size
+  end
+
+  def test_size_with_two_objects
+    2.times { ch.send(object) }
+    assert_equal 2, ch.size
+  end
+
+  def test_size_after_recv
+    ch.send(object)
+    ch.recv
+    assert_equal 0, ch.size
+  end
+end
+
+##
+# Chan::UNIXSocket#to_a
+class Chan::ToArrayTest < Chan::Test
+  def test_to_a_with_splat
+    3.times { ch.send(object) }
+    assert_equal [object, object, object], splat(*ch)
+  end
+
+  def test_to_a_with_last
+    3.times { ch.send(object) }
+    assert_equal object, ch.to_a.last
+  end
+
+  def test_to_a_with_empty_channel
+    assert_equal [], ch.to_a
+  end
+
+  private
+
+  def splat(*args)
+    args
+  end
+end
+
+##
+# Chan::UNIXSocket#bytes_written
+class Chan::BytesWrittenTest < Chan::Test
+  def test_bytes_written_with_one_object
+    Process.wait fork { ch.send(object) }
+    assert_equal object_size, ch.bytes_written
+  end
+
+  def test_bytes_written_with_two_objects
+    2.times { Process.wait fork { ch.send(object) } }
+    assert_equal object_size * 2, ch.bytes_written
+  end
+end
+
+##
+# Chan::UNIXSocket#bytes_read
+class Chan::BytesReadTest < Chan::Test
+  def test_bytes_read_with_one_object
+    ch.send(object)
+    Process.wait fork { ch.recv }
+    assert_equal object_size, ch.bytes_read
+  end
+
+  def test_bytes_read_with_two_objects
+    2.times { ch.send(object) }
+    2.times { Process.wait fork { ch.recv } }
+    assert_equal object_size * 2, ch.bytes_read
+  end
+end

data/xchan.rb.gemspec

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "./lib/xchan/version"
+Gem::Specification.new do |gem|
+  gem.name = "xchan.rb"
+  gem.authors = ["0x1eef"]
+  gem.email = ["0x1eef@protonmail.com"]
+  gem.homepage = "https://github.com/0x1eef/xchan.rb#readme"
+  gem.version = Chan::VERSION
+  gem.licenses = ["0BSD"]
+  gem.files = `git ls-files`.split($/)
+  gem.require_paths = ["lib"]
+  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_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 "rake", "~> 13.1"
+end

metadata

@@ -0,0 +1,170 @@
+--- !ruby/object:Gem::Specification
+name: xchan.rb
+version: !ruby/object:Gem::Version
+  version: 0.16.4
+platform: ruby
+authors:
+- '0x1eef'
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-01-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lockf.rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.6
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.6
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.5.7
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.5.7
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: test-cmd.rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.1'
+description: An easy to use InterProcess Communication (IPC) library.
+email:
+- 0x1eef@protonmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/tests.yml"
+- ".gitignore"
+- ".gitlab-ci.yml"
+- ".projectile"
+- ".rubocop.yml"
+- ".yardopts"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile.rb
+- lib/xchan.rb
+- lib/xchan/bytes.rb
+- lib/xchan/mixin.rb
+- lib/xchan/stat.rb
+- lib/xchan/tempfile.rb
+- lib/xchan/unix_socket.rb
+- lib/xchan/version.rb
+- share/xchan.rb/examples/read_operations/1_blocking_read.rb
+- 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/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
+- test/readme_test.rb
+- test/setup.rb
+- test/xchan_test.rb
+- xchan.rb.gemspec
+homepage: https://github.com/0x1eef/xchan.rb#readme
+licenses:
+- 0BSD
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: An easy to use InterProcess Communication (IPC) library.
+test_files: []