polyphony 0.33 → 0.34

data/docs/api-reference/io.md

@@ -0,0 +1,36 @@
+---
+layout: page
+title: ::IO
+parent: API Reference
+permalink: /api-reference/io/
+---
+# ::IO
+
+[Ruby core IO documentation](https://ruby-doc.org/core-2.7.0/IO.html)
+
+Polyphony reimplements a significant number of IO class and instance methods to
+be fiber-aware. Polyphony also adds methods for accessing the associated event
+watchers.
+
+## Class Methods
+
+## Instance methods
+
+### #read_watcher → io_watcher
+
+Returns the read watcher associated with the IO. The watcher is automatically
+created and cached. The watcher is an instance of `Gyro::IO`. Normally this
+method is not called directly from application code.
+
+```ruby
+def read_ten_chars(io)
+  io.read_watcher.await
+  io.read(10)
+end
+```
+
+### #write_watcher → io_watcher
+
+Returns the write watcher associated with the IO. The watcher is automatically
+created and cached. The watcher is an instance of `Gyro::IO`. Normally this
+method is not called directly from application code.

data/docs/api-reference/object.md

@@ -0,0 +1,99 @@
+---
+layout: page
+title: ::Object (Global API)
+parent: API Reference
+permalink: /api-reference/object/
+---
+# ::Object (Global API)
+
+The global Polyphony API is designed to feel almost like a part of the Ruby
+runtime. The global API contains multiple methods for creating and controlling
+fibers, as well as miscellaneous methods for dealing with timers and other
+events, with minimal boilerplate. The API is implemented as a module included in
+the `Object` class, allowing access from any receiver.
+
+### #after(interval, { block }) → fiber
+
+Run the given block after the given time interval (specified in seconds). This
+method spins up a separate fiber that will sleep for the given interval, then
+run the given block.
+
+```ruby
+f = spin { do_some_big_work }
+after(1) { f.stop }
+f.await
+```
+
+### #cancel_after(interval, { block }) → object
+
+Run the given block, cancelling it after the given time interval by raising a
+`Polyphony::Cancel` exception. If uncaught, the exception will be propagated.
+
+```ruby
+spin do
+  cancel_after(3) { do_some_work }
+rescue Polyphony::Cancel
+  puts "work was cancelled"
+end
+```
+
+### #every(interval, { block }) → object
+
+Runs the given block repeatedly, at the given time interval. This method will
+block until an exception is raised.
+
+```ruby
+every(3) do
+  puts "I'm still alive"
+end
+```
+
+### #move_on_after(interval, with_value: nil, { block }) → object
+
+Run the given block, interrupting it after the given time interval by raising a
+`Polyphony::MoveOn` exception. The `with_value` keyword argument can be used to
+set the value returned from the block if the timeout has elapsed.
+
+```ruby
+result = move_on_after(3, with_value: 'bar') { sleep 5; 'foo' }
+result #=> 'bar'
+```
+
+### #receive → object
+
+Shortcut for `Fiber.current.receive`
+
+### #receive_pending → [*object]
+
+Shortcut for `Fiber.current.receive_pending`
+
+### #sleep(duration = nil) → fiber
+
+Sleeps for the given duration.
+
+### #spin(tag = nil, { block}) → fiber
+
+Shortcut for `Fiber.current.spin`
+
+### #spin_loop(tag = nil, rate: nil, &block) → fiber
+
+Spins up a new fiber that runs the given block in a loop. If `rate` is given,
+the loop is throttled to run `rate` times per second.
+
+```ruby
+# print twice a second
+f = spin_loop(rate: 2) { puts 'hello world' }
+sleep 2
+f.stop
+```
+
+### #throttled_loop(rate, count: nil, &block) → object
+
+Runs the given block in a loop at the given rate (times per second). If `count`
+is given, the loop will be run for the specified number of times and then
+returns. Otherwise, the loop is infinite (unless an exception is raised).
+
+```ruby
+# twice a second
+throttled_loop(2) { puts 'hello world' }
+```

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

@@ -0,0 +1,33 @@
+---
+layout: page
+title: Polyphony::BaseException
+parent: API Reference
+permalink: /api-reference/polyphony-baseexception/
+---
+# Polyphony::BaseException
+
+The `Polyphony::BaseException` is a common base class for exceptions used to
+control fiber execution. Instances of descendant classes are meant to be created
+explicitly using `new`, e.g. `Polyphony::MoveOn.new`, rather than using `raise
+Polyphony::MoveOn`. Normally an application will not use those classes directly
+but would rather use APIs such as `Fiber#interrupt`.
+
+## Derived classes
+
+- [`Polyphony::Cancel`](../polyphony-cancel/)
+- [`Polyphony::MoveOn`](../polyphony-moveon/)
+- [`Polyphony::Restart`](../polyphony-restart/)
+- [`Polyphony::Terminate`](../polyphony-terminate/)
+
+## Instance methods
+
+### #initialize(value = nil)
+
+Initializes the exception with an optional result value. The value will be used
+as the result of the block being interrupted or the fiber being terminated.
+
+```ruby
+f = spin { 'foo' }
+f.raise(Polyphony::Terminate.new('bar'))
+f.await #=> 'bar'
+```

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

@@ -0,0 +1,26 @@
+---
+layout: page
+title: Polyphony::Cancel
+parent: API Reference
+permalink: /api-reference/polyphony-cancel/
+---
+# Polyphony::Cancel
+
+`Polyphony::Cancel` is an exception class used to interrupt a blocking operation
+with an exception that must be rescued. This exception is will propagate if not
+rescued. A `Polyphony::Cancel` exception is normally raised using APIs such as
+`Fiber#cancel!` or `Object#cancel_after`.
+
+```ruby
+require 'httparty'
+require 'time'
+
+def current_server_time
+  cancel_after(10) do
+    response_body = HTTParty.get(TIME_URL).body
+    Time.parse(response_body)
+  end
+rescue Polyphony::Cancel
+  Time.now
+end
+```

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

@@ -0,0 +1,24 @@
+---
+layout: page
+title: Polyphony::MoveOn
+parent: API Reference
+permalink: /api-reference/polyphony-moveon/
+---
+# Polyphony::MoveOn
+
+`Polyphony::MoveOn` is an exception class used to interrupt a blocking operation
+without propagating the excception. A `Polyphony::MoveOn` exception is normally
+raised using APIs such as `Fiber#interrupt` or `Object#move_on_after`. This
+exception allows you to set the result of the operation being interrupted.
+
+```ruby
+
+def do_something_slow
+  sleep 10
+  'foo'
+end
+
+f = spin { do_something_slow }
+f.interrupt('bar')
+f.await #=> 'bar'
+```

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

@@ -0,0 +1,20 @@
+---
+layout: page
+title: Polyphony::Net
+parent: API Reference
+permalink: /api-reference/polyphony-net/
+---
+# Polyphony::Net
+
+The `Polyphony::Net` provides convenience methods for working with sockets. The
+module unifies secure and non-secure socket APIs.
+
+## Class Methods
+
+### #tcp_connect(host, port, opts = {}) → socket
+
+Connects to a TCP server.
+
+### #tcp_listen(host = nil, port = nil, opts = {}) → socket
+
+Opens a server socket for listening to incoming connections.

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

@@ -0,0 +1,28 @@
+---
+layout: page
+title: Polyphony::Process
+parent: API Reference
+permalink: /api-reference/polyphony-process/
+---
+# Polyphony::Process
+
+The `Polyphony::Process` module is used to watch child processes.
+
+## Class Methods
+
+### #watch(cmd = nil, { block })
+
+Starts a child process, blocking until the child process terminates. If `#watch`
+is interrupted before the child process terminates, the child process is sent a
+`TERM` signal, and awaited. After 5 seconds, if the child has still not
+terminated, it will be sent a `KILL` signal and awaited. This method is normally
+used in conjunction with `#supervise` in order to supervise child processes.
+
+If `cmd` is given, the child process is started using `Kernel#spawn` running a
+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')
+supervise(restart: :always)
+```

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

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

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

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

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

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