polyphony 0.43.8

data/bin/polyphony-debug

@@ -0,0 +1,87 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'polyphony'
+
+Gyro.trace(true)
+
+FILE_CACHE = {}
+@ready = nil
+@last_location = nil
+@mode = :step
+@current_fiber = nil
+@stacks = Hash.new([])
+
+def debug_prompt
+  loop do
+    STDOUT << '(debug) '
+    case (cmd = STDIN.gets.chomp)
+    when '.q', '.quit'
+      exit!
+    when 's', 'step'
+      @mode = :step
+      return
+    else
+      begin
+        result = binding.eval(cmd)
+        p result
+      rescue Exception => e
+        p e
+        puts e.backtrace.join("\n")
+      end
+    end
+  end
+end
+
+def get_snippet(path, lineno)
+  lines = FILE_CACHE[path] ||= IO.read(path).lines
+  start_idx = lineno - 5
+  stop_idx = lineno + 3
+  stop_idx = lines.size - 1 if stop_idx >= lines.size
+  start_idx = 0 if start_idx < 0
+  (start_idx..stop_idx).map { |idx| [idx + 1, lines[idx]]}
+end
+
+def print_snippet(snippet, cur_line)
+  snippet.each do |(lineno, line)|
+    is_cur = lineno == cur_line
+    formatted = format("%s%03d %s", is_cur ? '*=> ' : '    ', lineno, line)
+    puts formatted
+  end
+end
+
+tp = Polyphony::Trace.new(*Polyphony::Trace::STOCK_EVENTS, :fiber_all) do |r|
+  unless @ready
+    @ready = true if r[:event] == :return
+    @current_fiber = r[:fiber]
+    next
+  end
+
+  case r[:event]
+  when :call, :b_call, :c_call
+    @stacks[r[:fiber]] << r
+  when :return, :b_return, :c_return
+    @stacks[r[:fiber]].pop
+  when :line
+    case @mode
+    when :step
+      if r[:location] != @last_location && r[:fiber] == @current_fiber
+        @last_location = r[:location]
+        puts "in #{r[:location]}"
+        puts
+        snippet = get_snippet(r[:path], r[:lineno])
+        print_snippet(snippet, r[:lineno])
+        puts
+        debug_prompt
+      end
+    end
+  end
+rescue Exception => e
+  p e
+  exit!
+end
+tp.enable
+
+require File.expand_path(ARGV[0])

data/docs/_config.yml

@@ -0,0 +1,64 @@
+title: "Polyphony"
+description: Fine-grained concurrency for Ruby
+
+plugins:
+  - jekyll-remote-theme
+
+permalink: pretty
+remote_theme: pmarsceill/just-the-docs
+color_scheme: light
+
+search_enabled: true
+search:
+  # Split pages into sections that can be searched individually
+  # Supports 1 - 6, default: 2
+  heading_level: 2
+  # Maximum amount of previews per search result
+  # Default: 3
+  previews: 3
+  # Maximum amount of words to display before a matched word in the preview
+  # Default: 5
+  preview_words_before: 5
+  # Maximum amount of words to display after a matched word in the preview
+  # Default: 10
+  preview_words_after: 10
+  # Set the search token separator
+  # Default: /[\s\-/]+/
+  # Example: enable support for hyphenated search words
+  tokenizer_separator: /[\s/]+/
+  # Display the relative url in search results
+  # Supports true (default) or false
+  rel_url: true
+  # Enable or disable the search button that appears in the bottom right corner of every page
+  # Supports true or false (default)
+  button: false
+
+aux_links:
+  "Polyphony on GitHub":
+    - "//github.com/digital-fabric/polyphony"
+
+# Makes Aux links open in a new tab. Default is false
+aux_links_new_tab: false
+
+# Enable or disable heading anchors
+heading_anchors: true
+
+back_to_top: true
+back_to_top_text: "Back to top"
+
+footer_content: "Copyright &copy; 2020 Sharon Rosner. Distributed by an <a href=\"https://github.com/digital-fabric/polyphony/tree/master/LICENSE\">MIT license.</a>"
+
+# Footer "Edit this page on GitHub" link text
+gh_edit_link: true # show or hide edit this page link
+gh_edit_link_text: "Edit this page on GitHub"
+gh_edit_repository: "https://github.com/digital-fabric/polyphony" # the github URL for your repo
+gh_edit_branch: "master/docs" # the branch that your docs is served from
+gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
+
+compress_html:
+  clippings: all
+  comments: all
+  endings: all
+  startings: []
+  blanklines: false
+  profile: false

data/docs/_includes/head.html

@@ -0,0 +1,40 @@
+<head>
+  <meta charset="UTF-8">
+  <meta http-equiv="X-UA-Compatible" content="IE=Edge">
+
+  {% unless site.plugins contains "jekyll-seo-tag" %}
+    <title>{{ page.title }} - {{ site.title }}</title>
+
+    {% if page.description %}
+      <meta name="Description" content="{{ page.description }}">
+    {% endif %}
+  {% endunless %}
+
+  <link rel="shortcut icon" href="{{ 'polyphony-logo.png' | absolute_url }}" type="image/png">
+
+  <link rel="stylesheet" href="{{ '/assets/css/just-the-docs-default.css' | absolute_url }}">
+
+  {% if site.ga_tracking != nil %}
+    <script async src="https://www.googletagmanager.com/gtag/js?id={{ site.ga_tracking }}"></script>
+    <script>
+      window.dataLayer = window.dataLayer || [];
+      function gtag(){dataLayer.push(arguments);}
+      gtag('js', new Date());
+
+      gtag('config', '{{ site.ga_tracking }}'{% unless site.ga_tracking_anonymize_ip == nil %}, { 'anonymize_ip': true }{% endunless %});
+    </script>
+
+  {% endif %}
+
+  {% if site.search_enabled != false %}
+    <script type="text/javascript" src="{{ '/assets/js/vendor/lunr.min.js' | absolute_url }}"></script>
+  {% endif %}
+  <script type="text/javascript" src="{{ '/assets/js/just-the-docs.js' | absolute_url }}"></script>
+
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+
+  {% seo %}
+
+  {% include head_custom.html %}
+
+</head>

data/docs/_includes/title.html

@@ -0,0 +1 @@
+<img src="{{ 'polyphony-logo.png' | absolute_url }}" style="height: 1.5em; margin-right: 0.5em">Polyphony

data/docs/_sass/custom/custom.scss

@@ -0,0 +1,10 @@
+
+h1.logo-title {
+  font-size: 42px !important;
+  font-weight: bold;
+}
+
+h2.logo-title {
+  margin-top: 0.25em;
+  margin-bottom: 1em;
+}

data/docs/_user-guide/all-about-timers.md

@@ -0,0 +1,126 @@
+---
+layout: page
+title: All About Timers
+nav_order: 1
+parent: User Guide
+permalink: /user-guide/all-about-timers/
+---
+# All About Timers
+
+Timers form a major part of writing dynamic concurrent programs. They allow
+programmers to create delays and to perform recurring operations with a
+controllable frequency. Crucially, they also enable the implementation of
+timeouts, which are an important aspect of concurrent programming.
+
+## Sleeping
+
+Sometimes, your code needs to wait for a certain period of time. For example,
+implementing a retry mechanism for failed HTTP requests might involve waiting
+for a few seconds before retrying. Polyphony patches the `Kernel#sleep` method
+to be fiber-aware, that is to yield control of execution while waiting for a
+timer to elapse.
+
+```ruby
+# This is a naive retry implementation
+def fetch(url)
+  fetch_url(url)
+rescue
+  sleep 1
+  retry
+end
+```
+
+## Sleeping Forever
+
+The `#sleep` method can also be used to sleep forever, if no argument is given:
+
+```ruby
+puts "Go to sleep"
+sleep
+puts "Woke up" # this line will not be executed
+```
+
+The `#sleep` forever call can be used for example in the main fiber when we do
+all our work in other fibers, since once the main fiber terminates the program
+exits.
+
+## Doing Work Later 
+
+While `#sleep` allows you to block execution of the current fiber, sometimes you
+want to perform some work later, while not blocking the current fiber. This is done simply by spinning off another fiber:
+
+```ruby
+do_some_stuff
+spin do
+  sleep 3
+  do_stuff_later
+end
+do_some_more_stuff
+```
+
+## Using timeouts
+
+Polyphony provides the following global methods for using timeouts:
+
+- `#move_on_after` - used for cancelling an operation after a certain period of time without raising an exception:
+
+  ```ruby
+  move_on_after 1 do
+    sleep 60
+  end
+  ```
+
+  This method also takes an optional return value argument:
+
+  ```ruby
+  move_on_after 1, with_value: 'bar' do
+    sleep 60
+    'foo'
+  end #=> 'bar'
+  ```
+
+- `#cancel_after` - used for cancelling an operation after a certain period of time with a `Cancel` exception:
+
+  ```ruby
+  cancel_after 1 do
+    sleep 60
+  end #=> raises Cancel
+  ```
+
+Polyphony also provides a fiber-aware version of the core Ruby `Timeout` API, which may be used directly or indirectly to interrupt blocking operations.
+
+## Using Raw Timers
+
+Polyphony implements timers through the `Gyro::Timer` class, which encapsulates
+libev timer watchers. Using `Gyro::Timer` you can create both one-time and
+recurring timers:
+
+```ruby
+# Create a one-time timer
+one_time = Gyro::Timer.new(1, 0)
+
+# Create a recurring timer
+recurring = Gyro::Timer.new(0.5, 1.5)
+```
+
+Once your timer is created, you can wait for it using the `#await` method:
+
+```ruby
+def delay(duration)
+  timer = Gyro::Timer.new(duration, 0)
+  timer.await
+end
+```
+
+Waiting for the timer will *block* the current timer. This means that if you
+want to do other work while waiting for the timer, you need to put it on a
+different fiber:
+
+```ruby
+timer = Gyro::Timer.new(3, 0)
+spin {
+  sleep 3
+  do_something_else
+}
+do_blocking_operation
+```

data/docs/_user-guide/index.md

@@ -0,0 +1,9 @@
+---
+layout: page
+title: User Guide
+has_children: true
+nav_order: 4
+---
+
+# User Guide
+{: .no_toc }

data/docs/_user-guide/web-server.md

@@ -0,0 +1,136 @@
+---
+layout: page
+title: Web Server
+nav_order: 5
+parent: User Guide
+permalink: /user-guide/web-server/
+---
+# Web Server
+
+Polyphony's web server functionality offers a powerful and flexible way to
+create Ruby-based web servers and web applications. In addition to supporting
+both HTTP 1 and HTTP 2, it supports seamless Websocket upgrades (and indeed
+arbitrary protocol upgrade), TLS termination, and automatic ALPN-based protocol
+selection. In addition, it includes a Rack adapter for running Rack
+applications. Polyphony's web server offers excellent performance
+characteristics, in terms of throughput, memory consumption and scalability
+(benchmarks are forthcoming).
+
+What makes Polyphony's web server design stand out is the fact that incoming
+requests can be processed immediately upon receiving the complete headers,
+without needing to wait for the entire request body to be received. This design
+allows web applications to properly buffer uploads of large files without
+consuming large amounts of RAM, as well as reject requests without waiting for
+the entire request body.
+
+## A basic web server
+
+```ruby
+require 'tipi'
+
+Tipi.serve('0.0.0.0', 1234) do |request|
+  request.respond("Hello world!\n")
+end
+```
+
+Note that requests are handled using a callback block which takes a single
+argument. The `request` object provides the entire API for responding to the
+client.
+
+Each client connection will be handled in a separate fiber, allowing
+concurrent processing of incoming requests.
+
+## HTTP 2 support
+
+HTTP 2 support is baked in to the server, which supports both HTTP 2 upgrades
+(for example on a non-encrypted connection) and ALPN-based protocol selection,
+in a completely effortless manner.
+
+Since HTTP 2 connections are multiplexed, allowing multiple concurrent requests
+on a single connection, each HTTP 2 stream is handled in a separate fiber.
+
+## TLS termination
+
+TLS termination can be handled by passing a `secure_context` option to the
+server:
+
+```ruby
+require 'tipi'
+require 'localhost/authority'
+
+authority = Localhost::Authority.fetch
+opts = { secure_context: authority.server_context }
+
+Tipi.serve('0.0.0.0', 1234, opts) do |request|
+  request.respond("Hello world!\n")
+end
+```
+
+## Websockets && HTTP upgrades
+
+Polyphony's web server makes it really easy to integrate websocket communication
+with normal HTTP processing:
+
+```ruby
+require 'tipi'
+require 'tipi/websocket'
+
+ws_handler = Polyphony::Websocket.handler do |ws|
+  while (msg = ws.recv)
+    ws << "you said: #{msg}"
+  end
+end
+
+opts = {
+  upgrade: { websocket: ws_handler }
+}
+
+Tipi.serve('0.0.0.0', 1234, opts) do |request|
+  request.respond("Hello world!\n")
+end
+```
+
+Polyphony also supports general-purpose HTTP upgrades using the same mechanism:
+
+```ruby
+require 'tipi'
+
+opts = {
+  upgrade: {
+    echo: ->(conn) {
+      while (msg = conn.gets)
+        conn << "You said: #{msg}"
+      end
+    }
+  }
+}
+
+Tipi.serve('0.0.0.0', 1234, opts) do |request|
+  request.respond("Hello world!\n")
+end
+```
+
+## Sending HTTP responses
+
+The response API provides multiple ways of responding, with or without a body,
+and enables streaming (using chunked encoding for HTTP/1.1 connections). Here's
+an example of an SSE response:
+
+```ruby
+require 'tipi'
+
+def sse_response(request)
+  request.send_headers('Content-Type': 'text/event-stream')
+  move_on_after(10) {
+    loop {
+      request.send_chunk("data: #{Time.now}\n\n")
+      sleep 1
+    }
+  }
+ensure
+  request.send_chunk("retry: 0\n\n", done: true)
+end
+
+Tipi.serve('0.0.0.0', 1234, &method(:sse_response))
+```
+