polyphony 0.34 → 0.41

data/docs/api-reference.md

@@ -7,5 +7,5 @@ alphabetical_order: true
 section: true
 has_toc: false
 nav_order: 5
-section_link: /api-reference/fiber
+section_link: /api-reference/exception
 ---

data/docs/api-reference/fiber.md

@@ -71,6 +71,24 @@ f << 2
 result = receive #=> 20
 ```
 
+### #auto_watcher → async
+
+Returns a reusable `Gyro::Async` watcher instance associated with the fiber.
+This method provides a way to minimize watcher allocation. Instead of allocating
+a new async watcher every time one is needed, the same watcher associated with
+the fiber is reused.
+
+```ruby
+def work(async)
+  do_something
+  async.signal
+end
+
+async = Fiber.current.auto_watcher
+spin { work(async) }
+async.await
+```
+
 ### #await → object<br>#join → object
 
 Awaits the termination of the fiber. If the fiber terminates with an uncaught

data/docs/api-reference/gyro-async.md

@@ -0,0 +1,57 @@
+---
+layout: page
+title: Gyro::Async
+parent: API Reference
+permalink: /api-reference/gyro-async/
+---
+# Gyro::Async
+
+`Gyro::Async` encapsulates a libev [async
+watcher](http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_async_code_how_to_wake_up_an),
+allowing thread-safe synchronisation and signalling. `Gyro::Async` watchers are
+used both directly and indirectly in Polyphony to implement
+[queues](../gyro-queue/), await fibers and threads, and auxiliary features such
+as [thread pools](../polyphony-threadpool/).
+
+A `Gyro::Async` watcher instance is shared across two or more fibers (across one
+or more threads), where one fiber waits to be signalled by calling
+`Gyro::Async#await`, and one or more other fibers do the signalling by calling
+`Gyro::Async#signal`:
+
+```ruby
+async = Gyro::Async.new
+spin do
+  sleep 1
+  async.signal
+end
+
+async.await
+```
+
+The signalling of async watchers is compressed, which means that multiple
+invocations of `Gyro::Async#signal` before the event loop can continue will
+result the watcher being signalled just a single time.
+
+In addition to signalling, the async watcher can also be used to transfer an
+arbitrary value to the awaitng fiber. See `#signal` for an example.
+
+## Instance methods
+
+### #await → object
+
+Blocks the current thread until the watcher is signalled.
+
+### #initialize
+
+Initializes the watcher instance.
+
+### #signal(value = nil) → async
+
+Signals the watcher, causing the fiber awaiting the watcher to become runnable
+and be eventually resumed with the given value.
+
+```ruby
+async = Gyro::Async.new
+spin { async.signal('foo') }
+async.await #=> 'foo'
+```

data/docs/api-reference/gyro-child.md

@@ -0,0 +1,29 @@
+---
+layout: page
+title: Gyro::Child
+parent: API Reference
+permalink: /api-reference/gyro-child/
+---
+# Gyro::Child
+
+`Gyro::Child` encapsulates a libev [child
+watcher](http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_child_code_watch_out_for_pro),
+used for waiting for a child process to terminate. A `Gyro::Child` watcher
+instance can be used for low-level control of child processes, instead of using
+more high-level APIs such `Process.wait` etc.
+
+## Instance methods
+
+### #await → [pid, exitcode]
+
+Blocks the current thread until the watcher is signalled. The return value is an
+array containing the child's pid and the exit code.
+
+```ruby
+pid = Polyphony.fork { sleep 1 }
+Gyro::Child.new(pid).await #=> [pid, 0]
+```
+
+### #initialize(pid)
+
+Initializes the watcher instance with the given pid

data/docs/api-reference/gyro-queue.md

@@ -0,0 +1,44 @@
+---
+layout: page
+title: Gyro::Queue
+parent: API Reference
+permalink: /api-reference/gyro-queue/
+---
+# Gyro::Queue
+
+`Gyro::Queue` implements a polyphonic (fiber-aware) queue that can store 0 or
+more items of any data types. Adding an item to the queue never blocks.
+Retrieving an item from the queue will block if the queue is empty.
+`Gyro::Queue` is both fiber-safe and thread-safe. This means multiple fibers
+from multiple threads can concurrently interact with the same queue.
+`Gyro::Queue` is used pervasively across the Polyphony code base for
+synchronisation and fiber control.
+
+## Instance methods
+
+### #&lt;&lt;(object) → queue<br>#push(object) → queue
+
+Adds an item to the queue.
+
+### #clear → queue
+
+Removes all items currently in the queue.
+
+### #empty? → true or false
+
+Returns true if the queue is empty. Otherwise returns false.
+
+### #initialize
+
+Initializes an empty queue.
+
+### #shift → object<br>#pop → object
+
+Retrieves an item from the queue. If the queue is empty, `#shift` blocks until
+an item is added to the queue or until interrupted. Multiple fibers calling
+`#shift` are served in a first-ordered first-served manner.
+
+### #shift_each → [*object]<br>#shift_each({ block }) → queue
+
+Removes and returns all items currently in the queue. If a block is given, it
+will be invoked for each item.

data/docs/api-reference/gyro-timer.md

@@ -0,0 +1,51 @@
+---
+layout: page
+title: Gyro::Timer
+parent: API Reference
+permalink: /api-reference/gyro-timer/
+---
+# Gyro::Timer
+
+`Gyro::Timer` encapsulates a libev [timer
+watcher](http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_timer_code_relative_and_opti),
+allowing waiting a certain amount of time before proceeding with an operation.
+Watchers can be either one-time timers or recurring timers. The Polyphony API
+provides various APIs that use timer watchers for timeouts, throttled
+operations, and sleeping.
+
+## Instance methods
+
+### #await → object
+
+Blocks the current thread until the timer has elapsed. For recurrent timers,
+`#await` will block until the next timer period has elapsed, as specified by the
+`repeat` argument given to `#initialize`.
+
+### #initialize(after, repeat)
+
+Initializes the watcher instance. The `after` argument gives the time duration
+in seconds before the timer has elapsed. The `repeat` argument gives the time
+period for recurring timers, or `0` for non-recurring timers.
+
+### #stop
+
+Stops an active recurring timer. Recurring timers stay active (from the point of
+view of the event loop) even after the timer period has elapsed. Calling `#stop`
+marks the timer as inactive and cleans up associated resources. This should
+normally be done inside an `ensure` block:
+
+```ruby
+def repeat(period)
+  timer = Gyro::Timer.new(period, period)
+  loop do
+    timer.await
+    yield
+  end
+ensure
+  timer.stop
+end
+
+repeat(10) { puts Time.now }
+```
+
+There's no need to call `#stop` for non-recurring timers.

data/docs/api-reference/gyro.md

@@ -0,0 +1,25 @@
+---
+layout: page
+title: Gyro
+parent: API Reference
+permalink: /api-reference/gyro/
+---
+# Gyro
+
+`Gyro` is the subsystem in charge of the low-level functionality in Polyphony.
+It contains all of the different event watcher classes, as well as other
+low-level constructs such as `Gyro::Queue`, a fiber-aware queue implementation,
+used pervasively across the Polyphony code base.
+
+While most Polyphony-based applications do not normally need to interact
+directly with the `Gyro` classes, more advanced applications and libraries may
+use those classes to enhance Polyphony and create custom concurrency patterns.
+
+## Classes
+
+- [`Gyro::Async`](../gyro-async/) - async event watcher
+- [`Gyro::Child`](../gyro-child/) - child process event watcher
+- [`Gyro::IO`](../gyro-io/) - IO event watcher
+- [`Gyro::Queue`](../gyro-queue/) - fiber-aware queue
+- [`Gyro::Signal`](../gyro-signal/) - signal event watcher
+- [`Gyro::Timer`](../gyro-timer/) - timer event watcher

data/docs/index.md

@@ -14,8 +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 }
+[Main Concepts](main-concepts/concurrency/){: .btn .btn-green .text-gamma }
+[FAQ](faq){: .btn .btn-green .text-gamma }
 [Source code](https://github.com/digital-fabric/polyphony){: .btn .btn-purple .text-gamma target="_blank" }
 {: .mt-6 .h-align-center }
 
@@ -64,8 +65,8 @@ adapters are being developed.
 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 is
-  largely a spinoff of
+  [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)
@@ -73,11 +74,13 @@ Polyphony draws inspiration from the following, in no particular order:
 * [Erlang supervisors](http://erlang.org/doc/man/supervisor.html) (and actually,
   Erlang in general)
 
-## Going further
+## Developer Resources
 
-To learn more about using Polyphony to build concurrent applications, continue reading, or look at the [bundled
-examples](https://github.com/digital-fabric/polyphony/tree/9e0f3b09213156bdf376ef33684ef267517f06e8/examples/README.md).
-A thorough API reference is forthcoming.
+* [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
 

data/docs/main-concepts/design-principles.md

@@ -1,18 +1,76 @@
 ---
 layout: page
-title: Design Principles
+title: The Design of Polyphony
 nav_order: 5
 parent: Main Concepts
 permalink: /main-concepts/design-principles/
 prev_title: Extending Polyphony
 ---
-# Design Principles
+# The Design of Polyphony 
+
+Polyphony is a new gem that aims to enable developing high-performance
+concurrent applications in Ruby using a fluent, compact syntax and API.
+Polyphony enables fine-grained concurrency - the splitting up of operations into
+a large number of concurrent tasks, each concerned with small part of the whole
+and advancing at its own pace. Polyphony aims to solve some of the problems
+associated with concurrent Ruby programs using a novel design that sets it apart
+from other approaches currently being used in Ruby.
+
+## Origins
+
+The Ruby core language (at least in its MRI implementation) currently provides
+two main constructs for performing concurrent work: threads and fibers. While
+Ruby threads are basically wrappers for OS threads, fibers are essentially
+continuations, allowing pausing and resuming distinct computations. Fibers have
+been traditionally used mostly for implementing enumerators and generators.
+
+In addition to the core Ruby concurrency primitives, some Ruby gems have been
+offering an alternative solution to writing concurrent Ruby apps, most notably
+[EventMachine](https://github.com/eventmachine/eventmachine/), which implements
+an event reactor and offers an asynchronous callback-based API for writing
+concurrent code.
+
+In the last couple of years, however, fibers have been receiving more attention
+as a possible constructs for writing concurrent programs. In particular, the
+[Async](https://github.com/socketry/async) framework, created by [Samuel
+Williams](https://github.com/ioquatix), offering a comprehensive set of
+libraries, employs fibers in conjunction with an event reactor provided by the
+[nio4r](https://github.com/socketry/nio4r) gem, which wraps the C
+library [libev](http://software.schmorp.de/pkg/libev.html).
+
+In addition, recently some effort was undertaken to provide a way to
+[automatically switch between fibers](https://bugs.ruby-lang.org/issues/13618)
+whenever a blocking operation is performed, or to [integrate a fiber
+scheduler](https://bugs.ruby-lang.org/issues/16786) into the core Ruby code.
+
+Nevertheless, while work is being done to harness fibers for providing a better
+way to do concurrency in Ruby, fibers remain a mistery for most Ruby
+programmers, a perplexing unfamiliar corner right at the heart of Ruby.
+
+## Design Principles
+
+Polyphony started as an experiment, but over about two years of slow, jerky
+evolution turned into something I'm really excited to share with the Ruby
+community. Polyphony's design is both similar and different than the projects
+mentioned above.
+
+Polyphony today as nothing like the way it began. A careful examination of the
+[CHANGELOG](https://github.com/digital-fabric/polyphony/blob/master/CHANGELOG.md)
+would show how Polyphony explored not only different event reactor designs, but
+also different API designs incorporating various concurrent paradigms such as
+promises, async/await, fibers, and finally structured concurrency. 
+
+While Polyphony, like nio4r or EventMachine, uses an event reactor to turn
+blocking operations into non-blocking ones, it completely embraces fibers and in
+fact does not provide any callback-based APIs. Furthermore, Polyphony provides
+fullblown fiber-aware implementations of blocking operations, such as
+`read/write`, `sleep` or `waitpid`, instead of just event watching primitives.
+
+Throughout the development process, it was my intention to create a programming
+interface that would make highly-concurrent 
+
+
 
-Polyphony was created in order to enable developing high-performance concurrent
-applications in Ruby using a fluent, compact syntax and API. Polyphony enables
-fine-grained concurrency - the splitting up of operations into a large number of
-concurrent tasks, each concerned with small part of the whole and advancing at
-its own pace.
 
 
 
@@ -46,8 +104,8 @@ library. Polyphony's design is based on the following principles:
   async callback-style APIs.
 
   ```ruby
-  # in Polyphony, I/O ops block the current fiber, but implicitly yield to other
-  # concurrent fibers:
+  # in Polyphony, I/O ops might block the current fiber, but implicitly yield to
+  # other concurrent fibers:
   clients.each { |client|
     spin { client.puts 'Elvis has left the chatroom' }
   }

data/docs/main-concepts/extending.md

@@ -5,7 +5,7 @@ nav_order: 4
 parent: Main Concepts
 permalink: /main-concepts/extending/
 prev_title: Exception Handling
-next_title: Design Principles
+next_title: The Design of Polyphony
 ---
 # Extending Polyphony
 

data/docs/main-concepts/fiber-scheduling.md

@@ -15,9 +15,9 @@ switching between fibers works in Ruby.
 
 Ruby provides two mechanisms for transferring control between fibers:
 `Fiber#resume` /`Fiber.yield` and `Fiber#transfer`. The first is inherently
-asymmetric and is famously used for implementing generators and [resumable
+asymmetric and is mostly used for implementing generators and [resumable
 enumerators](https://blog.appsignal.com/2018/11/27/ruby-magic-fibers-and-enumerators-in-ruby.html).
-Here's a small example:
+Here's an example:
 
 ```ruby
 fib = Fiber.new do
@@ -31,7 +31,7 @@ end
 10.times { puts fib.resume }
 ```
 
-Another implication of using resume / yield is that the main fiber can't yield
+An implication of using resume / yield is that the main fiber can't yield
 away, meaning we cannot pause the main fiber using `Fiber.yield`.
 
 The other fiber control mechanism, using `Fiber#transfer`, is fully symmetric:
@@ -45,46 +45,48 @@ ping.transfer
 ```
 
 `Fiber#transform` also allows using the main fiber as a general purpose
-resumable execution context. Polyphony uses `Fiber#transfer` exclusively for
-scheduling fibers.
+resumable execution context. For that reason, Polyphony uses `Fiber#transfer`
+exclusively for scheduling fibers. Normally, however, applications based on
+Polyphony will not use this API directly.
 
 ## The Different Fiber states
 
-In Polyphony, each fiber has one four possible states:
+In Polyphony, each fiber has one of four possible states:
 
-A new fiber will start in a `:waiting` state. The `#spin` global method will
-create the fiber and schedule it for execution, marking it as `:runnable`. When
-the fiber is run, it is in a `:running` state. Finally, when the fiber has
-terminated, it transitions to the `:dead` state.
-
-Whenever a fiber performs a blocking operation - such as waiting for a timer to
-elapse, or for a socket to become readable, or for a child process to terminate -
-it transitions to a `:waiting` state. Once the timer has elapsed, the socket
-has become readable, or the child process has terminated, the fiber is marked as
-`:runnable`. It then waits its turn to run.
+- `:runnable` - a new fiber will start in the runnable state. This means it is
+  placed on the thread's run queue and is now waiting its turn to be resumed.
+- `:running` - once the fiber is resumed, it transitions to the running state.
+  `Fiber.current.state` always returns `:running`.
+- `:wait` - whenever the fiber performs a blocking operation—such as waiting for
+  a timer to elapse, or for a socket to become readable—the fiber transitions to
+  a waiting state. When the corresponding event occurs the fiber will transition
+  to a `:runnable` state, and will be eventually resumed (`:running`).
+- `:dead` - once the fiber has terminated, it transitions to the dead state.
 
 ## Switchpoints
 
-A switchpoint is any point in time at which control might switch from the
+A switchpoint is any point in time at which control *might* switch from the
 currently running fiber to another fiber that is `:runnable`. This usually
-occurs when the currently running fiber starts a blocking operation. It also
-occurs when the running fiber has yielded control using `#snooze` or `#suspend`.
-A Switchpoint will also occur when the currently running fiber has terminated.
+occurs when the currently running fiber starts a blocking operation, such as
+reading from a socket or waiting for a timer. It also occurs when the running
+fiber has explicitly yielded control using `#snooze` or `#suspend`. A
+Switchpoint will also occur when the currently running fiber has terminated.
 
 ## Scheduler-less scheduling
 
 Polyphony relies on [libev](http://software.schmorp.de/pkg/libev.html) for
 handling events such as I/O readiness, timers and signals. In most event
 reactor-based libraries and frameworks, such as `nio4r`, `EventMachine` or
-`node.js`, the reactor loop is run, and event callbacks are used to schedule
-user-supplied code *from inside the loop*. In Polyphony, however, we have chosen
-a programming model that does not use a loop to schedule fibers. In fact, in
-Polyphony there's no such thing as a reactor loop, and there's no *scheduler*
-per se running on a separate execution context.
+`node.js`, the entire application is run inside of a reactor loop, and event
+callbacks are used to schedule user-supplied code *from inside the loop*.
+
+In Polyphony, however, we have chosen a concurrency model that does not use a
+loop to schedule fibers. In fact, in Polyphony there's no outer reactor loop,
+and there's no *scheduler* per se running on a separate execution context.
 
 Instead, Polyphony maintains for each thread a run queue, a list of `:runnable`
-fibers. If no fiber is `:runnable`, the libev event reactor will be ran until
-one or more events have occurred. Events are handled by adding the corresponding
+fibers. If no fiber is `:runnable`, Polyphony will run the libev event loop until
+at least one event has occurred. Events are handled by adding the corresponding
 fibers onto the run queue. Finally, control is transferred to the first fiber on
 the run queue, which will run until it blocks or terminates, at which point
 control is transferred to the next runnable fiber.
@@ -95,8 +97,8 @@ This approach has numerous benefits:
   leading to less context switches, and less bookkeeping.
 - Clear separation between the reactor code (the `libev` code) and the fiber
   scheduling code.
-- Much less time is spent in reactor loop callbacks, letting the reactor loop
-  run more efficiently.
+- Much less time is spent in event loop callbacks, letting the event loop run
+  more efficiently.
 - Fibers are switched outside of the event reactor code, making it easier to
   avoid race conditions and unexpected behaviours.
 
@@ -121,9 +123,9 @@ are waiting and the main fiber is done running, the Ruby process will terminate.
 ## Interrupting blocking operations
 
 Sometimes it is desirable to be able to interrupt a blocking operation, such as
-waiting for a socket to be readable, or sleeping for an extended period of time.
-This is especially useful when higher-level constructs are needed for
-controlling multiple concurrent operations.
+waiting for a socket to be readable, or sleeping. This is especially useful when
+higher-level constructs are needed for controlling multiple concurrent
+operations.
 
 Polyphony provides the ability to interrupt a blocking operation by harnessing
 the ability to transfer values back and forth between fibers using
@@ -134,52 +136,24 @@ signalling that the blocking operation has been unsuccessful and allowing
 exception handling using the builtin mechanisms offered by Ruby, namely `rescue`
 and `ensure` (see also [exception handling](exception-handling.md)).
 
-Here's a naive implementation of a yielding I/O read operation in Polyphony (the
-actual code for I/O reading in Polyphony is written in C and is a bit more
-involved):
+This mode of operation makes implementing timeouts almost trivial:
 
 ```ruby
-def read_from(io)
-  loop do
-    result = IO.readnonblock(8192, exception: false)
-    if result == :wait_readable
-      wait_readable(io)
-    else
-      return result
-    end
+def with_timeout(duration)
+  interruptible_fiber = Fiber.current
+  timeout_fiber = spin do
+    sleep duration
+    interruptible_fiber.raise 'timeout'
   end
-end
-
-def wait_readable(io)
-  fiber = Fiber.current
-  watcher = Gyro::IO.new(io, :read) { fiber.transfer }
-
-  # run any scheduled fibers or run libev reactor waiting for events 
-  result = GV.run
-
-  # waiting fiber is resumed - check transferred value
-  raise result if result.is_a?(Exception)
-  result
+  
+  # do work
+  yield
 ensure
-  # ensure the I/O watcher is deactivated, even if exception is raised
-  watcher.active = false
+  timeout_fiber.terminate
 end
-```
 
-In the above example, the `wait_readable` method will normally wait indefinitely
-until the IO object has become readable. But we could interrupt it at any time
-by scheduling the corresponding fiber with an exception:
-
-```ruby
-def timeout(duration)
-  fiber = Fiber.current
-  interrupter = spin do
-    Gyro::Timer.new(duration, 0).await
-    fiber.transfer(TimerException.new)
-  end
-  yield
-ensure
-  interrupter.stop
+with_timeout(10) do
+  HTTParty.get 'https://acme.com/'
 end
 ```
 
@@ -187,6 +161,15 @@ end
 
 Polyphony performs fiber scheduling separately for each thread. Each thread,
 therefore, will be able to run multiple fibers independently from other threads.
+Multithreading in Ruby has limited benefit, due to the global virtual lock that
+prevents true parallelism. But offloading work to a separate thread might be
+eneficial when a Polyphonic app needs to use APIs that are not fiber-aware, such
+as blocking database calls (SQLite in particular), or system calls that might
+block for an extended duration.
+
+For this, you can either spawn a new thread, or use the provided
+`Polyphony::ThreadPool` class that allows you to offload work to a pool of
+threads.
 
 ## The fiber scheduling algorithm in full