polyphony 0.99 → 0.99.1

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

@@ -1,59 +0,0 @@
----
-layout: page
-title: Polyphony::ResourcePool
-parent: API Reference
-permalink: /api-reference/polyphony-resourcepool/
----
-# Polyphony::ResourcePool
-
-`Polyphony::ResourcePool` implements a general purpose resource pool for
-limiting concurrent access to a resource or multiple copies thereof. A resource
-pool might be used for example to limit the number of concurrent database
-connections.
-
-## Class methods
-
-## Instance methods
-
-### #acquire({ block })
-
-Acquires a resource and passes it to the given block. The resource will be used
-exclusively by the given block, and then returned to the pool. This method
-blocks until the given block has completed running. If no resource is available,
-this method blocks until a resource has been released.
-
-```ruby
-db_connections = Polyphony::ResourcePool.new(limit: 5) { PG.connect(opts) }
-
-def query_records(sql)
-  db_connections.acquire do |db|
-    db.query(sql).to_a
-  end
-end
-```
-
-### #available → count
-
-Returns the number of resources currently available in the resource pool.
-
-### #initialize(limit: number, { block })
-
-Initializes a new resource pool with the given maximum number of concurrent
-resources. The given block is used to create the resource.
-
-```ruby
-require 'postgres'
-
-opts = { host: '/tmp', user: 'admin', dbname: 'mydb' }
-db_connections = Polyphony::ResourcePool.new(limit: 5) { PG.connect(opts) }
-```
-
-### #limit → count
-
-Returns the size limit of the resource pool.
-
-### #size → count
-
-Returns the total number of allocated resources in the resource pool. This
-includes both available and unavailable resources.
-

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

@@ -1,18 +0,0 @@
----
-layout: page
-title: Polyphony::Restart
-parent: API Reference
-permalink: /api-reference/polyphony-restart/
----
-# Polyphony::Restart
-
-`Polyphony::Restart` is an exception class used to restart a fiber. Applications
-will not normally raise a `Polyphony::Restart` exception, but would rather use
-`Fiber#restart`.
-
-```ruby
-f = spin { do_something_slow }
-...
-f.restart
-...
-```

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

@@ -1,18 +0,0 @@
----
-layout: page
-title: Polyphony::Terminate
-parent: API Reference
-permalink: /api-reference/polyphony-terminate/
----
-# Polyphony::Terminate
-
-`Polyphony::Terminate` is an exception class used to terminate a fiber without
-propagating the exception. It should never be rescued. A `Polyphony::Terminate`
-exception is normally raised using APIs such as `Fiber#terminate` or
-`Fiber#terminate_all_children`.
-
-```ruby
-f = spin { do_something_slow }
-...
-f.terminate
-```

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

@@ -1,67 +0,0 @@
----
-layout: page
-title: Polyphony::ThreadPool
-parent: API Reference
-permalink: /api-reference/polyphony-threadpool/
----
-# Polyphony::ThreadPool
-
-`Polyphony::ThreadPool` implements a general purpose thread pool, normally used
-for the execution of non-fiber aware operations, such as C-extension based
-third-party libraries or other system call blocking APIs. The Polyphony
-implementation of a thread pool allows limiting the number of threads used for
-performing a recurring operation across one or more fibers.
-
-A default thread pool is available for quick access to this feature.
-
-## Class methods
-
-### #process({ block }) → object
-
-Runs the given block on the default thread pool. The default pool will be
-created on the first call to `#process`. This method will block until the
-operation has completed. The return value is that of the given block. Any
-uncaught exception will be propagated to the callsite.
-
-```ruby
-result = Polyphony::ThreadPool.process { lengthy_op }
-```
-
-## Instance methods
-
-### #busy? → true or false
-
-Returns true if operations are currently being run on the thread pool.
-
-### cast({ block }) → pool
-
-Runs the given block on one of the threads in the pool in a fire-and-forget
-manner, without waiting for the operation to complete. Using `#cast` to run an
-operation means there's no way of knowing if the operation has completed or if
-any exception has been raised, other than inside the block.
-
-```ruby
-my_pool.cast { puts 'Hello world' }
-do_something_else
-```
-
-### #initialize(size = Etc.nprocessors)
-
-Initializes a new instance of `Polyphony::ThreadPool` with the given maximum
-number of threads. The default size is the number of available processors
-(number of CPU cores).
-
-```ruby
-my_pool = Polyphony::ThreadPool.new(3)
-```
-
-### #process({ block }) → object
-
-Runs the given block on one of the threads in the thread pool and blocks until
-the operation has completed. The return value is that of the given block. Any
-uncaught exception will be propagated to the callsite.
-
-```ruby
-pool = Polyphony::ThreadPool.new(3)
-result = pool.process { lengthy_op }
-```

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

@@ -1,77 +0,0 @@
----
-layout: page
-title: Polyphony::Throttler
-parent: API Reference
-permalink: /api-reference/polyphony-throttler/
----
-# Polyphony::Throttler
-
-`Polyphony::Throttler` implements general purpose operation throttling, or rate
-limiting. A `Polyphony::Throttler` instance may be used to limit the rate of an
-arbitrary operation in a single fiber, or across multiple fibers. For example,
-an HTTP server can limit the number of requests per second across for each
-client, or for all clients.
-
-A throttler is invoked using its `#call` method, e.g.:
-
-```ruby
-# throttle rate: one per second
-throttler = Polyphony::Throttler.new(1)
-
-10.times do |i|
-  spin_loop { throttler.call { p [i, Time.now] } }
-end
-```
-
-If many throttler instances are created over the application's lifetime, they
-should be stopped using the `#stop` method in order to prevent memory leaks.
-This is best done using an `ensure` block:
-
-```ruby
-def start_server
-  throttler = Polyphony::Throttler.new(1000)
-  MyServer.start do |req|
-    throttler.call { handle_request(req) }
-  end
-ensure
-  throttler.stop
-end
-```
-
-## Instance methods
-
-### #initialize(rate)<br>#initialize(interval: interval)<br>#initialize(rate: rate)
-
-Initializes the throttler with the given rate. The rate can be specified either
-as a number signifying the maximum rate per second, or as a keyword argument. If
-the rate is specified using the `interval:` keyword argument, the value given is
-the minimum interval between consecutive invocations.
-
-```ruby
-# These are all equivalent
-Polyphony::Throttler.new(10)
-Polyphony::Throttler.new(rate: 10)
-Polyphony::Throttler.new(interval: 0.1)
-```
-
-### #call({ block }) → object
-
-Invokes the throttler with the given block. This method will sleep for an
-interval of time required to throttle the execution of the given block. The
-return value is the return value of the given block.
-
-### #stop → throttler
-
-Stops the timer associated with the throttler. This method should be called when
-the throttler is no longer needed. This is best done from an `ensure` block.
-
-```ruby
-def start_server
-  throttler = Polyphony::Throttler.new(1000)
-  MyServer.start do |req|
-    throttler.call { handle_request(req) }
-  end
-ensure
-  throttler.stop
-end
-```

data/docs/api-reference/polyphony.md

@@ -1,36 +0,0 @@
----
-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

@@ -1,88 +0,0 @@
----
-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 system backend. 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/index.md

@@ -1,10 +0,0 @@
----
-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,34 +0,0 @@
----
-layout: page
-title: Installing Polyphony
-parent: Getting Started
-nav_order: 1
----
-# Installing Polyphony
-
-## 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) 2.6 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
-```