polyphony 0.99.5 → 1.0

data/lib/polyphony/extensions/object.rb

@@ -1,8 +1,289 @@
 # frozen_string_literal: true
 
-require_relative '../core/global_api'
+require_relative '../core/throttler'
 
 # Object extensions (methods available to all objects / call sites)
 class ::Object
-  include Polyphony::GlobalAPI
+  # Spins up a fiber that will run the given block after sleeping for the
+  # given delay.
+  #
+  # @param interval [Number] delay in seconds before running the given block
+  # @return [Fiber] spun fiber
+  def after(interval, &block)
+    spin do
+      sleep interval
+      block.()
+    end
+  end
+
+  # Runs the given block after setting up a cancellation timer for
+  # cancellation. If the cancellation timer elapses, the execution will be
+  # interrupted with an exception defaulting to `Polyphony::Cancel`.
+  #
+  # This method should be used when a timeout should cause an exception to be
+  # propagated down the call stack or up the fiber tree.
+  #
+  # Example of normal use:
+  #
+  #   def read_from_io_with_timeout(io)
+  #     cancel_after(10) { io.read }
+  #   rescue Polyphony::Cancel
+  #     nil
+  #   end
+  #
+  # The timeout period can be reset by passing a block that takes a single
+  # argument. The block will be provided with the canceller fiber. To reset
+  # the timeout, use `Fiber#reset`, as shown in the following example:
+  #
+  #   cancel_after(10) do |timeout|
+  #     loop do
+  #       msg = socket.gets
+  #       timeout.reset
+  #       handle_msg(msg)
+  #     end
+  #   end
+  #
+  # @overload cancel_after(interval)
+  #   @param interval [Number] timout in seconds
+  #   @yield [Fiber] timeout fiber
+  #   @return [any] block's return value
+  # @overload cancel_after(interval, with_exception: exception)
+  #   @param interval [Number] timout in seconds
+  #   @param with_exception [Class, Exception] exception or exception class
+  #   @yield [Fiber] timeout fiber
+  #   @return [any] block's return value
+  # @overload cancel_after(interval, with_exception: [klass, message])
+  #   @param interval [Number] timout in seconds
+  #   @param with_exception [Array] array containing class and message to use as exception
+  #   @yield [Fiber] timeout fiber
+  #   @return [any] block's return value
+  def cancel_after(interval, with_exception: Polyphony::Cancel, &block)
+    if block.arity > 0
+      cancel_after_with_optional_reset(interval, with_exception, &block)
+    else
+      Polyphony.backend_timeout(interval, with_exception, &block)
+    end
+  end
+
+  # Spins up a new fiber.
+  #
+  # @param tag [any] optional tag for the new fiber
+  # @return [Fiber] new fiber
+  def spin(tag = nil, &block)
+    Fiber.current.spin(tag, caller, &block)
+  end
+
+  # Spins up a new fiber, running the given block inside an infinite loop. If
+  # `rate:` or `interval:` parameters are given, the loop is throttled
+  # accordingly.
+  #
+  # @param tag [any] optional tag for the new fiber
+  # @param rate [Number, nil] loop rate (times per second)
+  # @param interval [Number, nil] interval between consecutive iterations in seconds
+  # @return [Fiber] new fiber
+  def spin_loop(tag = nil, rate: nil, interval: nil, &block)
+    if rate || interval
+      Fiber.current.spin(tag, caller) do
+        throttled_loop(rate: rate, interval: interval, &block)
+      end
+    else
+      spin_loop_without_throttling(tag, caller, block)
+    end
+  end
+
+  # Runs the given code, then waits for any child fibers of the current fibers
+  # to terminate.
+  #
+  # @return [any] given block's return value
+  def spin_scope(&block)
+    raise unless block
+
+    spin do
+      result = yield
+      Fiber.current.await_all_children
+      result
+    end.await
+  end
+
+  # Runs the given block in an infinite loop with a regular interval between
+  # consecutive iterations.
+  #
+  # @param interval [Number] interval between consecutive iterations in seconds
+  def every(interval, &block)
+    Polyphony.backend_timer_loop(interval, &block)
+  end
+
+  # Runs the given block after setting up a cancellation timer for
+  # cancellation. If the cancellation timer elapses, the execution will be
+  # interrupted with a `Polyphony::MoveOn` exception, which will be rescued,
+  # and with cause the operation to return the given value.
+  #
+  # This method should be used when a timeout is to be handled locally,
+  # without generating an exception that is to propagated down the call stack
+  # or up the fiber tree.
+  #
+  # Example of normal use:
+  #
+  #   move_on_after(10) {
+  #     sleep 60
+  #     42
+  #   } #=> nil
+  #
+  #   move_on_after(10, with_value: :oops) {
+  #     sleep 60
+  #     42
+  #   } #=> :oops
+  #
+  # The timeout period can be reset by passing a block that takes a single
+  # argument. The block will be provided with the canceller fiber. To reset
+  # the timeout, use `Fiber#reset`, as shown in the following example:
+  #
+  #   move_on_after(10) do |timeout|
+  #     loop do
+  #       msg = socket.gets
+  #       timeout.reset
+  #       handle_msg(msg)
+  #     end
+  #   end
+  #
+  # @overload move_on_after(interval) { ... }
+  #   @param interval [Number] timout in seconds
+  #   @yield [Fiber] timeout fiber
+  #   @return [any] block's return value
+  # @overload move_on_after(interval, with_value: value) { ... }
+  #   @param interval [Number] timout in seconds
+  #   @param with_value [any] return value in case of timeout
+  #   @yield [Fiber] timeout fiber
+  #   @return [any] block's return value
+  def move_on_after(interval, with_value: nil, &block)
+    if block.arity > 0
+      move_on_after_with_optional_reset(interval, with_value, &block)
+    else
+      Polyphony.backend_timeout(interval, nil, with_value, &block)
+    end
+  end
+
+  # Returns the first message from the current fiber's mailbox. If the mailbox
+  # is empty, blocks until a message is available.
+  #
+  # @return [any] received message
+  def receive
+    Fiber.current.receive
+  end
+
+  # Returns all messages currently pending on the current fiber's mailbox.
+  #
+  # @return [Array] array of received messages
+  def receive_all_pending
+    Fiber.current.receive_all_pending
+  end
+
+  # Supervises the current fiber's children. See `Fiber#supervise` for
+  # options.
+  #
+  # @param args [Array] positional parameters
+  # @param opts [Hash] named parameters
+  # @return [any]
+  def supervise(*args, **opts, &block)
+    Fiber.current.supervise(*args, **opts, &block)
+  end
+
+  # Sleeps for the given duration. If the duration is `nil`, sleeps
+  # indefinitely.
+  #
+  # @param duration [Number, nil] duration
+  # @return [any]
+  def sleep(duration = nil)
+    duration ?
+    Polyphony.backend_sleep(duration) : Polyphony.backend_wait_event(true)
+  end
+
+  # Starts a throttled loop with the given rate. If `count:` is given, the
+  # loop is run for the given number of times. Otherwise, the loop is
+  # infinite. The loop rate (times per second) can be given as the rate
+  # parameter. The throttling can also be controlled by providing an
+  # `interval:` or `rate:` named parameter.
+  #
+  # @param rate [Number, nil] loop rate (times per second)
+  # @option opts [Number] :rate loop rate (times per second)
+  # @option opts [Number] :interval loop interval in seconds
+  # @option opts [Number] :count number of iterations (nil for infinite)
+  # @return [any]
+  def throttled_loop(rate = nil, **opts, &block)
+    throttler = Polyphony::Throttler.new(rate || opts)
+    if opts[:count]
+      opts[:count].times { |_i| throttler.(&block) }
+    else
+      while true
+        throttler.(&block)
+      end
+    end
+  rescue LocalJumpError, StopIteration
+    # break called or StopIteration raised
+  end
+
+  private
+
+  # Helper method for performing a `cancel_after` with optional reset.
+  #
+  # @param interval [Number] timeout interval in seconds
+  # @param exception [Exception, Class, Array<class, message>] exception spec
+  # @return [any] block's return value
+  def cancel_after_with_optional_reset(interval, exception, &block)
+    fiber = Fiber.current
+    canceller = spin do
+      Polyphony.backend_sleep(interval)
+      exception = cancel_exception(exception)
+      exception.raising_fiber = Fiber.current
+      fiber.cancel(exception)
+    end
+    block.call(canceller)
+  ensure
+    canceller.stop
+  end
+
+  # Converts the given exception spec to an exception instance.
+  #
+  # @param exception [Exception, Class, Array<class, message>] exception spec
+  # @return [Exception] exception instance
+  def cancel_exception(exception)
+    case exception
+    when Class then exception.new
+    when Array then exception[0].new(exception[1])
+    else RuntimeError.new(exception)
+    end
+  end
+
+  # Helper method for performing `#spin_loop` without throttling. Spins up a
+  # new fiber in which to run the loop.
+  #
+  # @param tag [any] new fiber's tag
+  # @param caller [Array<String>] caller info
+  # @param block [Proc] code to run
+  # @return [any]
+  def spin_loop_without_throttling(tag, caller, block)
+    Fiber.current.spin(tag, caller) do
+      block.call while true
+    rescue LocalJumpError, StopIteration
+      # break called or StopIteration raised
+    end
+  end
+
+  # Helper method for performing `#move_on_after` with optional reset.
+  #
+  # @param interval [Number] timeout interval in seconds
+  # @param value [any] return value in case of timeout
+  # @return [any] return value of given block or timeout value
+  def move_on_after_with_optional_reset(interval, value, &block)
+    fiber = Fiber.current
+    canceller = spin do
+      sleep interval
+      fiber.move_on(value)
+    end
+    block.call(canceller)
+  rescue Polyphony::MoveOn => e
+    e.value
+  ensure
+    canceller.stop
+  end
 end

data/lib/polyphony/extensions/openssl.rb

@@ -17,7 +17,6 @@ class ::OpenSSL::SSL::SSLSocket
   #
   # @param socket [TCPSocket] socket to wrap
   # @param context [OpenSSL::SSL::SSLContext] optional SSL context
-  # @return [void]
   def initialize(socket, context = nil)
     socket = socket.respond_to?(:io) ? socket.io || socket : socket
     context ? orig_initialize(socket, context) : orig_initialize(socket)
@@ -155,7 +154,7 @@ class ::OpenSSL::SSL::SSLSocket
   #
   # @param maxlen [Integer] maximum bytes to receive
   # @yield [String] read data
-  # @return [void]
+  # @return [OpenSSL::SSL::SSLSocket] self
   def read_loop(maxlen = 8192)
     while (data = sysread(maxlen))
       yield data
@@ -263,8 +262,9 @@ class ::OpenSSL::SSL::SSLServer
 
   # Accepts incoming connections in an infinite loop.
   #
+  # @param ignore_errors [boolean] whether to ignore IO and SSL errors
   # @yield [OpenSSL::SSL::SSLSocket] accepted socket
-  # @return [void]
+  # @return [OpenSSL::SSL::SSLServer] self
   def accept_loop(ignore_errors = true)
     loop do
       yield accept

data/lib/polyphony/extensions/pipe.rb

@@ -178,7 +178,7 @@ class Polyphony::Pipe
   #
   # @param maxlen [Integer] maximum bytes to read
   # @yield [String] read data
-  # @return [void]
+  # @return [Polyphony::Pipe] self
   def read_loop(maxlen = 8192, &block)
     Polyphony.backend_read_loop(self, maxlen, &block)
   end
@@ -199,7 +199,7 @@ class Polyphony::Pipe
   #
   # @param receiver [any] receiver object
   # @param method [Symbol] method to call
-  # @return [void]
+  # @return [Polyphony::Pipe] self
   def feed_loop(receiver, method = :call, &block)
     Polyphony.backend_feed_loop(self, receiver, method, &block)
   end

data/lib/polyphony/extensions/socket.rb

@@ -37,7 +37,7 @@ class ::Socket < ::BasicSocket
   # Accepts incoming connections in an infinite loop.
   #
   # @yield [Socket] accepted socket
-  # @return [void]
+  # @return [nil]
   def accept_loop(&block)
     Polyphony.backend_accept_loop(self, TCPSocket, &block)
   end
@@ -109,7 +109,7 @@ class ::Socket < ::BasicSocket
   #
   # @param maxlen [Integer] maximum bytes to receive
   # @yield [String] received data
-  # @return [void]
+  # @return [Socket] self
   def recv_loop(maxlen = 8192, &block)
     Polyphony.backend_recv_loop(self, maxlen, &block)
   end
@@ -131,7 +131,7 @@ class ::Socket < ::BasicSocket
   #
   # @param receiver [any] receiver object
   # @param method [Symbol] method to call
-  # @return [void]
+  # @return [Socket] self
   def feed_loop(receiver, method = :call, &block)
     Polyphony.backend_recv_feed_loop(self, receiver, method, &block)
   end
@@ -376,7 +376,7 @@ class ::TCPSocket < ::IPSocket
   #
   # @param maxlen [Integer] maximum bytes to receive
   # @yield [String] received data
-  # @return [void]
+  # @return [Socket] self
   def recv_loop(maxlen = 8192, &block)
     Polyphony.backend_recv_loop(self, maxlen, &block)
   end
@@ -398,7 +398,7 @@ class ::TCPSocket < ::IPSocket
   #
   # @param receiver [any] receiver object
   # @param method [Symbol] method to call
-  # @return [void]
+  # @return [Socket] self
   def feed_loop(receiver, method = :call, &block)
     Polyphony.backend_recv_feed_loop(self, receiver, method, &block)
   end
@@ -494,7 +494,7 @@ class ::TCPServer < ::TCPSocket
   # Accepts incoming connections in an infinite loop.
   #
   # @yield [TCPSocket] accepted socket
-  # @return [void]
+  # @return [nil]
   def accept_loop(&block)
     Polyphony.backend_accept_loop(@io, TCPSocket, &block)
   end
@@ -526,7 +526,7 @@ class ::UNIXServer < ::UNIXSocket
   # Accepts incoming connections in an infinite loop.
   #
   # @yield [UNIXSocket] accepted socket
-  # @return [void]
+  # @return [nil]
   def accept_loop(&block)
     Polyphony.backend_accept_loop(self, UNIXSocket, &block)
   end
@@ -588,7 +588,7 @@ class ::UNIXSocket < ::BasicSocket
   #
   # @param maxlen [Integer] maximum bytes to receive
   # @yield [String] received data
-  # @return [void]
+  # @return [Socket] self
   def recv_loop(maxlen = 8192, &block)
     Polyphony.backend_recv_loop(self, maxlen, &block)
   end
@@ -610,7 +610,7 @@ class ::UNIXSocket < ::BasicSocket
   #
   # @param receiver [any] receiver object
   # @param method [Symbol] method to call
-  # @return [void]
+  # @return [Socket] self
   def feed_loop(receiver, method = :call, &block)
     Polyphony.backend_recv_feed_loop(self, receiver, method, &block)
   end

data/lib/polyphony/extensions/thread.rb

@@ -12,7 +12,6 @@ class ::Thread
 
   # Initializes the thread.
   # @param args [Array] arguments to pass to thread block
-  # @return [void]
   def initialize(*args, &block)
     @join_wait_queue = []
     @finalization_mutex = Mutex.new
@@ -23,11 +22,12 @@ class ::Thread
 
   # Sets up the thread and its main fiber.
   #
-  # @return [void]
+  # @return [Thread] self
   def setup
     @main_fiber = Fiber.current
     @main_fiber.setup_main_fiber
     setup_fiber_scheduling
+    self
   end
 
   # @!visibility private
@@ -133,7 +133,7 @@ class ::Thread
 
   # Runs the thread's block, handling any uncaught exceptions.
   #
-  # @return [void]
+  # @return [any] thread result value
   def execute
     # backend must be created in the context of the new thread, therefore it
     # cannot be created in Thread#initialize
@@ -159,7 +159,6 @@ class ::Thread
   # Finalizes the thread.
   #
   # @param result [any] thread's return value
-  # @return [void]
   def finalize(result)
     unless Fiber.current.children.empty?
       Fiber.current.shutdown_all_children
@@ -175,7 +174,6 @@ class ::Thread
   # Signals all fibers waiting for the thread to terminate.
   #
   # @param result [any] thread's return value
-  # @return [void]
   def signal_waiters(result)
     @join_wait_queue.each { |w| w.signal(result) }
   end

data/lib/polyphony/net.rb

@@ -57,7 +57,6 @@ module Polyphony
       #
       # @param context [SSLContext] SSL context
       # @param protocols [Array] array of supported protocols
-      # @return [void]
       def setup_alpn(context, protocols)
         context.alpn_protocols = protocols
         context.alpn_select_cb = lambda do |peer_protocols|

data/lib/polyphony/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: polyphony
 version: !ruby/object:Gem::Version
-  version: 0.99.5
+  version: '1.0'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-05-10 00:00:00.000000000 Z
+date: 2023-05-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler
@@ -144,9 +144,6 @@ files:
 - README.md
 - Rakefile
 - TODO.md
-- assets/echo-fibers.svg
-- assets/polyphony-logo.png
-- assets/sleeping-fiber.svg
 - bin/pdbg
 - bin/polyphony-debug
 - bin/stress.rb
@@ -154,15 +151,15 @@ files:
 - docs/_user-guide/all-about-timers.md
 - docs/_user-guide/index.md
 - docs/_user-guide/web-server.md
+- docs/assets/echo-fibers.svg
+- docs/assets/polyphony-logo.png
+- docs/assets/sleeping-fiber.svg
 - docs/concurrency.md
 - docs/design-principles.md
 - docs/exception-handling.md
 - docs/extending.md
 - docs/faq.md
 - docs/fiber-scheduling.md
-- docs/index.md
-- docs/link_rewriter.rb
-- docs/main-concepts/index.md
 - docs/overview.md
 - docs/readme.md
 - docs/tutorial.md
@@ -335,7 +332,6 @@ files:
 - lib/polyphony/core/channel.rb
 - lib/polyphony/core/debug.rb
 - lib/polyphony/core/exceptions.rb
-- lib/polyphony/core/global_api.rb
 - lib/polyphony/core/resource_pool.rb
 - lib/polyphony/core/sync.rb
 - lib/polyphony/core/thread_pool.rb

data/docs/index.md

@@ -1,94 +0,0 @@
----
-layout: page
-title: Home
-nav_order: 1
-permalink: /
-next_title: Installing Polyphony
----
-
-<p align="center"><img src="{{ 'polyphony-logo.png' | absolute_url }}" /></p>
-
-# Polyphony
-{:.text-center .logo-title}
-
-## Fine-grained concurrency for Ruby
-{:.text-center .logo-title}
-
-Polyphony is a library for building concurrent applications in Ruby. Polyphony
-implements a comprehensive
-[fiber](https://ruby-doc.org/core-2.5.1/Fiber.html)-based concurrency model,
-using [libev](https://github.com/enki/libev) as a high-performance event reactor
-for I/O, timers, and other asynchronous events.
-
-[Overview](getting-started/overview){: .btn .btn-green .text-gamma }
-[Take the tutorial](getting-started/tutorial){: .btn .btn-blue .text-gamma }
-[Source code](https://github.com/digital-fabric/polyphony){: .btn .btn-purple .text-gamma target="_blank" }
-{:.text-center .mt-6 .h-align-center }
-
-## Focused on Developer Happiness
-
-Polyphony is designed to make concurrent Ruby programming feel natural and
-fluent. The Polyphony API is easy to use, easy to understand, and above all
-idiomatic.
-
-## Optimized for High Performance
-
-Polyphony offers high performance for I/O bound Ruby apps. Distributing
-concurrent operations over fibers, instead of threads or processes, minimizes
-memory consumption and reduces the cost of context-switching.
-
-## Designed for Interoperability
-
-With Polyphony you can use any of the stock Ruby classes and modules like `IO`,
-`Process`, `Socket` and `OpenSSL` in a concurrent multi-fiber environment. In
-addition, Polyphony provides a structured model for exception handling that
-builds on and enhances Ruby's exception handling system.
-
-## A Growing Ecosystem
-
-Polyphony includes a full-blown HTTP server implementation with integrated
-support for HTTP 2, WebSockets, TLS/SSL termination and more. Polyphony also
-provides fiber-aware adapters for connecting to PostgreSQL and Redis. More
-adapters are being developed.
-
-## 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, 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` and `TCPSocket` and `Net::HTTP`.
-* Competitive performance and scalability characteristics, in terms of both
-  throughput and memory consumption.
-
-## Prior Art
-
-Polyphony draws inspiration from the following, in no particular order:
-
-* [nio4r](https://github.com/socketry/nio4r/) and
-  [async](https://github.com/socketry/async) (Polyphony's C-extension code
-  started as a spinoff of
-  [nio4r's](https://github.com/socketry/nio4r/tree/master/ext))
-* The [go scheduler](https://www.ardanlabs.com/blog/2018/08/scheduling-in-go-part2.html)
-* [EventMachine](https://github.com/eventmachine/eventmachine)
-* [Trio](https://trio.readthedocs.io/)
-* [Erlang supervisors](http://erlang.org/doc/man/supervisor.html) (and actually,
-  Erlang in general)
-
-## Developer Resources
-
-* [Tutorial](getting-started/tutorial)
-* [Main Concepts](main-concepts/concurrency/)
-* [User Guide](user-guide/all-about-timers/)
-* [API Reference](api-reference/exception/)
-* [Examples](https://github.com/digital-fabric/polyphony/tree/9e0f3b09213156bdf376ef33684ef267517f06e8/examples/README.md)
-
-## Contributing to Polyphony
-
-Issues and pull requests will be gladly accepted. Please use the [Polyphony git
-repository](https://github.com/digital-fabric/polyphony) as your primary point
-of departure for contributing.

data/docs/link_rewriter.rb

@@ -1,17 +0,0 @@
-require 'yard'
-
-# shamelessly copied from https://github.com/troessner/reek/blob/master/docs/yard_plugin.rb
-
-# Template helper to modify processing of links in HTML generated from our
-# markdown files.
-module LocalLinkHelper
-  # Rewrites links to (assumed local) markdown files so they're processed as
-  # {file: } directives.
-  def resolve_links(text)
-    text = text.gsub(%r{<a href="(docs/[^"]*.md)">([^<]*)</a>}, '{file:/\1 \2}')
-               .gsub(%r{<img src="(assets/[^"]*)">}, '{rdoc-image:/\1}')
-    super text
-  end
-end
-
-YARD::Templates::Template.extra_includes << LocalLinkHelper

data/docs/main-concepts/index.md

@@ -1,9 +0,0 @@
----
-layout: page
-title: Main Concepts
-has_children: true
-nav_order: 3
----
-
-# Main Concepts
-{: .no_toc }