polyphony 0.33 → 0.34

data/docs/api-reference/polyphony.md

@@ -0,0 +1,36 @@
+---
+layout: page
+title: Polyphony
+parent: API Reference
+permalink: /api-reference/polyphony/
+---
+# Polyphony
+
+The `Polyphony` module acts as a namespace containing general Polyphony
+functionalities.
+
+## Class Methods
+
+### #emit_signal_exception(exception, fiber = Thread.main.main_fiber) → thread
+
+Emits an exception to the given fiber from a signal handler.
+
+### #fork({ block }) → pid
+
+Forks a child process running the given block. Due to the way Ruby implements
+fibers, along with how signals interact with them, Polyphony-based applications
+should use `Polyphony#fork` rather than `Kernel#fork`. In order to continue
+handling fiber scheduling and signal handling correctly, the child process does
+the following:
+
+- A new fiber is created using `Fiber#new` and control is transferred to it.
+- Notify the event loop that a fork has occurred (by calling `ev_loop_fork`).
+- Setup the current fiber as the main thread's main fiber.
+- Setup fiber scheduling for the main thread.
+- Install fiber-aware signal handlers for the `TERM` and `INT` signals.
+- Run the block.
+- Correctly handle uncaught exceptions, including `SystemExit` and `Interrupt`.
+
+### #watch_process(cmd = nil, { block })
+
+Alternative for [`Polyphony::Process.watch`](../polyphony-process/#watchcmd--nil--block-).

data/docs/api-reference/thread.md

@@ -0,0 +1,88 @@
+---
+layout: page
+title: ::Thread
+parent: API Reference
+permalink: /api-reference/thread/
+---
+# ::Thread
+
+[Ruby core Thread documentation](https://ruby-doc.org/core-2.7.0/Thread.html)
+
+Polyphony enhances the core `Thread` class with APIs for switching and
+scheduling fibers, and reimplements some of its APIs such as `Thread#raise`
+using fibers which, incidentally, make it safe.
+
+Each thread has its own run queue and its own event selector. While running
+multiple threads does not result in true parallelism in MRI Ruby, sometimes
+multithreading is inevitable, for instance when using third-party gems that
+spawn threads, or when calling blocking APIs that are not fiber-aware.
+
+## Class Methods
+
+## Instance methods
+
+### #&lt;&lt;(object) → fiber<br>#send(object) → fiber
+
+Sends a message to the thread's main fiber. For further details see
+[`Fiber#<<`](../fiber/#object--fibersendobject--fiber).
+
+### #fiber_scheduling_stats → stats
+
+Returns statistics relating to fiber scheduling for the thread with the
+following entries:
+
+- `:scheduled_fibers` - number of fibers currently in the run queue
+- `:pending_watchers` - number of currently pending event watchers
+
+### #join → object<br>#await → object
+
+Waits for the thread to finish running. If the thread has terminated with an
+uncaught exception, it will be reraised in the context of the calling fiber. If
+no excecption is raised, returns the thread's result.
+
+```ruby
+t = Thread.new { sleep 1 }
+t.join
+```
+
+### #main_fiber → fiber
+
+Returns the main fiber for the thread.
+
+### #result → object
+
+Returns the result of the thread's main fiber.
+
+```ruby
+t = Thread.new { 'foo' }
+t.join
+t.result #=> 'foo'
+```
+
+### #switch_fiber
+
+invokes a switchpoint, selecting and resuming the next fiber to run. The
+switching algorithm works as follows:
+
+- If the run queue is not empty, conditionally run the event loop a single time
+  in order to prevent event starvation when there's always runnable fibers
+  waiting to be resumed.
+- If the run queue is empty, run the event loop until a fiber is put on the run
+  queue.
+- Switch to the first fiber in the run queue.
+
+This method is normally not called directly by the application. Calling
+`Thread#switch_fiber` means the current fiber has no more work to do and would
+like yield to other fibers. Note that if the current fiber needs to resume at a
+later time, it should be scheduled before calling `Thread#switch_fiber`.
+
+```ruby
+# schedule current fiber to be resumed later
+Fiber.current.schedule
+
+# switch to another fiber
+Thread.current.switch_fiber
+
+# the fiber is resumed
+resume_work
+```

data/docs/getting-started/tutorial.md

@@ -163,7 +163,7 @@ The `handle_client` method is almost trivial:
 ```ruby
 def handle_client(client)
   while (data = client.gets)
-    client.write('you said: ', data.chomp, "!\n")
+    client << data
   end
 rescue Errno::ECONNRESET
   puts 'Connection reset by client'
@@ -239,195 +239,98 @@ thus reset the cancel scope timer.
 In addition, we use an `ensure` block to make sure the client connection is
 closed, whether or not it was interrupted by the cancel scope timer. The habit
 of always cleaning up using `ensure` in the face of potential interruptions is a
-fundamental element of using Polyphony correctly. It makes your code robust,
+fundamental element of using Polyphony correctly. This makes your code robust,
 even in a highly chaotic concurrent execution environment where tasks can be
 interrupted at any time.
 
-Here's the complete source code for our Polyphony-based echo server:
+## Implementing graceful shutdown
 
-```ruby
-require 'polyphony/auto_run'
+Let's now add graceful shutdown to our server. This means that when the server
+is stopped we'll first stop accepting new connections, but we'll let any already
+connected clients keep their sessions.
 
-server = TCPServer.open('127.0.0.1', 1234)
-puts 'Echoing on port 1234...'
+Polyphony's concurrency model is structured. Fibers are limited to the lifetime
+of their direct parent. When the main fiber terminates (on program exit), it
+will terminate all its child fibers, each of which will in turn terminate its
+own children. The termination of child fibers is implemented by sending each
+child fiber a `Polyphony::Terminate` exception. We can implement custom
+termination logic simply by adding an exception handler for
+`Polyphony::Terminate`:
 
-def handle_client(client)
-  timeout = cancel_after(10)
+```ruby
+# We first refactor the echo loop into a method
+def client_loop(client, timeout = nil)
   while (data = client.gets)
-    timeout.reset
+    timeout&.reset
     client << data
   end
+end
+
+def handle_client(client)
+  timeout = cancel_after(10)
+  client_loop(client, timeout)
 rescue Polyphony::Cancel
   client.puts 'Closing connection due to inactivity.'
+rescue Polyphony::Terminate
+  # We add a handler for the Terminate exception, and give 
+  client.puts 'Server is shutting down. You have 5 more seconds...'
+  move_on_after(5) do
+    client_loop(client)
+  end
 rescue Errno::ECONNRESET
   puts 'Connection reset by client'
 ensure
   timeout.stop
   client.close
 end
-
-while (client = server.accept)
-  spin { handle_client(client) }
-end
-```
-
-## Waiting and Interrupting
-
-Polyphony makes it very easy to run multiple concurrent fibers. You can
-basically start a fiber for any operation that involves talking to the outside
-world - running a database query, making an HTTP request, sending off a webhook
-invocation etc. While it's trivial to spin off thousands of fibers, we'd also
-like a way to control all those fibers.
-
-Polyphony provides a number of tools for controlling fiber execution. Let's
-examine some of these tools and how they work. Suppose we have a fiber that was
-previously spun:
-
-```ruby
-fiber = spin { do_some_work }
 ```
 
-We can wait for the fiber to terminate:
-
-```ruby
-fiber.await # alternatively fiber.join
-```
-
-Notice that the await call returns the return value of the fiber block:
-
-```ruby
-fiber = spin { 2 + 2}
-fiber.await #=> 4
-```
-
-We can also stop the fiber at any point:
-
-```ruby
-fiber.stop # or fiber.interrupt
-```
-
-We can inject a return value for the fiber using `stop`:
-
-```ruby
-fiber = spin do
-  sleep 1
-  1 + 1
-end
-
-spin { puts "1 + 1 = #{fiber.await} wha?" }
-
-fiber.stop(3)
-suspend
-```
-
-We can also *cancel* the fiber, which raises a `Polyphony::Cancel` exception:
-
-```ruby
-fiber.cancel!
-```
+## Conclusion
 
-And finally, we can interrupt the fiber with an exception raised in its current
-context:
+In this tutorial, we have shown how Polyphony can be used to create robust,
+highly concurrent Ruby applications. As we have discussed above, Polyphony
+provides a comprehensive set of tools that make it simple and intuitive to write
+concurrent applications, with features such as structured concurrency (for
+controlling fiber lifetime), timeouts (for handling inactive or slow clients),
+custom termination logic (for implementing graceful shutdown).
 
-```ruby
-fiber.raise 'foo'
-```
-
-For more information on how exceptions are handled in Polyphony, see [exception
-handling](../../main-concepts/exception-handling/).
-
-## Supervising - controlling multiple fibers at once
-
-Here's a simple example that we'll use to demonstrate some of the tools provided
-by Polyphony for controlling fibers. Let's build a script that fetches the local
-time for multiple time zones:
+Here's the complete source code for our Polyphony-based echo server:
 
 ```ruby
-require 'polyphony'
-require 'httparty'
-require 'json'
+require 'polyphony/auto_run'
 
-def get_time(tzone)
-  res = HTTParty.get("http://worldtimeapi.org/api/timezone/#{tzone}")
-  json = JSON.parse(res.body)
-  Time.parse(json['datetime'])
-end
+server = TCPServer.open('127.0.0.1', 1234)
+puts 'Echoing on port 1234...'
 
-zones = %w{
-  Europe/London Europe/Paris Europe/Bucharest America/New_York Asia/Bangkok
-}
-zones.each do |tzone|
-  spin do
-    time = get_time(tzone)
-    puts "Time in #{tzone}: #{time}"
+def client_loop(client, timeout = nil)
+  while (data = client.gets)
+    timeout&.reset
+    client << data
   end
 end
 
-suspend
-```
-
-Now that we're familiar with the use of the `#spin` method, we know that all
-those HTTP requests will be processed concurrently, and we can expect those 5
-separate requests to occur within a fraction of a second (depending on our
-machine's location). Also notice how we just used `httparty` with fiber-level
-concurrency, without any boilerplate or employing special wrapper classes.
-
-Just as before, we suspend the main fiber after spinning off the worker fibers,
-in order to wait for everything else to be done. But what if we needed to do
-other work? For example, we might want to collect the different local times into
-a hash to be processed later. In that case, we can use a `Supervisor`:
-
-```ruby
-def get_times(zones)
-  Polyphony::Supervisor.new do |s|
-    zones.each do |tzone|
-      s.spin { [tzone, get_time(tzone)] }
-    end
+def handle_client(client)
+  timeout = cancel_after(10)
+  client_loop(client, timeout)
+rescue Polyphony::Cancel
+  client.puts 'Closing connection due to inactivity.'
+rescue Polyphony::Terminate
+  client.puts 'Server is shutting down. You have 5 more seconds...'
+  move_on_after(5) do
+    client_loop(client)
   end
+rescue Errno::ECONNRESET
+  puts 'Connection reset by client'
+ensure
+  timeout.stop
+  client.close
 end
 
-get_times(zones).await.each do |tzone, time|
-  puts "Time in #{tzone}: #{time}"
-end
-```
-
-There's quite a bit going on here, so let's break it down. We first construct a
-supervisor and spin our fibers in its context using `Supervisor#spin`.
-
-```ruby
-Polyphony::Supervisor.new do |s|
-  ...
-  s.spin { ... }
-  ...
+while (client = server.accept)
+  spin { handle_client(client) }
 end
 ```
 
-Once our worker fibers are spun, the supervisor can be used to control them. We
-can wait for all fibers to terminate using `Supervisor#await`, which returns an
-array with the return values of all fibers (in the above example, each fiber
-returns the time zone and the local time).
-
-```ruby
-results = supervisor.await
-```
-
-We can also select the result of the first fiber that has finished executing.
-All the other fibers will be interrupted:
-
-```ruby
-result, fiber = supervisor.select
-```
-
-(Notice how `Supervisor#select` returns both the fiber's return value and the
-fiber itself).
-
-We can also interrupt all the supervised fibers by using `Supervisor#interrupt`
-(or `#stop`) just like with single fibers:
-
-```ruby
-supervisor.interrupt
-```
-
 ## What Else Can I Do with Polyphony?
 
 Polyphony currently provides support for any library that uses Ruby's stock

data/docs/index.md

@@ -14,7 +14,9 @@ implements a comprehensive
 using [libev](https://github.com/enki/libev) as a high-performance event reactor
 for I/O, timers, and other asynchronous events.
 
+[FAQ](faq){: .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" }
 {: .mt-6 .h-align-center }
 
 ## Focused on Developer Happiness

data/examples/core/forever_sleep.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'polyphony'
+
+trap('TERM') do
+  # do nothing
+end
+
+trap('INT') do
+  # do nothing
+end
+
+puts "go to sleep"
+begin
+  sleep
+ensure
+  puts "done sleeping"
+end

data/examples/core/xx-caller.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'polyphony'
+
+spin {
+  spin {
+    spin {
+      pp Fiber.current.caller
+    }.await
+  }.await
+}.await

data/examples/core/xx-exception-backtrace.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+class E < Exception
+  def initialize(msg)
+    super
+    # set_backtrace(caller)
+  end
+
+  alias_method :orig_backtrace, :backtrace
+  def backtrace
+    b = orig_backtrace
+    p [:backtrace, b, caller]
+    b
+  end
+end
+
+def e1
+  e2
+end
+
+def e2
+  E.new('foo')
+end
+
+def e3
+  raise E, 'bar'
+end
+
+e = e1
+p e
+puts e.backtrace&.join("\n")
+
+begin
+  e3
+rescue Exception => e
+  p e
+  puts e.backtrace.join("\n")
+end