polyphony 1.3 → 1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 537c28ec35d12c724a5f5ef4117ada1641d0b49b780757965615665bddbe995a
-  data.tar.gz: 5c11137a7a7dc6774ec815ec8b38791752f1beb939311b5968f0d0b242c7f8ad
+  metadata.gz: 91cce4703d1b930aa9b242373492a373abd6d49b5ce200f8828683538c15562b
+  data.tar.gz: c5c8af2ab5f4961b6379015b8d68f10c56dc5c466a44c0a0a4d6be4a93ab26b9
 SHA512:
-  metadata.gz: 912c4a3cea0a183350c939e588bba70656fcd14a07af6bd5912e3c2208cbb286150477d050482b030c494b0f87f21da7ec350c50f5bfee8e563bc21211143adc
-  data.tar.gz: c72b01fcef19a525cef49b277f0f1fe949956499be51f34f75fe1e87fc6efe9222a43ac96d282460610c3a82989934a0f661e78a27736120117c1ef391036dd6
+  metadata.gz: 5a9cb0b512efaae4b0454f3b5e99807657275a8d4c80dd8f527235c842c3131f4a38f4e4eefc174aeae1c2e7c6f879e9ccf8064e49b42dd69cb27d7780ff1780
+  data.tar.gz: 19977c5db508a5a5bdf1fa1f4b0db061436849c5d75f59c62764ae3bfd5426014e4e119e7306b68edf25c82cea9193f259c2e1403b1def825847614c003026dd

data/.yardopts

@@ -18,6 +18,7 @@
 ./ext/polyphony
 -
 docs/readme.md
+docs/installation.md
 docs/overview.md
 docs/tutorial.md
 docs/cancellation.md

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 1.4 2023-07-01
+
+- Implement concurrent `IO#close`
+- Improve docs
+- Use only positional arguments in `IO#read` and `IO#readpartial` (#109 @floriandejonckheere)
+
 ## 1.3 2023-06-23
 
 - Improve cancellation doc page

data/README.md

@@ -23,58 +23,24 @@
 ## What is Polyphony?
 
 Polyphony is a library for building concurrent applications in Ruby. Polyphony
-harnesses the power of [Ruby fibers](https://ruby-doc.org/core-2.5.1/Fiber.html)
-to provide a cooperative, sequential coroutine-based concurrency model. Under
-the hood, Polyphony uses
-[io_uring](https://unixism.net/loti/what_is_io_uring.html) or
+harnesses the power of [Ruby fibers](https://rubyapi.org/3.2/o/fiber) to provide
+a cooperative, sequential coroutine-based concurrency model. Under the hood,
+Polyphony uses [io_uring](https://unixism.net/loti/what_is_io_uring.html) or
 [libev](https://github.com/enki/libev) to maximize I/O performance.
 
 ## Features
 
-* Co-operative scheduling of concurrent tasks using Ruby fibers.
-* High-performance event reactor for handling I/O events and timers.
-* Natural, sequential programming style that makes it easy to reason about
-  concurrent code.
-* Abstractions and constructs for controlling the execution of concurrent code:
-  supervisors, cancel scopes, throttling, resource pools etc.
-* Code can use native networking classes and libraries, growing support for
-  third-party gems such as `pg` and `redis`.
-* Use stdlib classes such as `TCPServer`, `TCPSocket` and
-  `OpenSSL::SSL::SSLSocket`.
-* Competitive performance and scalability characteristics, in terms of both
-  throughput and memory consumption.
-
-## Installing
-
-### System Requirements
-
-In order to use Polyphony you need to have:
-
-- Linux or MacOS (support for Windows will come at a later stage)
-- Ruby (MRI) 3.1 or newer
-
-### Installing the Polyphony Gem
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'polyphony'
-```
-
-And then execute:
-
-```bash
-$ bundle
-```
-
-Or install it yourself as:
-
-```bash
-$ gem install polyphony
-```
+* Ruby fibers as the main unit of concurrency.
+* [Structured concurrency](https://en.wikipedia.org/wiki/Structured_concurrency)
+  coupled with robust exception handling.
+* Message passing between fibers, even across threads!
+* High-performance I/O using the core Ruby I/O classes and
+  [io_uring](https://unixism.net/loti/what_is_io_uring.html) with support for
+  [advanced I/O patterns](docs/advanced-io.md).
 
 ## Usage
 
+- [Installation](docs/installation.md)
 - [Overview](docs/overview.md)
 - [Tutorial](docs/tutorial.md)
 - [All About Cancellation: How to Stop Concurrent Operations](docs/cancellation.md)

data/docs/installation.md

@@ -0,0 +1,30 @@
+# @title Installation
+
+# Installation
+
+## System Requirements
+
+In order to use Polyphony you need to have:
+
+- Linux or MacOS (support for Windows will come at a later stage)
+- Ruby (MRI) 3.1 or newer
+
+## Installing the Polyphony Gem
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'polyphony'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install polyphony
+```

data/docs/readme.md

@@ -25,58 +25,24 @@
 ## What is Polyphony?
 
 Polyphony is a library for building concurrent applications in Ruby. Polyphony
-harnesses the power of [Ruby fibers](https://ruby-doc.org/core-2.5.1/Fiber.html)
-to provide a cooperative, sequential coroutine-based concurrency model. Under
-the hood, Polyphony uses
-[io_uring](https://unixism.net/loti/what_is_io_uring.html) or
+harnesses the power of [Ruby fibers](https://rubyapi.org/3.2/o/fiber) to provide
+a cooperative, sequential coroutine-based concurrency model. Under the hood,
+Polyphony uses [io_uring](https://unixism.net/loti/what_is_io_uring.html) or
 [libev](https://github.com/enki/libev) to maximize I/O performance.
 
 ## Features
 
-* Co-operative scheduling of concurrent tasks using Ruby fibers.
-* High-performance event reactor for handling I/O events and timers.
-* Natural, sequential programming style that makes it easy to reason about
-  concurrent code.
-* Abstractions and constructs for controlling the execution of concurrent code:
-  supervisors, cancel scopes, throttling, resource pools etc.
-* Code can use native networking classes and libraries, growing support for
-  third-party gems such as `pg` and `redis`.
-* Use stdlib classes such as `TCPServer`, `TCPSocket` and
-  `OpenSSL::SSL::SSLSocket`.
-* Competitive performance and scalability characteristics, in terms of both
-  throughput and memory consumption.
-
-## Installing
-
-### System Requirements
-
-In order to use Polyphony you need to have:
-
-- Linux or MacOS (support for Windows will come at a later stage)
-- Ruby (MRI) 3.1 or newer
-
-### Installing the Polyphony Gem
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'polyphony'
-```
-
-And then execute:
-
-```bash
-$ bundle
-```
-
-Or install it yourself as:
-
-```bash
-$ gem install polyphony
-```
+* Ruby fibers as the main unit of concurrency.
+* [Structured concurrency](https://en.wikipedia.org/wiki/Structured_concurrency)
+  coupled with robust exception handling.
+* Message passing between fibers, even across threads!
+* High-performance I/O using the core Ruby I/O classes and
+  [io_uring](https://unixism.net/loti/what_is_io_uring.html) with support for
+  {file:/docs/advanced-io.md advanced I/O patterns}.
 
 ## Usage
 
+- {file:/docs/installation.md       Installation}
 - {file:/docs/overview.md           Overview}
 - {file:/docs/tutorial.md           Tutorial}
 - {file:/docs/cancellation.md       All About Cancellation: How to Stop Concurrent Operations}

data/examples/core/stages.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'polyphony'
+
+# Based on the design of Elixir's GenStage
+
+class Producer
+  def initialize(mod, *a, **b)
+    extend(mod)
+    setup(*a, **b)
+    @_fiber = spin do
+      receive_loop do |msg|
+        case msg[:kind]
+        when :demand
+          items = handle_demand(msg[:limit])
+          msg[:peer] << items
+        end
+      end
+    end
+  end
+
+  def <<(msg)
+    @_fiber << msg
+  end
+end
+
+module Counter
+  def setup(counter = 0)
+    @counter = counter
+  end
+
+  def handle_demand(demand)
+    events = (@counter...@counter + demand).to_a
+    @counter += demand
+    events
+  end
+end
+
+counter = Producer.new(Counter, 0)
+
+class Consumer
+  def initialize(mod, *a, **b)
+    extend(mod)
+    setup(*a, **b) if respond_to?(:setup)
+    @_fiber = spin do
+      while true
+        items = get_items
+        handle_items(items)
+      end
+    end
+
+    @max_demand = 10
+    @min_demand = 5
+  end
+
+  def subscribe(upstream)
+    @upstream = upstream
+  end
+
+  private
+
+  def get_items
+    send_demand(@max_demand) if !@sent_demand
+    items = receive
+    send_demand(@min_demand)
+    items
+  end
+
+  def send_demand(demand)
+    if @upstream
+      @upstream << { peer: Fiber.current, kind: :demand, limit: demand }
+      @sent_demand = true
+    else
+      sleep 0.1
+    end
+  end
+end
+
+module Printer
+  def handle_items(items)
+    sleep 1
+    puts "got: #{items.join(' ')}"
+  end
+end
+
+# counter << { peer: Fiber.current, kind: :demand, limit: 10 }
+# r = receive
+
+# p r: r
+
+# counter << { peer: Fiber.current, kind: :demand, limit: 10 }
+# r = receive
+# p r: r
+
+printer = Consumer.new(Printer)
+printer.subscribe(counter)
+
+sleep

data/ext/polyphony/backend_common.c

@@ -458,7 +458,7 @@ VALUE Backend_stats(VALUE self) {
 
 VALUE Backend_verify_blocking_mode(VALUE self, VALUE io, VALUE blocking) {
   io_verify_blocking_mode(io, rb_io_descriptor(io), blocking);
-  return self;
+  return io;
 }
 
 void backend_setup_stats_symbols(void) {

data/ext/polyphony/backend_io_uring.c

@@ -1363,34 +1363,33 @@ VALUE Backend_wait_io(VALUE self, VALUE io, VALUE write) {
   return self;
 }
 
-// VALUE Backend_close(VALUE self, VALUE io) {
-//   Backend_t *backend;
-//   rb_io_t *fptr;
-//   VALUE resume_value = Qnil;
-//   op_context_t *ctx;
-//   struct io_uring_sqe *sqe;
-//   int result;
-//   int completed;
-
-//   if (fd < 0) return Qnil;
-
-//   io_unset_nonblock(io, fd);
-
-//   ctx = context_store_acquire(&backend->store, OP_CLOSE);
-//   sqe = io_uring_backend_get_sqe(backend);
-//   io_uring_prep_close(sqe, fd);
-//   result = io_uring_backend_defer_submit_and_await(backend, sqe, ctx, &resume_value);
-//   completed = context_store_release(&backend->store, ctx);
-//   RAISE_IF_EXCEPTION(resume_value);
-//   if (!completed) return resume_value;
-//   RB_GC_GUARD(resume_value);
-
-//   if (result < 0) rb_syserr_fail(-result, strerror(-result));
-
-//   fptr_finalize(fptr);
-//   // fd = -1;
-//   return io;
-// }
+VALUE Backend_close(VALUE self, VALUE io) {
+  Backend_t *backend;
+  rb_io_t *fptr;
+  VALUE resume_value = Qnil;
+  op_context_t *ctx;
+  struct io_uring_sqe *sqe;
+  int result;
+  int completed;
+  int fd = fd_from_io(io, &fptr, 0, 0);
+  if (fd < 0) return Qnil;
+
+  GetBackend(self, backend);
+  ctx = context_store_acquire(&backend->store, OP_CLOSE);
+  sqe = io_uring_backend_get_sqe(backend);
+  io_uring_prep_close(sqe, fd);
+  result = io_uring_backend_defer_submit_and_await(backend, sqe, ctx, &resume_value);
+  completed = context_store_release(&backend->store, ctx);
+  RAISE_IF_EXCEPTION(resume_value);
+  if (!completed) return resume_value;
+  RB_GC_GUARD(resume_value);
+
+  if (result < 0) rb_syserr_fail(-result, strerror(-result));
+
+  fptr_finalize(fptr);
+  // fd = -1;
+  return io;
+}
 
 inline struct __kernel_timespec double_to_timespec(double duration) {
   double duration_integral;
@@ -2015,7 +2014,7 @@ void Init_Backend(void) {
   rb_define_method(cBackend, "wait_io", Backend_wait_io, 2);
   rb_define_method(cBackend, "waitpid", Backend_waitpid, 1);
   rb_define_method(cBackend, "write", Backend_write_m, -1);
-  // rb_define_method(cBackend, "close", Backend_close, 1);
+  rb_define_method(cBackend, "close", Backend_close, 1);
 
   SYM_io_uring = ID2SYM(rb_intern("io_uring"));
   SYM_send = ID2SYM(rb_intern("send"));

data/ext/polyphony/backend_libev.c

@@ -1135,6 +1135,31 @@ VALUE Backend_wait_io(VALUE self, VALUE io, VALUE write) {
   return libev_wait_fd(backend, fd, events, 1);
 }
 
+VALUE Backend_close(VALUE self, VALUE io) {
+  Backend_t *backend;
+  rb_io_t *fptr;
+  VALUE resume_value = Qnil;
+  int result;
+  int fd = fd_from_io(io, &fptr, 0, 0);
+  if (fd < 0) return Qnil;
+
+  GetBackend(self, backend);
+
+  result = close(fd);
+  if (result == -1) {
+    int err = errno;
+    rb_syserr_fail(err, strerror(err));
+  }
+
+  resume_value = backend_snooze(&backend->base);
+  RAISE_IF_EXCEPTION(resume_value);
+  RB_GC_GUARD(resume_value);
+
+  fptr_finalize(fptr);
+  // fd = -1;
+  return io;
+}
+
 struct libev_timer {
   struct ev_timer timer;
   VALUE fiber;
@@ -1654,6 +1679,7 @@ void Init_Backend(void) {
   rb_define_method(cBackend, "wait_io", Backend_wait_io, 2);
   rb_define_method(cBackend, "waitpid", Backend_waitpid, 1);
   rb_define_method(cBackend, "write", Backend_write_m, -1);
+  rb_define_method(cBackend, "close", Backend_close, 1);
 
   SYM_libev = ID2SYM(rb_intern("libev"));
 

data/ext/polyphony/polyphony.c

@@ -404,9 +404,26 @@ VALUE Polyphony_raw_buffer_size(VALUE self, VALUE buffer) {
   return INT2FIX(buffer_spec->len);
 }
 
-// VALUE Polyphony_backend_close(VALUE self, VALUE io) {
-//   return Backend_close(BACKEND(), io);
-// }
+/* Closes the given IO.
+ *
+ * @param io [IO, Polyphony::Pipe] IO instance
+ * @return [IO, Polyphony::Pipe] given IO
+ */
+
+VALUE Polyphony_backend_close(VALUE self, VALUE io) {
+  return Backend_close(BACKEND(), io);
+}
+
+/* Ensures the given IO is in blocking/non-blocking mode.
+ *
+ * @param io [IO, Polyphony::Pipe] IO instance
+ * @param blocking [boolean] true for blocking, false for non-blocking mode
+ * @return [IO, Polyphony::Pipe] given IO
+ */
+
+VALUE Polyphony_backend_verify_blocking_mode(VALUE self, VALUE io, VALUE blocking) {
+  return Backend_verify_blocking_mode(BACKEND(), io, blocking);
+}
 
 void Init_Polyphony(void) {
   mPolyphony = rb_define_module("Polyphony");
@@ -448,8 +465,8 @@ void Init_Polyphony(void) {
   rb_define_singleton_method(mPolyphony, "backend_wait_io", Polyphony_backend_wait_io, 2);
   rb_define_singleton_method(mPolyphony, "backend_waitpid", Polyphony_backend_waitpid, 1);
   rb_define_singleton_method(mPolyphony, "backend_write", Polyphony_backend_write, -1);
-  // rb_define_singleton_method(mPolyphony, "backend_close", Polyphony_backend_close, 1);
-  rb_define_singleton_method(mPolyphony, "backend_verify_blocking_mode", Backend_verify_blocking_mode, 2);
+  rb_define_singleton_method(mPolyphony, "backend_close", Polyphony_backend_close, 1);
+  rb_define_singleton_method(mPolyphony, "backend_verify_blocking_mode", Polyphony_backend_verify_blocking_mode, 2);
 
   rb_define_singleton_method(mPolyphony, "__with_raw_buffer__", Polyphony_with_raw_buffer, 1);
   rb_define_singleton_method(mPolyphony, "__raw_buffer_get__", Polyphony_raw_buffer_get, -1);

data/ext/polyphony/polyphony.h

@@ -133,7 +133,7 @@ VALUE Backend_wait_io(VALUE self, VALUE io, VALUE write);
 VALUE Backend_waitpid(VALUE self, VALUE pid);
 VALUE Backend_write(VALUE self, VALUE io, VALUE str);
 VALUE Backend_write_m(int argc, VALUE *argv, VALUE self);
-// VALUE Backend_close(VALUE self, VALUE io);
+VALUE Backend_close(VALUE self, VALUE io);
 
 VALUE Backend_poll(VALUE self, VALUE blocking);
 VALUE Backend_wait_event(VALUE self, VALUE raise_on_exception);

data/lib/polyphony/core/debug.rb

@@ -52,7 +52,7 @@ module Polyphony
 
       # Converts an event (expressed as an array) to a hash.
       #
-      # @param e [Array] event as emitted by the backend
+      # @param event [Array] event as emitted by the backend
       # @return [Hash] event hash
       def trace_event_info(event)
         {
@@ -65,7 +65,7 @@ module Polyphony
 
       # Returns an event hash for a `:block` event.
       #
-      # @param e [Array] event array
+      # @param event [Array] event array
       # @return [Hash] event hash
       def event_props_block(event)
         {
@@ -76,7 +76,7 @@ module Polyphony
 
       # Returns an event hash for a `:enter_poll` event.
       #
-      # @param e [Array] event array
+      # @param _event [Array] event array
       # @return [Hash] event hash
       def event_props_enter_poll(_event)
         {}
@@ -84,7 +84,7 @@ module Polyphony
 
       # Returns an event hash for a `:leave_poll` event.
       #
-      # @param e [Array] event array
+      # @param _event [Array] event array
       # @return [Hash] event hash
       def event_props_leave_poll(_event)
         {}
@@ -92,7 +92,7 @@ module Polyphony
 
       # Returns an event hash for a `:schedule` event.
       #
-      # @param e [Array] event array
+      # @param event [Array] event array
       # @return [Hash] event hash
       def event_props_schedule(event)
         {
@@ -105,7 +105,7 @@ module Polyphony
 
       # Returns an event hash for a `:spin` event.
       #
-      # @param e [Array] event array
+      # @param event [Array] event array
       # @return [Hash] event hash
       def event_props_spin(event)
         {
@@ -117,7 +117,7 @@ module Polyphony
 
       # Returns an event hash for a `:terminate` event.
       #
-      # @param e [Array] event array
+      # @param event [Array] event array
       # @return [Hash] event hash
       def event_props_terminate(event)
         {
@@ -128,7 +128,7 @@ module Polyphony
 
       # Returns an event hash for a `:unblock` event.
       #
-      # @param e [Array] event array
+      # @param event [Array] event array
       # @return [Hash] event hash
       def event_props_unblock(event)
         {

data/lib/polyphony/extensions/io.rb

@@ -197,7 +197,7 @@ class ::IO
   alias_method :orig_read, :read
 
   # @!visibility private
-  def read(len = nil, buf = nil, buffer_pos: 0)
+  def read(len = nil, buf = nil, buffer_pos = 0)
     return '' if len == 0
     return Polyphony.backend_read(self, buf, len, true, buffer_pos) if buf
 
@@ -214,7 +214,7 @@ class ::IO
   alias_method :orig_readpartial, :read
 
   # @!visibility private
-  def readpartial(len, str = +'', buffer_pos: 0, raise_on_eof: true)
+  def readpartial(len, str = +'', buffer_pos = 0, raise_on_eof = true)
     result = Polyphony.backend_read(self, str, len, false, buffer_pos)
     raise EOFError if !result && raise_on_eof
 
@@ -255,7 +255,7 @@ class ::IO
       idx = @read_buffer.index(sep)
       return @read_buffer.slice!(0, idx + sep_size) if idx
 
-      result = readpartial(8192, @read_buffer, buffer_pos: -1)
+      result = readpartial(8192, @read_buffer, -1)
       return nil unless result
     end
   rescue EOFError
@@ -280,7 +280,7 @@ class ::IO
         yield line
       end
 
-      result = readpartial(8192, @read_buffer, buffer_pos: -1)
+      result = readpartial(8192, @read_buffer, -1)
       return self if !result
     end
   rescue EOFError
@@ -427,6 +427,19 @@ class ::IO
     Polyphony.backend_splice(src, self, maxlen)
   end
 
+  # @!visibility private
+  alias_method :orig_close, :close
+
+  # Closes the IO instance
+  #
+  # @return [void]
+  def close
+    return if closed?
+
+    Polyphony.backend_close(self)
+    nil
+  end
+
   if RUBY_PLATFORM =~ /linux/
     # Tees data from the given IO.
     #

data/lib/polyphony/extensions/kernel.rb

@@ -5,6 +5,22 @@ require 'open3'
 module Polyphony
   # Intercepts calls to #trap
   module TrapInterceptor
+    # Installs a signal handler. If a block is given (or the command parameter
+    # is a Proc or a callable), it is executed inside an out-of-band,
+    # prioritized fiber.
+    #
+    # If the command is the string “IGNORE” or “SIG_IGN”, the signal will be
+    # ignored. If the command is “DEFAULT” or “SIG_DFL”, the Ruby’s default
+    # handler will be invoked. If the command is “EXIT”, the script will be
+    # terminated by the signal. If the command is “SYSTEM_DEFAULT”, the
+    # operating system’s default handler will be invoked. Otherwise, the given
+    # command or block will be run. The special signal name “EXIT” or signal
+    # number zero will be invoked just prior to program termination.
+    #
+    # trap returns the previous handler for the given signal.
+    #
+    # @param sig [String, Symbol, Integer] signal name or number
+    # @param command [String, Proc] command to perform
     def trap(sig, command = nil, &block)
       return super(sig, command) if command.is_a? String
 

data/lib/polyphony/extensions/openssl.rb

@@ -90,7 +90,7 @@ class ::OpenSSL::SSL::SSLSocket
 
   # Reads from the socket. If `maxlen` is given, reads up to `maxlen` bytes from
   # the socket, otherwise reads to `EOF`. If `buf` is given, it is used as the
-  # buffer to read into, otherwise a new string is allocated. If `buf_pos` is
+  # buffer to read into, otherwise a new string is allocated. If `buffer_pos` is
   # given, reads into the given offset (in bytes) in the given buffer. If the
   # given buffer offset is negative, it is calculated from the current end of
   # the buffer (`-1` means the read data will be appended to the end of the
@@ -101,21 +101,21 @@ class ::OpenSSL::SSL::SSLSocket
   #
   # @param maxlen [Integer, nil] maximum bytes to read from socket
   # @param buf [String, nil] buffer to read into
-  # @param buf_pos [Number] buffer position to read into
+  # @param buffer_pos [Number] buffer position to read into
   # @return [String] buffer used for reading
-  def read(maxlen = nil, buf = nil, buffer_pos: 0)
-    return readpartial(maxlen, buf, buffer_pos:) if buf
+  def read(maxlen = nil, buf = nil, buffer_pos = 0)
+    return readpartial(maxlen, buf, buffer_pos) if buf
 
     buf = +''
     return readpartial(maxlen, buf) if maxlen
 
-    readpartial(4096, buf, buffer_pos: -1) while true
+    readpartial(4096, buf, -1) while true
   rescue EOFError
     buf
   end
 
   # Reads up to `maxlen` from the socket. If `buf` is given, it is used as the
-  # buffer to read into, otherwise a new string is allocated. If `buf_pos` is
+  # buffer to read into, otherwise a new string is allocated. If `buffer_pos` is
   # given, reads into the given offset (in bytes) in the given buffer. If the
   # given buffer offset is negative, it is calculated from the current end of
   # the buffer (`-1` means the read data will be appended to the end of the
@@ -127,16 +127,16 @@ class ::OpenSSL::SSL::SSLSocket
   #
   # @param maxlen [Integer, nil] maximum bytes to read from socket
   # @param buf [String, nil] buffer to read into
-  # @param buf_pos [Number] buffer position to read into
+  # @param buffer_pos [Number] buffer position to read into
   # @param raise_on_eof [bool] whether to raise an exception on `EOF`
   # @return [String, nil] buffer used for reading or nil on `EOF`
-  def readpartial(maxlen, buf = +'', buffer_pos: 0, raise_on_eof: true)
-    if buf_pos != 0
+  def readpartial(maxlen, buf = +'', buffer_pos = 0, raise_on_eof = true)
+    if buffer_pos != 0
       if (result = sysread(maxlen, +''))
-        if buf_pos == -1
+        if buffer_pos == -1
           result = buf + result
         else
-          result = buf[0...buf_pos] + result
+          result = buf[0...buffer_pos] + result
         end
       end
     else

data/lib/polyphony/extensions/pipe.rb

@@ -41,9 +41,9 @@ class Polyphony::Pipe
   #
   # @param len [Integer, nil] maximum bytes to read
   # @param buf [String, nil] buffer to read into
-  # @param buf_pos [Integer] buffer position to read into
+  # @param buffer_pos [Integer] buffer position to read into
   # @return [String] read data
-  def read(len = nil, buf = nil, buffer_pos: 0)
+  def read(len = nil, buf = nil, buffer_pos = 0)
     return Polyphony.backend_read(self, buf, len, true, buffer_pos) if buf
 
     @read_buffer ||= +''
@@ -59,10 +59,10 @@ class Polyphony::Pipe
   #
   # @param len [Integer, nil] maximum bytes to read
   # @param buf [String, nil] buffer to read into
-  # @param buf_pos [Integer] buffer position to read into
+  # @param buffer_pos [Integer] buffer position to read into
   # @param raise_on_eof [boolean] whether to raise an error if EOF is detected
   # @return [String] read data
-  def readpartial(len, buf = +'', buffer_pos: 0, raise_on_eof: true)
+  def readpartial(len, buf = +'', buffer_pos = 0, raise_on_eof = true)
     result = Polyphony.backend_read(self, buf, len, false, buffer_pos)
     raise EOFError if !result && raise_on_eof
 
@@ -104,7 +104,7 @@ class Polyphony::Pipe
       idx = @read_buffer.index(sep)
       return @read_buffer.slice!(0, idx + sep_size) if idx
 
-      result = readpartial(8192, @read_buffer, buffer_pos: -1)
+      result = readpartial(8192, @read_buffer, -1)
       return nil unless result
     end
   rescue EOFError

data/lib/polyphony/extensions/socket.rb

@@ -59,7 +59,7 @@ class ::Socket < ::BasicSocket
 
   # Reads from the socket. If `maxlen` is given, reads up to `maxlen` bytes from
   # the socket, otherwise reads to `EOF`. If `buf` is given, it is used as the
-  # buffer to read into, otherwise a new string is allocated. If `buf_pos` is
+  # buffer to read into, otherwise a new string is allocated. If `buffer_pos` is
   # given, reads into the given offset (in bytes) in the given buffer. If the
   # given buffer offset is negative, it is calculated from the current end of
   # the buffer (`-1` means the read data will be appended to the end of the
@@ -70,9 +70,9 @@ class ::Socket < ::BasicSocket
   #
   # @param len [Integer, nil] maximum bytes to read from socket
   # @param buf [String, nil] buffer to read into
-  # @param buf_pos [Number] buffer position to read into
+  # @param buffer_pos [Number] buffer position to read into
   # @return [String] buffer used for reading
-  def read(len = nil, buf = nil, buffer_pos: 0)
+  def read(len = nil, buf = nil, buffer_pos = 0)
     return '' if len == 0
     return Polyphony.backend_read(self, buf, len, true, buffer_pos) if buf
 
@@ -148,7 +148,7 @@ class ::Socket < ::BasicSocket
   end
 
   # Reads up to `maxlen` from the socket. If `buf` is given, it is used as the
-  # buffer to read into, otherwise a new string is allocated. If `buf_pos` is
+  # buffer to read into, otherwise a new string is allocated. If `buffer_pos` is
   # given, reads into the given offset (in bytes) in the given buffer. If the
   # given buffer offset is negative, it is calculated from the current end of
   # the buffer (`-1` means the read data will be appended to the end of the
@@ -160,10 +160,10 @@ class ::Socket < ::BasicSocket
   #
   # @param maxlen [Integer, nil] maximum bytes to read from socket
   # @param buf [String, nil] buffer to read into
-  # @param buf_pos [Number] buffer position to read into
+  # @param buffer_pos [Number] buffer position to read into
   # @param raise_on_eof [bool] whether to raise an exception on `EOF`
   # @return [String, nil] buffer used for reading or nil on `EOF`
-  def readpartial(maxlen, buf = +'', buffer_pos: 0, raise_on_eof: true)
+  def readpartial(maxlen, buf = +'', buffer_pos = 0, raise_on_eof = true)
     result = Polyphony.backend_recv(self, buf, maxlen, buffer_pos)
     raise EOFError if !result && raise_on_eof
 
@@ -320,7 +320,7 @@ class ::TCPSocket < ::IPSocket
 
   # Reads from the socket. If `maxlen` is given, reads up to `maxlen` bytes from
   # the socket, otherwise reads to `EOF`. If `buf` is given, it is used as the
-  # buffer to read into, otherwise a new string is allocated. If `buf_pos` is
+  # buffer to read into, otherwise a new string is allocated. If `buffer_pos` is
   # given, reads into the given offset (in bytes) in the given buffer. If the
   # given buffer offset is negative, it is calculated from the current end of
   # the buffer (`-1` means the read data will be appended to the end of the
@@ -331,9 +331,9 @@ class ::TCPSocket < ::IPSocket
   #
   # @param len [Integer, nil] maximum bytes to read from socket
   # @param buf [String, nil] buffer to read into
-  # @param buf_pos [Number] buffer position to read into
+  # @param buffer_pos [Number] buffer position to read into
   # @return [String] buffer used for reading
-  def read(len = nil, buf = nil, buffer_pos: 0)
+  def read(len = nil, buf = nil, buffer_pos = 0)
     return '' if len == 0
     return Polyphony.backend_read(self, buf, len, true, buffer_pos) if buf
 
@@ -391,7 +391,7 @@ class ::TCPSocket < ::IPSocket
   end
 
   # Reads up to `maxlen` from the socket. If `buf` is given, it is used as the
-  # buffer to read into, otherwise a new string is allocated. If `buf_pos` is
+  # buffer to read into, otherwise a new string is allocated. If `buffer_pos` is
   # given, reads into the given offset (in bytes) in the given buffer. If the
   # given buffer offset is negative, it is calculated from the current end of
   # the buffer (`-1` means the read data will be appended to the end of the
@@ -403,10 +403,10 @@ class ::TCPSocket < ::IPSocket
   #
   # @param maxlen [Integer, nil] maximum bytes to read from socket
   # @param buf [String, nil] buffer to read into
-  # @param buf_pos [Number] buffer position to read into
+  # @param buffer_pos [Number] buffer position to read into
   # @param raise_on_eof [bool] whether to raise an exception on `EOF`
   # @return [String, nil] buffer used for reading or nil on `EOF`
-  def readpartial(maxlen, buf = +'', buffer_pos: 0, raise_on_eof: true)
+  def readpartial(maxlen, buf = +'', buffer_pos = 0, raise_on_eof = true)
     result = Polyphony.backend_recv(self, buf, maxlen, buffer_pos)
     raise EOFError if !result && raise_on_eof
 
@@ -526,7 +526,7 @@ class ::UNIXSocket < ::BasicSocket
 
   # Reads from the socket. If `maxlen` is given, reads up to `maxlen` bytes from
   # the socket, otherwise reads to `EOF`. If `buf` is given, it is used as the
-  # buffer to read into, otherwise a new string is allocated. If `buf_pos` is
+  # buffer to read into, otherwise a new string is allocated. If `buffer_pos` is
   # given, reads into the given offset (in bytes) in the given buffer. If the
   # given buffer offset is negative, it is calculated from the current end of
   # the buffer (`-1` means the read data will be appended to the end of the
@@ -537,9 +537,9 @@ class ::UNIXSocket < ::BasicSocket
   #
   # @param len [Integer, nil] maximum bytes to read from socket
   # @param buf [String, nil] buffer to read into
-  # @param buf_pos [Number] buffer position to read into
+  # @param buffer_pos [Number] buffer position to read into
   # @return [String] buffer used for reading
-  def read(len = nil, buf = nil, buffer_pos: 0)
+  def read(len = nil, buf = nil, buffer_pos = 0)
     return '' if len == 0
     return Polyphony.backend_read(self, buf, len, true, buffer_pos) if buf
 
@@ -623,7 +623,7 @@ class ::UNIXSocket < ::BasicSocket
   end
 
   # Reads up to `maxlen` from the socket. If `buf` is given, it is used as the
-  # buffer to read into, otherwise a new string is allocated. If `buf_pos` is
+  # buffer to read into, otherwise a new string is allocated. If `buffer_pos` is
   # given, reads into the given offset (in bytes) in the given buffer. If the
   # given buffer offset is negative, it is calculated from the current end of
   # the buffer (`-1` means the read data will be appended to the end of the
@@ -635,10 +635,10 @@ class ::UNIXSocket < ::BasicSocket
   #
   # @param maxlen [Integer, nil] maximum bytes to read from socket
   # @param buf [String, nil] buffer to read into
-  # @param buf_pos [Number] buffer position to read into
+  # @param buffer_pos [Number] buffer position to read into
   # @param raise_on_eof [bool] whether to raise an exception on `EOF`
   # @return [String, nil] buffer used for reading or nil on `EOF`
-  def readpartial(maxlen, buf = +'', buffer_pos: 0, raise_on_eof: true)
+  def readpartial(maxlen, buf = +'', buffer_pos = 0, raise_on_eof = true)
     result = Polyphony.backend_recv(self, buf, maxlen, buffer_pos)
     raise EOFError if !result && raise_on_eof
 

data/lib/polyphony/version.rb

@@ -2,5 +2,5 @@
 
 module Polyphony
   # @!visibility private
-  VERSION = '1.3'
+  VERSION = '1.4'
 end

data/test/stress.rb

@@ -3,11 +3,16 @@
 count = ARGV[0] ? ARGV[0].to_i : 100
 test_name = ARGV[1]
 
-$test_cmd = +'ruby test/test_scenarios.rb'
+$test_cmd = +'ruby test/run.rb'
 if test_name
   $test_cmd << " --name #{test_name}"
 end
 
+puts '*' * 40
+puts
+puts $test_cmd
+puts
+
 def run_test(count)
   puts "#{count}: running tests..."
   # sleep 1

data/test/test_backend.rb

@@ -544,4 +544,11 @@ class BackendChainTest < MiniTest::Test
     # released properly before raising the error (for the time being this has
     # been verified manually).
   end
+
+  def test_backend_close
+    r, w = IO.pipe
+    w << 'abc'
+    Thread.backend.close(w)
+    assert w.closed?
+  end
 end

data/test/test_global_api.rb

@@ -137,7 +137,7 @@ class MoveOnAfterTest < MiniTest::Test
     t1 = monotonic_clock
 
     assert_nil v
-    assert_in_range 0.012..0.025, t1 - t0 if IS_LINUX
+    assert_in_range 0.012..0.030, t1 - t0 if IS_LINUX
   end
 
   def test_nested_move_on_after
@@ -161,7 +161,7 @@ class MoveOnAfterTest < MiniTest::Test
     end
     t1 = monotonic_clock
     assert_equal 2, o
-    assert_in_range 0.008..0.025, t1 - t0 if IS_LINUX
+    assert_in_range 0.008..0.035, t1 - t0 if IS_LINUX
   end
 end
 

data/test/test_io.rb

@@ -89,7 +89,7 @@ class IOTest < MiniTest::Test
 
     buf = +'def'
     o << 'foobar'
-    assert_equal 'deffoobar', i.read(6, buf, buffer_pos: -1)
+    assert_equal 'deffoobar', i.read(6, buf, -1)
     assert_equal 'deffoobar', buf
   end
 

data/test/test_signal.rb

@@ -4,6 +4,10 @@ require_relative 'helper'
 
 class SignalTrapTest < Minitest::Test
   def test_signal_handler_trace
+    if Thread.current.backend.kind != :io_uring
+      skip "Skipping signal handler trace because Backend_close on libev behaves differently"
+    end
+
     i1, o1 = IO.pipe
     i2, o2 = IO.pipe
     pid = Process.pid
@@ -39,16 +43,21 @@ class SignalTrapTest < Minitest::Test
     end
 
     expected = [
-      [:block, :main],
+      [:block,      :main],
+      [:enter_poll, :main],
+      [:schedule,   :main],
+      [:leave_poll, :main],
+      [:unblock,    :main],
+      [:block,      :main],
       [:enter_poll, :main],
       [:leave_poll, :main],
-      [:unblock, :oob],
-      [:terminate, :oob],
-      [:block, :oob],
+      [:unblock,    :oob],
+      [:terminate,  :oob],
+      [:block,      :oob],
       [:enter_poll, :oob],
-      [:schedule, :main],
+      [:schedule,   :main],
       [:leave_poll, :oob],
-      [:unblock, :main]
+      [:unblock,    :main]
     ]
     if Thread.backend.kind == :libev
       expected += [

data/test/test_socket.rb

@@ -73,12 +73,8 @@ class TCPSocketTest < MiniTest::Test
   def test_read
     port, server = start_tcp_server_on_random_port
     server_fiber = spin do
-      while (socket = server.accept)
-        spin do
-          while (data = socket.readpartial(8192))
-            socket << data
-          end
-        end
+      server.accept_loop do |socket|
+        spin { socket.recv_loop { |data| socket << data } }
       end
     end
 
@@ -98,7 +94,7 @@ class TCPSocketTest < MiniTest::Test
 
     buf = +'def'
     client << 'foobar'
-    assert_equal 'deffoobar', client.read(6, buf, buffer_pos: -1)
+    assert_equal 'deffoobar', client.read(6, buf, -1)
     assert_equal 'deffoobar', buf
 
     client.close

data/test/test_timer.rb

@@ -73,7 +73,7 @@ class TimerCancelAfterTest < MiniTest::Test
       end
     end
     t1 = Time.now
-    assert_in_range 0.01..0.03, t1 - t0 if IS_LINUX
+    assert_in_range 0.01..0.04, t1 - t0 if IS_LINUX
   end
 
   def test_timer_cancel_after_with_reset

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: polyphony
 version: !ruby/object:Gem::Version
-  version: '1.3'
+  version: '1.4'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-06-23 00:00:00.000000000 Z
+date: 2023-07-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler
@@ -191,6 +191,7 @@ files:
 - docs/extending.md
 - docs/faq.md
 - docs/fiber-scheduling.md
+- docs/installation.md
 - docs/overview.md
 - docs/readme.md
 - docs/tutorial.md
@@ -234,6 +235,7 @@ files:
 - examples/core/shutdown_all_children.rb
 - examples/core/spin.rb
 - examples/core/spin_error_backtrace.rb
+- examples/core/stages.rb
 - examples/core/stream_mockup.rb
 - examples/core/supervise-process.rb
 - examples/core/supervisor.rb