polyphony 0.99 → 0.99.1

data/docs/api-reference/fiber.md

@@ -1,425 +0,0 @@
----
-layout: page
-title: ::Fiber
-parent: API Reference
-permalink: /api-reference/fiber/
-# prev_title: Tutorial
-# next_title: How Fibers are Scheduled
----
-# ::Fiber
-
-[Ruby core Fiber documentation](https://ruby-doc.org/core-2.7.0/Fiber.html)
-
-Polyphony enhances the core `Fiber` class with APIs for scheduling, exception
-handling, message passing, and more. Normally, fibers should be created using
-`Object#spin` or `Fiber#spin`, but some fibers might be created implicitly when
-using lazy enumerators or third party gems. For fibers created implicitly,
-Polyphony provides `Fiber#setup_raw`, which enables scheduling and message
-passing for such fibers.
-
-While most work on fibers since their introduction into MRI Ruby has
-concentrated on `Fiber#resume` and `Fiber.yield` for transferring control
-between fibers, Polyphony uses `Fiber#transfer` exclusively, which allows
-fully symmetric transfer of control between fibers.
-
-## Class Methods
-
-### ::await(\*fibers) → [\*result]
-
-Awaits all given fibers, returning when all fibers have terminated. If one of
-the given fibers terminates with an uncaught exception, `::await` will terminate
-and await all fibers that are still running, then reraise the exception. All the
-given fibers are guaranteed to have terminated when `::await` returns. If no
-exception is raised, `::await` returns an array containing the results of all
-given fibers, in the same order.
-
-```ruby
-f1 = spin { sleep 1 }
-f2 = spin { sleep 2 }
-Fiber.await(f1, f2)
-```
-
-### ::select(\*fibers) → [\*result]
-
-Selects the first fiber to have terminated among the given fibers. If any of the
-given fibers terminates with an uncaught exception, `::select` will reraise the
-exception. If no exception is raised, `::select` returns an array containing the
-fiber and its result. All given fibers are guaranteed to have terminated when
-`::select` returns.
-
-```ruby
-# get the fastest reply of a bunch of URLs
-fibers = urls.map { |u| spin { [u, HTTParty.get(u)] } }
-fiber, (url, result) = Fiber.select(*fibers)
-```
-
-## Instance methods
-
-### #&lt;&lt;(object) → fiber<br>#send(object) → fiber
-
-Adds a message to the fiber's mailbox. The message can be any object. This
-method is complemented by `Fiber#receive`.
-
-```ruby
-f = spin do
-  loop do
-    receiver, x = receive
-    receiver << x * 10
-  end
-end
-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
-exception, `#await` will reraise the exception. Otherwise `#await` returns the
-result of the fiber.
-
-```ruby
-f = spin { 'foo' }
-f.await #=> 'foo'
-```
-
-### #await_all_children → fiber
-
-Waits for all the fiber's child fibers to terminate. This method is normally
-coupled with `Fiber#terminate_all_children`. See also
-`Fiber#shutdown_all_children`.
-
-```ruby
-jobs.each { |j| spin { process(j) } }
-sleep 1
-terminate_all_children
-await_all_children
-```
-
-### #caller → [*location]
-
-Return the execution stack of the fiber, including that of the fiber from which
-it was spun.
-
-```ruby
-spin {
-  spin {
-    spin {
-      pp Fiber.current.caller
-    }.await
-  }.await
-}.await
-
-#=> ["examples/core/xx-caller.rb:3:in `block (2 levels) in <main>'",
-#=>  "examples/core/xx-caller.rb:2:in `block in <main>'",
-#=>  "examples/core/xx-caller.rb:1:in `<main>'"]
-```
-
-### #cancel! → fiber
-
-Terminates the fiber by raising a `Polyphony::Cancel` exception. If uncaught,
-the exception will be propagated.
-
-```ruby
-f = spin { sleep 1 }
-f.cancel! #=> exception: Polyphony::Cancel
-```
-
-### #children → [\*fiber]
-
-Returns an array containing all of the fiber's child fibers. A child fiber's
-lifetime is limited to that of its immediate parent.
-
-```ruby
-f1 = spin { sleep 1 }
-f2 = spin { sleep 1 }
-f3 = spin { sleep 1 }
-Fiber.current.children #=> [f1, f2, f3]
-```
-
-### #interrupt(object = nil) → fiber<br>#stop(object = nil) → fiber
-
-Terminates the fiber by raising a `Polyphony::MoveOn` exception in its context.
-The given object will be set as the fiber's result. Note that a `MoveOn`
-exception is never propagated.
-
-```ruby
-f = spin { do_something_slow }
-f.interrupt('never mind')
-f.await #=> 'never mind'
-```
-
-### #location → string
-
-Returns the location of the fiber's associated block, or `(root)` for the main
-fiber.
-
-### #main? → true or false
-
-Returns true if the fiber is the main fiber for its thread.
-
-### #parent → fiber
-
-Returns the fiber's parent fiber. The main fiber's parent is nil.
-
-```ruby
-f = spin { sleep 1 }
-f.parent #=> Fiber.current
-```
-
-### #raise(\*args) → fiber
-
-Raises an error in the context of the fiber. The given exception can be a string
-(for raising `RuntimeError` exceptions with a given message), an exception
-class, or an exception instance. If no argument is given, a `RuntimeError` will
-be raised. Uncaught exceptions will be propagated.
-
-```ruby
-f = spin { sleep 1 }
-f.raise('foo') # raises a RuntimeError
-f.raise(MyException, 'my error message') # exception class with message
-f.raise(MyException.new('my error message')) # exception instance
-# or simply
-f.raise
-```
-
-### #receive → object
-
-Pops the first message from the fiber's mailbox. If no message is available,
-`#receive` will block until a message is pushed to the mailbox. The received
-message can be any kind of object. This method is complemented by
-`Fiber#<<`/`Fiber#send`.
-
-```ruby
-spin { Fiber.current.parent << 'hello from child' }
-message = receive #=> 'hello from child'
-```
-
-### #receive_all_pending → [*object]
-
-Returns all messages currently in the mailbox, emptying the mailbox. This method
-does not block if no the mailbox is already empty. This method may be used to
-process any pending messages upon fiber termination:
-
-```ruby
-worker = spin do
-  loop do
-    job = receive
-    handle_job(job)
-  end
-rescue Polyphony::Terminate => e
-  receive_all_pending.each { |job| handle_job(job) }
-end
-```
-
-### #restart(object = nil) → fiber<br>#reset(object = nil) → fiber
-
-Restarts the fiber, essentially rerunning the fiber's associated block,
-restoring it to its primary state. If the fiber is already terminated, a new
-fiber will be created and returned. If the fiber's block takes an argument, its
-value can be set by passing it to `#restart`.
-
-```ruby
-counter = 0
-f = spin { sleep 1; counter += 1 }
-f.await #=> 1
-f.restart
-f.await #=> 2
-```
-
-### #result → object
-
-Returns the result of the fiber. If the fiber has not yet terminated, `nil` is
-returned. If the fiber terminated with an uncaught exception, the exception is
-returned.
-
-```ruby
-f = spin { sleep 1; 'foo' }
-f.await
-f.result #=> 'foo'
-```
-
-### #running? → true or false
-
-Returns true if the fiber is not yet terminated.
-
-### #schedule(object = nil) → fiber
-
-Adds the fiber to its thread's run queue. The fiber will be eventually resumed
-with the given value, which can be any object. If an exception is given, it will
-be raised in the context of the fiber upon resuming. If the fiber is already on
-the run queue, the resume value will be updated.
-
-```ruby
-f = spin do
-  result = suspend
-  p result
-end
-
-sleep 0.1
-f.schedule 'foo'
-f.await
-#=> 'foo'
-```
-
-### #shutdown_all_children → fiber
-
-Terminates all of the fiber's child fibers and blocks until all are terminated.
-This method is can be used to replace calls to `#terminate_all_children`
-followed by `#await_all_children`.
-
-```ruby
-jobs.each { |j| spin { process(j) } }
-sleep 1
-shutdown_all_children
-```
-
-### #spin(tag = nil, { block }) → fiber
-
-Creates a new fiber with self as its parent. The returned fiber is put on the
-run queue of the parent fiber's associated thread. A tag of any object type can
-be associated with the fiber. Note that `Object#spin` is a shortcut for
-`Fiber.current.spin`.
-
-```ruby
-f = Fiber.current.spin { |x|'foo' }
-f.await #=> 'foo'
-```
-
-If the block takes an argument, its value can be controlled by explicitly
-calling `Fiber#schedule`. The result of the given block (the value of the last
-statement in the block) can be retrieved using `Fiber#result` or by otherwise
-using fiber control APIs such as `Fiber#await`.
-
-```ruby
-f = spin { |x| x * 10 }
-f.schedule(2)
-f.await #=> 20
-```
-
-### #state → symbol
-
-Returns the fiber's current state, which can be any of the following:
-
-- `:waiting` - the fiber is currently waiting for an operation to complete.
-- `:runnable` - the fiber is scheduled to be resumed (put on the run queue).
-- `:running` - the fiber is currently running.
-- `:dead` - the fiber has terminated.
-
-### #supervise(opts = {}) → fiber
-
-Supervises all child fibers, optionally restarting any fiber that terminates.
-
-The given `opts` argument controls the behaviour of the supervision. The
-following options are currently supported:
-
-- `:restart`: restart options
-  - `nil` - Child fibers are not restarted (default behaviour).
-  - `true` - Any child fiber that terminates is restarted.
-  - `:on_error` - Any child fiber that terminates with an uncaught exception is
-    restarted.
-- `:watcher`: a fiber watching supervision events.
-
-If a watcher fiber is specified, it will receive supervision events to its
-mailbox. The events are of the form `[<event_type>, <fiber>]`, for example
-`[:restart, child_fiber_1]`. Here's an example of using a watcher fiber:
-
-```ruby
-watcher = spin_loop do
-  kind, fiber = receive
-  case kind
-  when :restart
-    puts "fiber #{fiber.inspect} restarted"
-  end
-end
-...
-supervise(restart: true, watcher: watcher)
-```
-
-### #tag → object
-
-Returns the tag associated with the fiber, normally passed to `Fiber#spin`. The
-tag can be any kind of object. The default tag is `nil`.
-
-```ruby
-f = spin(:worker) { do_some_work }
-f.tag #=> :worker
-```
-
-### #tag=(object) → object
-
-Sets the tag associated with the fiber. The tag can be any kind of object.
-
-```ruby
-f = spin { do_some_work }
-f.tag = :worker
-```
-
-### #terminate → fiber
-
-Terminates the fiber by raising a `Polyphony::Terminate` exception. The
-exception is not propagated. Note that the fiber is not guaranteed to terminate
-before `#terminate` returns. The fiber will need to run first in order to raise
-the `Terminate` exception and terminate. This method is normally coupled with
-`Fiber#await`:
-
-```ruby
-f1 = spin { sleep 1 }
-f2 = spin { sleep 2 }
-
-f1.await
-
-f2.terminate
-f2.await
-```
-
-### #terminate_all_children → fiber
-
-Terminates all of the fiber's child fibers. Note that `#terminate_all_children`
-does not acutally wait for all child fibers to terminate. This method is
-normally coupled with `Fiber#await_all_children`. See also `Fiber#shutdown_all_children`.
-
-```ruby
-jobs.each { |j| spin { process(j) } }
-sleep 1
-terminate_all_children
-await_all_children
-```
-
-### #thread → thread
-
-Returns the thread to which the fiber belongs.
-
-```ruby
-f = spin(:worker) { do_some_work }
-f.thread #=> Thread.current
-```
-
-### #when_done({ block }) → fiber
-
-Installs a hook to be called when the fiber is terminated. The block will be
-called with the fiber's result. If the fiber terminates with an uncaught
-exception, the exception will be passed to the block.
-
-```ruby
-f = spin { 'foo' }
-f.when_done { |r| puts "got #{r} from fiber" }
-f.await #=> STDOUT: 'got foo from fiber'
-```

data/docs/api-reference/index.md

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

data/docs/api-reference/io.md

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

@@ -1,99 +0,0 @@
----
-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_all_pending → [*object]
-
-Shortcut for `Fiber.current.receive_all_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

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

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

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

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

@@ -1,28 +0,0 @@
----
-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
-spin { Polyphony::Process.watch('echo "Hello World"; sleep 1') }
-supervise(restart: :always)
-```