polyphony 0.99 → 0.99.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4696bb7b13f68b379c29d5c38257e57c13aefd299f88727107e2f0f0a3c7d360
-  data.tar.gz: 94a3eeb8575d0d5fe6f143ab41351024b50c4c4cf919edec6c8155d9ead2831e
+  metadata.gz: 3f9f6713f2080b0ad929afc680c52a88ad737701575c30433e9ec4c759258dd7
+  data.tar.gz: c7f3fd09e72c34269624d52d8dc77e9f5645cfa2d65743afe51e07db850598e3
 SHA512:
-  metadata.gz: 9e1798e18b0e7a35104009d6f480191f5ed5efd7dee69189d443cb57ab8ca2f8fd75105234cd60f52ecea2348a8c3d85f152aa869374ea8dfbab8895a2015b04
-  data.tar.gz: 835b2be245f60b04d5b750bcce6e679b11c671e31c3d0269aeafaa961c52c501193f67cf00f4f7cc5570cab499105d025863189767db8ae79f961a62d903b173
+  metadata.gz: d3472d5ffee0ce36370701c98d28d33d9c76e7ac21a6635e4dff063a6d28e313cd518290dbd0904c496ec29471cab39922daf2473f6b9a168588d0ef861f5ff2
+  data.tar.gz: 2a230e7c9b2a95e24992d4a844b92a7af243da5113f355945ce8f585a415dafbde0e2f1fe2fcd1ba434bda94992a3cdf906e37ab78c01caa355e131c8103c87b

data/.github/FUNDING.yml

@@ -1 +1 @@
-github: ciconia
+github: noteflakes

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 3.2
   RubyInterpreters:
     - ruby
   Exclude:
@@ -49,7 +49,7 @@ Style/NumericPredicate:
 Style/TrivialAccessors:
   Enabled: false
 
-Style/MethodMissingSuper:
+Lint/MissingSuper:
   Enabled: false
 
 Style/GlobalVars:
@@ -90,7 +90,7 @@ Metrics/MethodLength:
 
 Metrics/ModuleLength:
   Exclude:
-    - lib/polyphony/extensions/core.rb
+    - lib/polyphony/core/global_api.rb
     - examples/**/*.rb
 
 Metrics/ClassLength:

data/.yardopts

@@ -0,0 +1,30 @@
+-o ./_yardoc
+-m markdown -M redcarpet
+--verbose
+--protected
+--no-private
+--asset assets/:assets
+--exclude debugger.rb
+--exclude redis.rb
+--exclude readline.rb
+--exclude postgres.rb
+--exclude zlib_conf.rb
+--exclude extconf.rb
+--exclude mysql2.rb
+--exclude sequel.rb
+--exclude event.c
+--exclude backend.+\.c
+--load ./docs/link_rewriter.rb
+./lib
+./ext/polyphony
+-
+docs/overview.md
+docs/tutorial.md
+docs/faq.md
+docs/concurrency.md
+docs/fiber-scheduling.md
+docs/exception-handling.md
+docs/extending.md
+docs/design-principles.md
+CHANGELOG.md
+LICENSE

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.99.1 2023-05-08
+
+- Reorganize docs, use Yard for all docs.
+
 ## 0.99 2023-03-09
 
 - Add missing Mutex API methods (#76)

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Sharon Rosner
+Copyright (c) 2023 Sharon Rosner
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,36 +1,26 @@
-<h1 align="center">
-  <a href="https://digital-fabric.github.io/polyphony/">
-    <img src="docs/polyphony-logo.png" alt="Polyphony">
-  </a>
-  <br>
-  Polyphony
-  <br>
-</h1>
-
-<h4 align="center">Fine-Grained Concurrency for Ruby</h4>
-
-<p align="center">
-  <a href="http://rubygems.org/gems/polyphony">
-    <img src="https://badge.fury.io/rb/polyphony.svg" alt="Ruby gem">
-  </a>
-  <a href="https://github.com/digital-fabric/polyphony/actions?query=workflow%3ATests">
-    <img src="https://github.com/digital-fabric/polyphony/workflows/Tests/badge.svg" alt="Tests">
-  </a>
-  <a href="https://github.com/digital-fabric/polyphony/blob/master/LICENSE">
-    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License">
-  </a>
-</p>
-
-[DOCS](https://digital-fabric.github.io/polyphony/) |
-[EXAMPLES](examples)
+<img src="assets/polyphony-logo.png" alt="Polyphony">
+
+# Polyphony: Fine-Grained Concurrency for Ruby
+
+<a href="http://rubygems.org/gems/polyphony">
+  <img src="https://badge.fury.io/rb/polyphony.svg" alt="Ruby gem">
+</a>
+<a href="https://github.com/digital-fabric/polyphony/actions?query=workflow%3ATests">
+  <img src="https://github.com/digital-fabric/polyphony/workflows/Tests/badge.svg" alt="Tests">
+</a>
+<a href="https://github.com/digital-fabric/polyphony/blob/master/LICENSE">
+  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License">
+</a>
 
 > Polyphony \| pəˈlɪf\(ə\)ni \|
+>
 > 1. _Music_ the style of simultaneously combining a number of parts, each
 >    forming an individual melody and harmonizing with each other.
+>
 > 2. _Programming_ a Ruby gem for concurrent programming focusing on performance
 >    and developer happiness.
 
-## What is Polyphony
+## 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)
@@ -54,10 +44,54 @@ the hood, Polyphony uses
 * Competitive performance and scalability characteristics, in terms of both
   throughput and memory consumption.
 
-## Documentation
+## 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.0 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
+```
+
+## Usage
+
+- [Overview](docs/overview.md)
+- [Tutorial](docs/tutorial.md)
+- [FAQ](docs/faq.md)
+
+## Technical Discussion
+
+- [Concurrency the Easy Way](docs/concurrency.md)
+- [How Fibers are Scheduled](docs/fiber-scheduling.md)
+- [Exception Handling](docs/exception-handling.md)
+- [Extending Polyphony](docs/extending.md)
+- [Polyphony's Design](docs/design-principles.md)
+
+## Examples
 
-The complete documentation for Polyphony could be found on the
-[Polyphony website](https://digital-fabric.github.io/polyphony).
+For examples of specific use cases you can consult the [bundled
+examples](https://github.com/digital-fabric/polyphony/tree/master/examples) in
+Polyphony's GitHub repository.
 
 ## Contributing to Polyphony
 

data/Rakefile

@@ -19,16 +19,12 @@ task :stress_test do
   exec 'ruby test/stress.rb'
 end
 
-task :docs do
-  exec 'RUBYOPT=-W0 jekyll serve -s docs -H ec2-18-156-117-172.eu-central-1.compute.amazonaws.com'
-end
-
 CLEAN.include "**/*.o", "**/*.so", "**/*.so.*", "**/*.a", "**/*.bundle", "**/*.jar", "pkg", "tmp"
 
 task :release do
   require_relative './lib/polyphony/version'
   version = Polyphony::VERSION
-  
+
   puts 'Building polyphony...'
   `gem build polyphony.gemspec`
 

data/TODO.md

@@ -11,9 +11,6 @@
 - Add support for IPv6:
   https://www.reddit.com/r/ruby/comments/lyen23/understanding_ipv6_and_why_its_important_to_you/
 
-- Add support for UDP sockets
-
-- Check segfault when resetting a `cancel_after` timeout lots of times at very high rate
 - Check why `throttled_loop` inside of `move_on_after` fails to stop
 
 - Override stock `::SizedQueue` impl with Queue with capacity
@@ -165,7 +162,6 @@
   - test performance
   - proceed from there
 
-
 ### Sinatra / Sidekiq
 
 - Pull out redis/postgres code, put into new `polyphony-xxx` gems

data/docs/{main-concepts/concurrency.md → concurrency.md}

@@ -1,12 +1,5 @@
----
-layout: page
-title: Concurrency the Easy Way
-nav_order: 1
-parent: Main Concepts
-permalink: /main-concepts/concurrency/
-prev_title: Tutorial
-next_title: How Fibers are Scheduled
----
+# @title Concurrency the Easy Way
+
 # Concurrency the Easy Way
 
 Concurrency is a major consideration for modern programmers. Applications and

data/docs/{main-concepts/design-principles.md → design-principles.md}

@@ -1,12 +1,6 @@
----
-layout: page
-title: The Design of Polyphony
-nav_order: 5
-parent: Main Concepts
-permalink: /main-concepts/design-principles/
-prev_title: Extending Polyphony
----
-# The Design of Polyphony
+# @title Polyphony's Design
+
+# Polyphony's Design
 
 Polyphony is a new gem that aims to enable developing high-performance
 concurrent applications in Ruby using a fluent, compact syntax and API.

data/docs/{main-concepts/exception-handling.md → exception-handling.md}

@@ -1,12 +1,5 @@
----
-layout: page
-title: Exception Handling
-nav_order: 3
-parent: Main Concepts
-permalink: /main-concepts/exception-handling/
-prev_title: How Fibers are Scheduled
-next_title: Extending Polyphony
----
+# @title Exception Handling
+
 # Exception Handling
 
 Ruby employs a pretty robust exception handling mechanism. An raised exception

data/docs/{main-concepts/extending.md → extending.md}

@@ -1,12 +1,5 @@
----
-layout: page
-title: Extending Polyphony
-nav_order: 4
-parent: Main Concepts
-permalink: /main-concepts/extending/
-prev_title: Exception Handling
-next_title: The Design of Polyphony
----
+# @title Extending Polyphony
+
 # Extending Polyphony
 
 Polyphony was designed to ease the transition from blocking APIs and

data/docs/faq.md

@@ -1,19 +1,6 @@
----
-layout: page
-title: Frequently Asked Questions
-nav_order: 100
----
+# @title FAQ
 
 # Frequently Asked Questions
-{: .no_toc }
-
-## Table of contents
-{: .no_toc .text-delta }
-
-- TOC
-{:toc}
-
----
 
 ## Why not just use callbacks instead of fibers?
 
@@ -191,5 +178,5 @@ Feel free to create issues and contribute pull requests.
 ## Who is behind this project?
 
 I'm Sharon Rosner, an independent software developer living in France. Here's my
-[github profile](https://github.com/ciconia). You can contact me by writing to
-[noteflakes@gmail.com](mailto:ciconia@gmail.com).
+[github profile](https://github.com/noteflakes). You can contact me by writing to
+[sharon@noteflakes.com](mailto:sharon@noteflakes.com).

data/docs/{main-concepts/fiber-scheduling.md → fiber-scheduling.md}

@@ -1,12 +1,4 @@
----
-layout: page
-title: How Fibers are Scheduled
-nav_order: 2
-parent: Main Concepts
-permalink: /main-concepts/fiber-scheduling/
-prev_title: Concurrency the Easy Way
-next_title: Exception Handling
----
+# @title How Fibers are Scheduled
 
 # How Fibers are Scheduled
 

data/docs/link_rewriter.rb

@@ -0,0 +1,16 @@
+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}')
+    super text
+  end
+end
+
+YARD::Templates::Template.extra_includes << LocalLinkHelper

data/docs/{getting-started/overview.md → overview.md}

@@ -1,20 +1,6 @@
----
-layout: page
-title: Overview
-parent: Getting Started
-nav_order: 2
----
+# @title Overview
 
 # Polyphony - an Overview
-{: .no_toc }
-
-## Table of contents
-{: .no_toc .text-delta }
-
-- TOC
-{:toc}
-
----
 
 ## Introduction
 
@@ -34,21 +20,6 @@ support for HTTP 1 & 2, WebSockets, TLS/SSL termination and more. Polyphony also
 provides fiber-aware adapters for connecting to PostgreSQL and Redis servers.
 More adapters are being actively developed.
 
-### Features
-{: .no_toc }
-
-- Co-operative scheduling of concurrent tasks using Ruby fibers.
-- High-performance event reactor for handling I/O, timer, and other events.
-- 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 and TCPSocket and Net::HTTP.
-- Impressive performance and scalability characteristics, in terms of both
-  throughput and memory consumption (see below)
-
 ## Taking Polyphony for a Spin
 
 Polyphony is different from other reactor-based solutions for Ruby in that

data/docs/{getting-started/tutorial.md → tutorial.md}

@@ -1,20 +1,6 @@
----
-layout: page
-title: Tutorial
-parent: Getting Started
-nav_order: 3
----
+# @title Tutorial
 
 # Tutorial
-{: .no_toc }
-
-## Table of contents
-{: .no_toc .text-delta }
-
-- TOC
-{:toc}
-
----
 
 Polyphony is a new Ruby library aimed at making writing concurrent Ruby apps
 easy and fun. In this article, we'll introduce Polyphony's fiber-based
@@ -108,7 +94,7 @@ The above program does nothing exceptional, it just sleeps for 1 second and
 prints a bunch of messages. But it is enough to demonstrate how concurrency
 works in Polyphony. Here's a flow chart of the transfer of control:
 
-<p class="img-figure"><img src="../../assets/img/sleeping-fiber.svg"></p>
+<img src="../assets/sleeping-fiber.svg">
 
 Here's the actual sequence of execution (in pseudo-code)
 
@@ -203,7 +189,7 @@ innocent call to `#spin`.
 
 Here's a flow chart showing the transfer of control between the different fibers:
 
-<p class="img-figure"><img src="../../assets/img/echo-fibers.svg"></p>
+<img src="../assets/echo-fibers.svg">
 
 Let's consider the advantage of the Polyphony concurrency model:
 
@@ -346,14 +332,3 @@ Polyphony currently provides support for any library that uses Ruby's stock
 `redis` and `irb` gems. It also includes an implementation of an integrated HTTP
 1 / HTTP 2 / websockets web server with support for TLS termination, ALPN
 protocol selection and preliminary rack support.
-
-## Fibers are the Future!
-
-Implementing concurrency at the level of fibers opens up so many new
-possibilities for Ruby. Polyphony has the performance characteristics and
-provides the necessary tools for transforming how concurrent Ruby apps are
-written. Polyphony is still new, and the present documentation is far from being
-complete. To learn more about Polyphony, read the [technical
-overview](../../main-concepts/design-principles/). For more examples please
-consult the [Github
-repository](https://github.com/digital-fabric/polyphony/tree/master/examples).

data/docs/{_posts/2020-07-26-polyphony-0.44.md → whats-new.md}

@@ -1,4 +1,6 @@
-# Polyphony 0.44.1
+# @title What's New?
+
+# What's New in 0.44?
 
 ## More performance, more compatibility, more robustness
 

data/examples/adapters/redis_client.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
-require 'bundler/setup'
-require 'polyphony/adapters/redis'
+# require 'bundler/setup'
+require './lib/polyphony/adapters/redis'
+require 'redis'
 
 ::Exception.__disable_sanitized_backtrace__ = true
 

data/examples/io/echo_server.rb

@@ -5,8 +5,8 @@ require 'polyphony'
 
 spin_loop(interval: 5) { p Thread.backend.stats }
 
-server = TCPServer.open('127.0.0.1', 1234)
 puts "Pid: #{Process.pid}"
+server = TCPServer.open('127.0.0.1', 1234)
 puts 'Echoing on port 1234...'
 begin
   while (client = server.accept)

data/examples/io/echo_server_plain_ruby.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'socket'
+
+puts "Pid: #{Process.pid}"
+server = TCPServer.open('127.0.0.1', 1234)
+puts 'Echoing on port 1234...'
+begin
+  while (client = server.accept)
+    Thread.new do
+      while (data = client.gets)
+        # client.send("you said: #{data.chomp}!\n", 0)
+        client.write('you said: ', data.chomp, "!\n")
+      end
+    rescue Errno::ECONNRESET
+      'Connection reset...'
+    ensure
+      puts "Closing client socket"
+      client.shutdown
+      client.close
+    end
+  end
+ensure
+  puts "Closing server"
+  server.close
+end