polyphony 0.99.4 → 0.99.6

data/test/test_socket.rb

@@ -199,7 +199,7 @@ class TCPSocketWithRawBufferTest < MiniTest::Test
     [port, server]
   rescue Errno::EADDRINUSE
     retry
-  end  
+  end
 
   def setup
     super
@@ -337,13 +337,13 @@ class SSLSocketTest < MiniTest::Test
   def test_ssl_accept_loop
     authority = Localhost::Authority.fetch
     server_ctx = authority.server_context
-    
+
     opts = {
       reuse_addr:     true,
       dont_linger:    true,
       secure_context: server_ctx
     }
-    
+
     port = rand(10001..39999)
     server = Polyphony::Net.tcp_listen('127.0.0.1', port, opts)
     f = spin do

data/test/test_trace.rb

@@ -49,7 +49,7 @@ class TraceTest < MiniTest::Test
     sleep 0
 
     Thread.backend.trace_proc = nil
-    
+
     assert_equal [
       [:spin, f],
       [:schedule, f, nil, false],
@@ -143,7 +143,7 @@ class TraceTest < MiniTest::Test
       }
     }
     receive
-    
+
     Polyphony::Trace.start_event_firehose { |e| receiver << e }
 
     f1 = spin(:f1) do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: polyphony
 version: !ruby/object:Gem::Version
-  version: 0.99.4
+  version: 0.99.6
 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 }

data/lib/polyphony/core/global_api.rb

@@ -1,309 +0,0 @@
-# frozen_string_literal: true
-
-require_relative './throttler'
-
-module Polyphony
-  
-  # Global API methods to be included in `::Object`
-  module 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
-    # @yield [] block to run
-    # @return [Fiber] spun fiber
-    def after(interval, &block)
-      spin do
-        sleep interval
-        block.()
-      end
-    end
-
-    # call-seq:
-    #   cancel_after(interval) { ... }
-    #   cancel_after(interval, with_exception: exception) { ... }
-    #   cancel_after(interval, with_exception: [klass, message]) { ... }
-    #   cancel_after(interval) { |timeout| ... }
-    #   cancel_after(interval, with_exception: exception) { |timeout| ... }
-    #   cancel_after(interval, with_exception: [klass, message]) { |timeout| ... }
-    #
-    # 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
-    #
-    # @param interval [Number] timout in seconds
-    # @param with_exception [Class, Exception] exception or exception class
-    # @yield [Fiber] block to execute
-    # @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
-    # @yield [any] fiber block
-    # @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
-    # @yield [any] code to run
-    # @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.
-    #
-    # @yield [any] code to run
-    # @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
-    # @yield [any] block to run
-    # @return [void]
-    def every(interval, &block)
-      Polyphony.backend_timer_loop(interval, &block)
-    end
-
-    # call-seq:
-    #   move_on_after(interval) { ... }
-    #   move_on_after(interval, with_value: value) { ... }
-    #   move_on_after(interval) { |canceller| ... }
-    #   move_on_after(interval, with_value: value) { |canceller| ... }
-    #
-    # 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
-    #
-    # @param interval [Number] timout in seconds
-    # @param with_value [any] return value in case of timeout
-    # @yield [Fiber] block to execute
-    # @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
-    # @yield [any] given block
-    # @return [void]
-    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 [void]
-    def sleep(duration = nil)
-      duration ?
-        Polyphony.backend_sleep(duration) : Polyphony.backend_wait_event(true)
-    end
-
-    # call-seq:
-    #   throttled_loop(rate) { ... }
-    #   throttled_loop(interval: value) { ... }
-    #   throttled_loop(rate: value) { ... }
-    #   throttled_loop(rate, count: value) { ... }
-    #
-    # 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)
-    # @yield [] code to run
-    # @return [void]
-    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
-    # @yield [Fiber] block to run
-    # @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 [void]
-    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
-    # @yield [Fiber] code to run
-    # @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
-end