Fix documentation for Fiber#transfer [ci skip]

Fiber#transfer prevents calling Fiber#resume on the receiver of the
transfer method, not the fiber calling transfer.

Transfering back to a fiber does not allow later calling resume on
the fiber.  Once transfer has been called on a fiber, you can never
call resume on the fiber.

Calling resume on a transferred fiber is not a double resume error,
it is a different FiberError (cannot resume transferred Fiber).

For details on the differences between transferred fibers and
regular fibers, see Sasada-san's RubyKaigi 2017 presentation (in
short, Fiber#transfer is for coroutine, Fiber#resume is for
semi-coroutine).

1 files changed, 13 insertions, 6 deletions

diff --git a/cont.c b/cont.c
index 0db18bb813..832068f42e 100644
--- a/cont.c
+++ b/cont.c
@@ -2191,15 +2191,18 @@ rb_fiber_raise(int argc, VALUE *argv, VALUE fiber)
  *  a resume call. Arguments passed to transfer are treated like those
  *  passed to resume.
  *
- *  You cannot resume a fiber that transferred control to another one.
- *  This will cause a double resume error. You need to transfer control
- *  back to this fiber before it can yield and resume.
+ *  You cannot call +resume+ on a fiber that has been transfered to.
+ *  If you call +transfer+ on a fiber, and later call +resume+ on the
+ *  the fiber, a +FiberError+ will be raised. Once you call +transfer+ on
+ *  a fiber, the only way to resume processing the fiber is to
+ *  call +transfer+ on it again.
  *
  *  Example:
  *
  *    fiber1 = Fiber.new do
  *      puts "In Fiber 1"
  *      Fiber.yield
+ *      puts "In Fiber 1 again"
  *    end
  *
  *    fiber2 = Fiber.new do
@@ -2214,12 +2217,16 @@ rb_fiber_raise(int argc, VALUE *argv, VALUE fiber)
  *
  *    fiber2.resume
  *    fiber3.resume
+ *    fiber1.resume rescue (p $!)
+ *    fiber1.transfer
  *
  *  <em>produces</em>
  *
- *    In fiber 2
- *    In fiber 1
- *    In fiber 3
+ *    In Fiber 2
+ *    In Fiber 1
+ *    In Fiber 3
+ *    #<FiberError: cannot resume transferred Fiber>
+ *    In Fiber 1 again
  *
  */
 static VALUE