polyphony 0.33 → 0.34

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fde67b1d9cd285b35d265f12648e48e43073fd3b8e27713f981883ab4b080c12
-  data.tar.gz: a567e1e171b4f61f5fb344b3345b4a9e6f32ec7a810258c99007a17614e5cd5e
+  metadata.gz: ea4d90a517ed25294e677a9d3298ee2f4f79ad269e222c2a6e3a786fed605b50
+  data.tar.gz: 19581d1dea73db08a6b9b0816fd4500c7ca84b2692150585133b7e3f99ee0522
 SHA512:
-  metadata.gz: 3e99f3e9f9acce3b2deadf516dc254ae6a305a64b9bd05a04e6207834f1189c61ae44481e485381fbb08eae3ee2f1da0843441ee518f64448f76c3529e1281a7
-  data.tar.gz: b6ebe93d0eb812010aafdcc2f9298e1237c14a6b0da6b3da30abe917217fb04fac24671e02792c0c3f790912660ed0b64355849e81e07bb35029dc647f413589
+  metadata.gz: 36291ddf1dedbed0fbdcb347811e657bad19661981cacff2fa9736246e883fa2f56fa4362f266721177559e295adefe3f92c1797e4773dfc03b45857d2ebb3fb
+  data.tar.gz: 8d9a5f0d368167a300e9926c9ad2d57221a423b60dc18d8a395c114feb18e3fa96546ac7709bf8acbabca500ec56d373bcd8f38479183c00077f0ccf513fb039

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.34 2020-03-25
+
+* Implement process supervisor (`Polyphony::ProcessSupervisor`)
+* Improve fiber supervision
+* Fix forking behaviour
+* Use correct backtrace for fiber control exceptions
+* Allow calling `move_on_after` and `cancel_after` without block
+
 ## 0.33 2020-03-08
 
 * Implement `Fiber#supervise` (WIP)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    polyphony (0.33)
+    polyphony (0.34)
       modulation (~> 1.0)
 
 GEM

data/TODO.md

@@ -1,12 +1,78 @@
+- Would it be possible to spin up a fiber on another thread?
+  
+  The use case is being able to supervise fibers that run on separate threads.
+  This might be useful for distributing jobs (such as handling HTTP connections)
+  over multiple threads.
+
+  For this we need:
+
+  - A way to communicate to a thread that it needs to spin up a fiber, the
+    simplest solution is to start a fiber accepting spin requests for each
+    thread (in `Thread#initialize`).
+  - An API:
+
+    ```ruby
+    spin(on_thread: thread) { do_something_important }
+    ```
+
+  An alternative is to turn the main fiber of spawned threads into a child of
+  the spawning fiber. But since a lot of people might start threads without any
+  regard to fibers, it might be better to implement this in a new API. An
+  example of the top of my head for threads that shouldn't be children of the
+  spawning fiber is our own test helper, which kills all child fibers after each
+  test. MiniTest has some threads it spawns for running tests in parallel, and
+  we don't want to stop them after each test!
+
+  So, a good solution would be:
+
+  ```ruby
+  t = Thread.new { do_stuff }
+  t.parent_fiber = Fiber.current
+  # or otherwise:
+  Fiber.current.add_child_fiber(t.main_fiber)
+  ```
+
+## 0.35 Some more API work, more docs
+
 - Debugging
   - Eat your own dogfood: need a good tool to check what's going on when some
     test fails
   - Needs to work with Pry (can write perhaps an extension for pry)
   - First impl in Ruby using `TracePoint` API
   - Mode of operation:
-    - Debugger runs on separate thread
-    - The `TracePoint` handler passes control to the debugger thread, and waits
-      for reply (probably using Fiber messages)
+    - Two parts: tracer and controller
+      - The tracer keeps state
+      - The controller interacts with the user and tells the tracer what to do
+      - Tracer and controller interact using fiber message passing
+      - The controller lives on a separate thread
+      - The tracer invokes the controller at the appropriate point in time
+        according to the state. For example, when doing a `next` command, the
+        tracer will wait for a `:line` event to occur within the same stack
+        frame, or for the frame to be popped on a `:return` event, and only then
+        will it invoke the controller.
+      - While invoking the controller and waiting for its reply, the tracer
+        optionally performs a fiber lock in order to prevent other fibers from
+        advancing (the fiber lock is the default mode).
+    - The tracer's state is completely inspectable
+
+      ```ruby
+      PolyTrace.state
+      PolyTrace.current_fiber
+      PolyTrace.call_stack
+      ```
+
+    - Modes can be changed using an API, e.g.
+
+      ```ruby
+      PolyTrace.fiber_lock = false
+      ```
+
+    - Fibers can be interrogated using an API, or perhaps using some kind of
+      Pry command...
+
+    - Normal mode of operation is fiber modal, that is, trace only the currently
+      selected fiber. The currently selected fiber may be changed upon breakpoint
+
   - Step over should return on the next line *for the same fiber*
   - The event loop (all event loops?) should be suspended so timers are adjusted
     accordingly, so on control passing to debugger we:
@@ -42,77 +108,36 @@
           - from an expression: `Fiber.current.children`
           - maybe just `select f1` (where f1 is a local var)
 
-- Fiber supervision
-  - can a fiber be restarted?
-    - Theoretically, we can take the same block and rerun it under a different
-      fiber
-  - (restart) strategy (taken from Erlang):
-    - `:one_for_one`: if a child terminates, it is restarted
-    - `:one_for_all`: if a child terminates, all other children are terminated,
-      then all are restarted
-    - `:simple_on_for_one`: same as `:one_for_one` except all children are
-      identical (run the same block)
-  - I'm not so sure this kind of supervision is what we need. We can envision
-    an API such as the following:
+- Allow locking the scheduler on to one fiber
+  - Add instance var `@fiber_lock`
+  - API is `Thread#fiber_lock` which sets the fiber_lock instance varwhile
+    running the block:
 
     ```ruby
-    spin {
-      spin { do_a }
-      spin { do_b }
-      supervise(restart: :never, shutdown: :terminate)
-    }
-    ```
-
-  - The default for `#supervise` should be:
-    - wait for all fibers to terminate
-    - propagate exceptions
-    - no restart
-  
-  - `#supervise` could also take a block:
-
-    ```ruby
-    supervise do |fiber, error|
-      # this block is called when a fiber is terminated, letting the developer
-      # decide how to react.
-
-      # We can propagate the error
-      raise error if error
-
-      # We can restart the fiber (the respun fiber will have the same parent,
-      # the same caller location, the same tag)
-      fiber.respin # TODO: implement Fiber#respin
+    def debug_prompt
+      Thread.current.fiber_lock do
+        ...
+      end
     end
     ```
+  - When `@fiber_lock` is set, it is considered as the only one in the run
+    queue:
 
-  - Another option is to pass supervision parameters to `#spin`:
-
-    ```ruby
-    spin(supervise: true) do
+    ```c
+    VALUE fiber_lock = rb_ivar_get(self, ID_ivar_fiber_lock);
+    int locked = fiber_lock != Qnil;
 
-    end
+    while (1) {
+      next_fiber = locked ? fiber_lock : rb_ary_shift(queue);
+      ...
+    }
     ```
 
-  - Or maybe:
 
-    ```ruby
-    spin_supervisor do
-      
-    end
-    ```
 
-## 0.32 Some more API work, more docs
 
-- Allow calling `cancel_after` and `move_on_after` without blocks, just return
-  the cancelling fiber:
 
-  ```ruby
-  def foo
-    f = cancel_after(10)
-    do_something_slow
-  ensure
-    f.stop
-  end
-  ```
+
 
 - Docs
   - landing page:
@@ -127,7 +152,7 @@
 - Check why first call to `#sleep` returns too early in tests. Check the
   sleep behaviour in a spawned thread.
 
-## 0.33 Sinatra / Sidekiq
+## 0.36 Sinatra / Sidekiq
 
 - sintra app with database access (postgresql)
 
@@ -137,13 +162,13 @@
   - test performance
   - proceed from there
 
-## 0.34 Testing && Docs
+## 0.37 Testing && Docs
 
 - Pull out redis/postgres code, put into new `polyphony-xxx` gems
 
-## 0.35 Integration
+## 0.38 Integration
 
-## 0.36 Real IO#gets and IO#read
+## 0.39 Real IO#gets and IO#read
 
 - More tests
 - Implement some basic stuff missing:
@@ -153,11 +178,11 @@
   - `IO.foreach`
   - `Process.waitpid`
 
-## 0.37 Rails
+## 0.40 Rails
 
 - Rails?
 
-## 0.37 DNS
+## 0.41 DNS
 
 ### DNS client
 

data/bin/polyphony-debug

@@ -0,0 +1,87 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'polyphony'
+
+Gyro.trace(true)
+
+FILE_CACHE = {}
+@ready = nil
+@last_location = nil
+@mode = :step
+@current_fiber = nil
+@stacks = Hash.new([])
+
+def debug_prompt
+  loop do
+    STDOUT << '(debug) '
+    case (cmd = STDIN.gets.chomp)
+    when '.q', '.quit'
+      exit!
+    when 's', 'step'
+      @mode = :step
+      return
+    else
+      begin
+        result = binding.eval(cmd)
+        p result
+      rescue Exception => e
+        p e
+        puts e.backtrace.join("\n")
+      end
+    end
+  end
+end
+
+def get_snippet(path, lineno)
+  lines = FILE_CACHE[path] ||= IO.read(path).lines
+  start_idx = lineno - 5
+  stop_idx = lineno + 3
+  stop_idx = lines.size - 1 if stop_idx >= lines.size
+  start_idx = 0 if start_idx < 0
+  (start_idx..stop_idx).map { |idx| [idx + 1, lines[idx]]}
+end
+
+def print_snippet(snippet, cur_line)
+  snippet.each do |(lineno, line)|
+    is_cur = lineno == cur_line
+    formatted = format("%s%03d %s", is_cur ? '*=> ' : '    ', lineno, line)
+    puts formatted
+  end
+end
+
+tp = Polyphony::Trace.new(*Polyphony::Trace::STOCK_EVENTS, :fiber_all) do |r|
+  unless @ready
+    @ready = true if r[:event] == :return
+    @current_fiber = r[:fiber]
+    next
+  end
+
+  case r[:event]
+  when :call, :b_call, :c_call
+    @stacks[r[:fiber]] << r
+  when :return, :b_return, :c_return
+    @stacks[r[:fiber]].pop
+  when :line
+    case @mode
+    when :step
+      if r[:location] != @last_location && r[:fiber] == @current_fiber
+        @last_location = r[:location]
+        puts "in #{r[:location]}"
+        puts
+        snippet = get_snippet(r[:path], r[:lineno])
+        print_snippet(snippet, r[:lineno])
+        puts
+        debug_prompt
+      end
+    end
+  end
+rescue Exception => e
+  p e
+  exit!
+end
+tp.enable
+
+require File.expand_path(ARGV[0])

data/docs/_includes/nav.html

@@ -17,7 +17,11 @@
               <a href="{{ node.url | absolute_url }}" class="navigation-list-link{% if page.url == node.url %} active{% endif %}">{{ node.title }}</a>
             {%- endif -%}
             {%- if node.has_children -%}
-              {%- assign children_list = site.html_pages | where: "parent", node.title | sort:"nav_order" -%}
+              {%- if node.alphabetical_order -%}
+                {%- assign children_list = site.html_pages | where: "parent", node.title | sort:"title" -%}
+              {%- else -%}
+                {%- assign children_list = site.html_pages | where: "parent", node.title | sort:"nav_order" -%}
+              {%- endif -%}
               <ul class="navigation-list-child-list ">
                 {%- for child in children_list -%}
                   <li class="navigation-list-item {% if page.url == child.url or page.parent == child.title %} active{% endif %}">

data/docs/_sass/overrides.scss

@@ -30,12 +30,15 @@ span.section-title {
 }
 
 a.navigation-list-link {
+  margin-left: 4px;
+  padding-left: 4px;
   color: $nav-child-link-color;
   font-weight: 600;
 }
 
 a.navigation-list-link.active {
-  border-right: 4px #6ae solid;
+  margin-left: 0;
+  border-left: 4px #6ae solid;
 }
 
 a.navigation-list-link:hover {

data/docs/api-reference.md

@@ -0,0 +1,11 @@
+---
+layout: page
+title: API Reference
+description: Lorem ipsum
+has_children: true
+alphabetical_order: true
+section: true
+has_toc: false
+nav_order: 5
+section_link: /api-reference/fiber
+---

data/docs/api-reference/exception.md

@@ -0,0 +1,27 @@
+---
+layout: page
+title: ::Exception
+parent: API Reference
+permalink: /api-reference/exception/
+---
+# ::Exception
+
+[Ruby core Exception documentation](https://ruby-doc.org/core-2.7.0/Exception.html)
+
+The core `Exception` class is enhanced to provide a better backtrace that takes
+into account the fiber hierarchy. In addition, a `source_fiber` attribute allows
+tracking the fiber from which an uncaught exception was propagated.
+
+## Class Methods
+
+## Instance methods
+
+### #source_fiber → fiber
+
+Returns the fiber in which the exception occurred. Polyphony sets this attribute
+only for uncaught exceptions. Currently this attribute is only used in a
+meaningful way for supervising fibers.
+
+### #source_fiber=(fiber) → fiber
+
+Sets the fiber in which the exception occurred.

data/docs/api-reference/fiber.md

@@ -0,0 +1,407 @@
+---
+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
+```
+
+### #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_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_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'
+```