polyphony 0.40 → 0.43.2

data/docs/_sass/custom/custom.scss

@@ -1,30 +1,10 @@
-$nav-child-link-color: #9d9b9e;
-$link-color: $blue-000;
 
-.img-figure {
-  text-align: center;
+h1.logo-title {
+  font-size: 42px !important;
+  font-weight: bold;
 }
 
-#prevnext {
-  padding-top: 1em;
+h2.logo-title {
+  margin-top: 0.25em;
+  margin-bottom: 1em;
 }
-
-#prevnext span {
-}
-
-#prevnext span.prev {
-  float: left;
-  padding-right: 4em;
-}
-
-#prevnext span.next {
-  float: right;
-}
-
-#prevnext span.clear {
-  clear: both;
-}
-
-.h-align-center {
-  text-align: center;
-}

data/docs/_sass/overrides.scss

@@ -1,46 +0,0 @@
-.navigation-list-item.section-title {
-  padding-top: 0.75em;
-  padding-bottom: 0.75em;
-}
-
-span.section-title {
-  text-transform: uppercase;
-  font-weight: bold;
-  color: #888;
-}
-
-.navigation-list-item .navigation-list-child-list {
-  display: block;
-}
-
-.navigation-list-child-list {
-  padding-left: 0;
-
-  .navigation-list-item {
-    position: relative;
-
-    &::before {
-      position: absolute;
-      margin-top: 0.3em;
-      margin-left: -0.8em;
-      color: rgba($body-text-color, 0.3);
-      content: "";
-    }
-  }
-}
-
-a.navigation-list-link {
-  margin-left: 4px;
-  padding-left: 4px;
-  color: $nav-child-link-color;
-  font-weight: 600;
-}
-
-a.navigation-list-link.active {
-  margin-left: 0;
-  border-left: 4px #6ae solid;
-}
-
-a.navigation-list-link:hover {
-  color: $link-color;
-}

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/api-reference/fiber.md

@@ -71,7 +71,7 @@ f << 2
 result = receive #=> 20
 ```
 
-### #auto_async → async
+### #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
@@ -84,7 +84,7 @@ def work(async)
   async.signal
 end
 
-async = Fiber.current.auto_async
+async = Fiber.current.auto_watcher
 spin { work(async) }
 async.await
 ```

data/docs/api-reference/index.md

@@ -0,0 +1,9 @@
+---
+layout: page
+title: API Reference
+has_children: true
+nav_order: 5
+---
+
+# API Reference
+{: .no_toc }

data/docs/api-reference/polyphony-process.md

@@ -23,6 +23,6 @@ shell command. If a block is given, the child process is started using
 [`Polyphony#fork`](../polyphony/#fork-block---pid).
 
 ```ruby
-Polyphony::Process.watch('echo "Hello World"; sleep 1')
+spin { Polyphony::Process.watch('echo "Hello World"; sleep 1') }
 supervise(restart: :always)
 ```

data/docs/api-reference/thread.md

@@ -12,7 +12,7 @@ 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
+Each thread has its own run queue and its own system agent. 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.

data/docs/faq.md

@@ -3,9 +3,19 @@ layout: page
 title: Frequently Asked Questions
 nav_order: 100
 ---
+
 # Frequently Asked Questions
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+- TOC
+{:toc}
+
+---
 
-### Why not just use callbacks instead of fibers?
+## Why not just use callbacks instead of fibers?
 
 It is true that reactor engines such as libev use callbacks to handle events.
 There's also programming platforms such as [node.js](https://nodejs.org/) that
@@ -87,7 +97,7 @@ In conclusion:
 * Callbacks often lead to code bloat.
 * Callbacks are harder to debug.
 
-### If callbacks suck, why not use promises?
+## If callbacks suck, why not use promises?
 
 Promises have gained a lot of traction during the last few years as an  
 alternative to callbacks, above all in the Javascript community. While promises
@@ -96,7 +106,7 @@ found to offer enough of a benefit. Promises still cause split logic, are quite
 verbose and provide a non-native exception handling mechanism. In addition, they
 do not make it easier to debug your code.
 
-### Why is awaiting implicit? Why not use explicit async/await?
+## Why is awaiting implicit? Why not use explicit async/await?
 
 Actually, async/await was contemplated while developing Polyphony, but at a
 certain point it was decided to abandon these methods / decorators in favor of a
@@ -108,7 +118,7 @@ Instead, we have decided to make blocking operations implicit and thus allow the
 use of common APIs such as `Kernel#sleep` or `IO.popen` in a transparent manner.
 After all, these APIs in their stock form block execution just as well.
 
-### Why use `Fiber#transfer` and not `Fiber#resume`?
+## Why use `Fiber#transfer` and not `Fiber#resume`?
 
 The API for `Fiber.yield`/`Fiber#resume` is stateful and is intended for the
 asymmetric execution of coroutines. This is useful when using generators, or
@@ -118,7 +128,7 @@ between them, which is much easier to achieve using `Fiber#transfer`. In
 addition, using `Fiber#transfer` allows us to perform blocking operations from
 the main fiber, which is not possible when using `Fiber#resume`.
 
-### Why does Polyphony reimplements core APIs such as `IO#read` and `Kernel#sleep`?
+## Why does Polyphony reimplements core APIs such as `IO#read` and `Kernel#sleep`?
 
 Polyphony "patches" some Ruby core and stdlib APIs, providing behavioraly
 compatible fiber-aware implementations. We believe Polyphony has the potential
@@ -126,7 +136,7 @@ to profoundly change the way concurrent Ruby apps are written. Polyphony is
 therefore designed to feel as much as possible like an integral part of the Ruby
 runtime.
 
-### Why is Polyphony not split into multiple gems?
+## Why is Polyphony not split into multiple gems?
 
 Polyphony is currently at an experimental stage, and its different APIs are
 still in flux. For that reason, all the different parts of Polyphony are
@@ -134,7 +144,7 @@ currently kept in a single gem. Once things stabilize, and as Polyphony
 approaches version 1.0, it will be split into separate gems, each with its own
 functionality.
 
-### Can I use Polyphony in a multithreaded program?
+## Can I use Polyphony in a multithreaded program?
 
 Yes, as of version 0.27 Polyphony implements per-thread fiber-scheduling. It is
 however important to note that Polyphony places the emphasis on a multi-fiber
@@ -148,7 +158,7 @@ are such a better fit for I/O bound Ruby programs. Threads should really be used
 when performing synchronous operations that are not fiber-aware, such as running
 an expensive SQLite query, or some other expensive system call.
 
-### How Does Polyphony Fit Into the Ruby's Future Concurrency Plans
+## How Does Polyphony Fit Into the Ruby's Future Concurrency Plans
 
 To our understanding, two things are currently on the horizon when it comes to
 concurrency in Ruby: [auto-fibers](https://bugs.ruby-lang.org/issues/13618), and
@@ -167,18 +177,18 @@ Polyphony's fiber-based concurrency model. Guilds will allow true parallelism
 and together with Polyphony will allow taking full advantage of multiple CPU
 cores in a single Ruby process.
 
-### Can I run Rails using Polyphony?
+## Can I run Rails using Polyphony?
 
 We haven't yet tested Rails with Polyphony, but most probably not. We do plan to
 support running Rails in an eventual release.
 
-### How can I contribute to Polyphony?
+## How can I contribute to Polyphony?
 
 The Polyphony repository is at
 [https://github.com/digital-fabric/polyphony](https://github.com/digital-fabric/polyphony).
 Feel free to create issues and contribute pull requests.
 
-### Who is behind this project?
+## 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

data/docs/getting-started/index.md

@@ -0,0 +1,10 @@
+---
+layout: page
+title: Getting Started
+description: Getting started with Polyphony
+has_children: true
+nav_order: 2
+---
+
+# Getting Started
+{: .no_toc }

data/docs/getting-started/installing.md

@@ -1,11 +1,8 @@
 ---
 layout: page
 title: Installing Polyphony
-nav_order: 1
 parent: Getting Started
-permalink: /getting-started/installing/
-prev_title: Home
-next_title: Tutorial
+nav_order: 1
 ---
 # Installing Polyphony
 
@@ -13,8 +10,7 @@ next_title: Tutorial
 
 In order to use Polyphony you need to have:
 
-- Linux or MacOS (sorry, there are no plans to support Windows for the time
-  being)
+- Linux or MacOS (support for Windows will come at a later stage)
 - Ruby (MRI) 2.6 or newer
 
 ## Installing the Polyphony Gem

data/docs/getting-started/overview.md

@@ -0,0 +1,486 @@
+---
+layout: page
+title: Overview
+parent: Getting Started
+nav_order: 2
+---
+
+# Polyphony - an Overview
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+- TOC
+{:toc}
+
+---
+
+## Introduction
+
+Polyphony is a new Ruby library for building concurrent applications in Ruby.
+Polyphony provides a comprehensive, structured concurrency model based on Ruby
+fibers and using libev as a high-performance event reactor.
+
+Polyphony is designed to maximize developer happiness. It provides a natural and
+fluent API for writing concurrent Ruby apps while using the stock Ruby APIs such
+as `IO`, `Process`, `Socket`, `OpenSSL` and `Net::HTTP` in a concurrent
+multi-fiber environment. In addition, Polyphony offers a solid
+exception-handling experience that builds on and enhances Ruby's
+exception-handling mechanisms.
+
+Polyphony includes a full-blown HTTP server implementation with integrated
+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
+there's no need to use special classes for building your app, and there's no
+need to setup reactor loops. Everything works the same except you can perform
+multiple operations at the same time by creating fibers. In order to start a new
+concurrent operation, you simply use `Kernel#spin`, which spins up a new fiber
+and schedules it for running:
+
+```ruby
+require 'polyphony'
+
+# Kernel#spin returns a Fiber instance
+counter = spin do
+  count = 1
+  loop do
+    sleep 1
+    puts "count: #{count}"
+    count += 1
+  end
+end
+
+puts "Press return to stop this program"
+gets
+```
+
+The above program spins up a fiber named `counter`, which counts to infinity.
+Meanwhile, the *main* fiber waits for input from the user, and then exits.
+Notice how we haven't introduced any custom classes, and how we used stock APIs
+such as `Kernel#sleep` and `Kernel#gets`. The only hint that this program is
+concurrent is the call to `Kernel#spin`.
+
+Behind the scenes, Polyphony takes care of automatically switching between
+fibers, letting each fiber advance at its own pace according to its duties. For
+example, when the main fiber calls `gets`, Polyphony starts waiting for data to
+come in on `STDIN` and then switches control to the `counter` fiber. When the
+`counter` fiber calls `sleep 1`, Polyphony starts a timer, and goes looking for
+other work. If no other fiber is ready to run, Polyphony simply waits for at
+least one event to occur, and then resumes the corresponding fiber.
+
+## Fibers vs Threads
+
+Most Ruby developers are familiar with threads, but fibers remain a little
+explored and little understood concept in the Ruby language. While A thread is
+an OS abstraction that is controlled by the OS, a fiber represents an execution
+context that can be paused and resumed by the application, and has no
+counterpart at the OS level.
+
+When used for writing concurrent programming, fibers offer multiple benefits
+over threads. They consume much less RAM than threads, and switching between
+them is faster than switching between threads. In addition, since fibers require
+no cooperation from the OS, an application can create literally millions of them
+given enough RAM. Those advantages make fibers a compelling solution for creating
+pervasively concurrent applications, even when using a dynamic high-level "slow"
+language such as Ruby.
+
+Ruby programs will only partly benefit from using mutiple threads for processing
+work loads (due to the GVL), but fibers are a great match mostly for programs
+that are I/O bound (that means spending most of their time talking to the
+outside world). A fiber-based web-server, for example, can juggle thousands of
+active concurrent connections, each advancing at its own pace, consuming only a
+single CPU core.
+
+Nevertheless, Polyphony fully supports multithreading, with each thread having
+its own fiber run queue and its own libev event loop. In addition, Polyphony
+enables cross-thread communication using  
+
+## Fibers vs Callbacks
+
+Programming environments such as Node.js and libraries such as EventMachine have
+popularized the usage of event loops for achieving concurrency. The application
+is wrapped in a loop that polls for events and fires application-provided
+callbacks that act on those events - for example receiving data on a socket
+connection, or waiting for a timer to elapse.
+
+While these callback-based solutions are established technologies and are used
+frequently to build concurrent apps, they do have some major drawbacks. Firstly,
+they force the developer to split the business logic into small pieces, each
+being ran inside of a callback. Secondly, they complicate state management,
+because state associated with the business logic cannot be kept *with* the
+business logic, it has to be stored elsewhere. Finally, callback-based
+concurrency complicates debugging, since a stacktrace at any given point in time
+will always originate in the event loop, and will not contain any information on
+the chain of events leading to the present moment.
+
+Fibers, in contrast, let the developer express the business logic in a
+sequential, easy to read manner: do this, then that. State can be stored right
+in the business logic, as local variables. And finally, the sequential
+programming style makes it much easier to debug your code, since stack traces
+contain the entire history of execution from the app's inception. 
+
+## Structured Concurrency
+
+Polyphony's tagline is "fine-grained concurrency for Ruby", because it makes it
+really easy to spin up literally thousands of fibers that perform concurrent
+work. But running such a large number of concurrent operations also means you
+need tools for managing all that concurrency.
+
+For that purpose, Polyphony follows a paradigm called *structured concurrency*.
+The basic idea behind structured concurrency is that fibers are organised in a
+hierarchy starting from the main fiber. A fiber spun by any given fiber is
+considered a child of that fiber, and its lifetime is guaranteed to be limited
+to that of its parent fiber. That is why in the example above, the `counter`
+fiber is automatically stopped when the main fiber stops running.
+
+The same goes for exception handling. Whenever an error occurs, if no suitable
+`rescue` block has been defined for the fiber in which the exception was raised,
+the exception will bubble up through the fiber's parent, grandparent etc, until
+the exception is handled, up to the main fiber. If the exception was not
+handled, the program will exit and dump the exception information just like a
+normal Ruby program.
+
+## Controlling Fiber Execution
+
+Polyphony offers a wide range of APIs for controlling fibers that make it easy
+to prevent your program turning into an incontrollable concurrent mess. In order
+to control fibers, Polyphony introduces various APIs for stopping fibers,
+scheduling fibers, awaiting for fibers to terminate, and even restarting them:
+
+```ruby
+f = spin do
+  puts "going to sleep"
+  sleep 1
+  puts "done sleeping"
+ensure
+  puts "stopped"
+end
+
+sleep 0.5
+f.stop
+f.restart
+f.await
+```
+
+The output of the above program will be:
+
+```
+going to sleep
+stopped
+going to sleep
+done sleeping
+stopped
+```
+
+The `Fiber#await` method waits for a fiber to terminate, and returns the fiber's
+return value:
+
+```ruby
+a = spin { sleep 1; :foo }
+b = spin { a.await }
+b.await #=> :foo
+```
+
+In the program above the main fiber waits for fiber `b` to terminate, and `b`
+waits for fiber `a` to terminate. The return value of `a.await` is `:foo`, and
+hence the return value of `b.await` is also `foo`.
+
+If we need to wait for multiple fibers, we can use `Fiber::await` or
+`Fiber::select`:
+
+```ruby
+# get result of a bunch of fibers
+fibers = 3.times.map { |i| spin { i * 10 } }
+Fiber.await(*fibers) #=> [0, 10, 20]
+
+# get the fastest reply of a bunch of URLs
+fibers = urls.map { |u| spin { [u, HTTParty.get(u)] } }
+# Fiber.select returns an array containing the fiber and its result
+Fiber.select(*fibers) #=> [fiber, [url, result]]
+```
+
+Finally, fibers can be supervised, in a similar manner to Erlang supervision
+trees. The `Kernel#supervise` method will wait for all child fibers to terminate
+before returning, and can optionally restart any child fiber that has terminated
+normally or with an exception:
+
+```ruby
+fiber1 = spin { sleep 1; raise 'foo' }
+fiber2 = spin { sleep 1 }
+
+supervise # blocks and then propagates the error raised in fiber1 
+```
+
+## Message Passing
+
+Polyphony also provides a comprehensive solution for using fibers as actors, in
+a similar fashion to Erlang processes. Fibers can exchange messages between each
+other, allowing each part of a concurrent system to function in a completely
+autonomous manner. For example, a chat application can encapsulate each chat
+room in a completely self-contained fiber:
+
+```ruby
+def chat_room
+  subscribers = []
+
+  loop do
+    # receive waits for a message to come in
+    case receive
+    # Using Ruby 2.7's pattern matching
+    in [:subscribe, subscriber]
+      subscribers << subscriber
+    in [:unsubscribe, subscriber]
+      subscribers.delete subscriber
+    in [:add_message, name, message]
+      subscribers.each { |s| s.call(name, message) }
+    end
+  end
+end
+
+CHAT_ROOMS = Hash.new do |h, n|
+  h[n] = spin { chat_room }
+end
+```
+
+Notice how the state (the `subscribers` variable) stays local, and how the logic
+of the chat room is expressed in a way that is both compact and easy to extend.
+Also notice how the chat room is written as an infinite loop. This is a common
+pattern in Polyphony, since fibers can always be stopped at any moment. 
+
+The code for handling a chat room user might be expressed as follows:
+
+```ruby
+def chat_user_handler(user_name, connection)
+  room = nil
+  message_subscriber = proc do |name, message|
+    connection.puts "#{name}: #{message}"
+  end
+  while command = connection.gets
+    case command
+    when /^connect (.+)/
+      room&.send [:unsubscribe, message_subscriber]
+      room = CHAT_ROOMS[$1]
+    when "disconnect"
+      room&.send [:unsubscribe, message_subscriber]
+      room = nil
+    when /^send (.+)/
+      room&.send [:add_message, user_name, $1]
+    end
+  end
+end
+```
+
+## Other Concurrency Constructs
+
+Polyphony includes various constructs that complement fibers. Resource pools
+provide a generic solution for controlling concurrent access to limited
+resources, such as database connections. A resource pool assures only one fiber
+has access to a given resource at any time:
+
+```ruby
+DB_CONNECTIONS = Polyphony::ResourcePool.new(limit: 5) do
+  PG.connect(DB_OPTS)
+end
+
+def query_records(sql)
+  DB_CONNECTIONS.acquire do |db|
+    db.query(sql).to_a
+  end
+end
+```
+
+Throttlers can be useful for rate limiting, for example preventing blacklisting
+your system in case it sends too many emails, even across fibers:
+
+```ruby
+MAX_EMAIL_RATE = 10 # max. 10 emails per second
+EMAIL_THROTTLER = Polyphony::Throttler.new(MAX_EMAIL_RATE)
+
+def send_email(addr, content)
+  EMAIL_THROTTLER.process do
+    ...
+  end
+end
+```
+
+In addition, various global methods (defined on the `Kernel` module) provide
+common functionality, such as using timeouts:
+
+```ruby
+# perform an delayed action (in a separate fiber)
+after(10) { notify_user }
+
+# perform a recurring action with time drift correction
+every(1) { p Time.now }
+
+# perform an operation with timeout without raising an exception
+move_on_after(10) { perform_query }
+
+# perform an operation with timeout, raising a Polyphony::Cancel exception
+cancel_after(10) { perform_query }
+```
+
+## The System Agent
+
+In order to implement automatic fiber switching when performing blocking
+operations, Polyphony introduces a concept called the *system agent*. The system
+agent is an object having a uniform interface, that performs all blocking
+operations.
+
+While a standard event loop-based solution would implement a blocking call
+separately from the fiber scheduling, the system agent integrates the two to
+create a blocking call that is already knows how to switch and schedule fibers.
+For example, in Polyphony all APIs having to do with reading from files or
+sockets end up calling `Thread.current.agent.read`, which does all the work.
+
+This design offers some major advantages over other designs. It minimizes memory
+allocations, of both Ruby objects and C structures. For example, instead of
+having to allocate libev watchers on the heap and then pass them around, they
+are allocated on the stack instead, which saves up on both memory and CPU cycles.
+
+In addition, the agent interface includes two methods that allow maximizing
+server performance by accepting connections and reading from sockets in a tight
+loop. Here's a naive implementation of an HTTP/1 server:
+
+```ruby
+require 'http/parser'
+require 'polyphony'
+
+def handle_client(socket)
+  parser = Http::Parser.new
+  reqs = []
+  parser.on_message_complete = proc { |env| reqs << { foo: :bar } }
+
+  Thread.current.agent.read_loop(socket) do |data|
+    parser << data
+    reqs.each { |r| reply(socket, r) }
+    reqs.clear
+  end
+end
+
+def reply(socket)
+  data = "Hello world!\n"
+  headers = "Content-Type: text/plain\r\nContent-Length: #{data.bytesize}\r\n"
+  socket.write "HTTP/1.1 200 OK\r\n#{headers}\r\n#{data}"
+end
+
+server = TCPServer.open('0.0.0.0', 1234)
+puts "listening on port 1234"
+
+Thread.current.agent.accept_loop(server) do |client|
+  spin { handle_client(client) }
+end
+```
+
+The `#read_loop` and `#accept_loop` agent methods implement tight loops that
+provide a significant boost to performance (up to +30% better throughput.)
+
+Currently, Polyphony includes a single system agent based on
+[libev](http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod). In the future,
+Polyphony will include other platform-specific system agents, such as a Windows
+agent using
+[IOCP](https://docs.microsoft.com/en-us/windows/win32/fileio/i-o-completion-ports),
+or an [io_uring](https://unixism.net/loti/what_is_io_uring.html) agent,
+which might be a game-changer for writing highly-concurrent Ruby-based web apps.
+
+## Writing Web Apps with Polyphony
+
+Polyphony includes a full-featured web server implementation that supports
+HTTP/1, HTTP/2, and WebSockets, can perform SSL termination (with automatic ALPN
+protocol selection), and has preliminary support for Rack (the de-facto standard
+Ruby web app interface).
+
+The Polyphony HTTP server has a unique design that calls the application's
+request handler after all request headers have been received. This allows the
+application to better deal with slow client attacks, big file uploads, and also
+to minimize costly memory allocation and GC'ing.
+
+Benchmarks will be included here at a later time.
+
+## Integrating Polyphony with other Gems
+
+Polyphony aims to be a comprehensive concurrency solution for Ruby, and to
+enable developers to use a maximum of core and stdlib APIs transparently in a
+multi-fiber envrionment. Polyphony also provides adapters for common gems such
+as postgres and redis, allowing using those gems in a fiber-aware manner.
+
+For gems that do not yet have a fiber-aware adapter, Polyphony offers a general
+solution in the form of a thread pool. A thread pool lets you offload blocking
+method calls (that block the entire thread) onto worker threads, letting you
+continue with other work while waiting for the call to return. For example,
+here's how an `sqlite` adapter might work:
+
+```ruby
+class SQLite3::Database
+  THREAD_POOL = Polyphony::ThreadPool.new
+
+  alias_method :orig_execute, :execute
+  def execute(sql, *args)
+    THREAD_POOL.process { orig_execute(sql, *args) }
+  end
+end
+```
+
+Other cases might require converting a callback-based interface into a blocking
+fiber-aware one. Here's (a simplified version of) how Polyphony uses the
+callback-based `http_parser.rb` gem to parse incoming HTTP/1 requests:
+
+```ruby
+class HTTP1Adapter
+  ...
+
+  def on_headers_complete(headers)
+    @pending_requests << Request.new(headers, self)
+  end
+
+  def each(&block)
+    while (data = @connection.readpartial(8192))
+      # feed parser
+      @parser << data
+      while (request = @pending_requests.shift)
+        block.call(request)
+        return unless request.keep_alive?
+      end
+    end
+  end
+
+  ...
+end
+```
+
+In the code snippet above, the solution is quite simple. The fiber handling the
+connection loops waiting for data to be read from the socket. Once the data
+arrives, it is fed to the HTTP parser. The HTTP parser will call the
+`on_headers_complete` callback, which simply adds a request to the requests
+queue. The code then continues to handle any requests still in the queue.
+
+## Future Directions
+
+Polyphony is a young project, and will still need a lot of development effort to
+reach version 1.0. Here are some of the exciting directions we're working on.
+
+- Support for more core and stdlib APIs
+- More adapters for gems with C-extensions, such as `mysql`, `sqlite3` etc
+- Use `io_uring` agent as alternative to the libev agent 
+- More concurrency constructs for building highly concurrent applications