Ruby  3.4.0dev (2024-11-22 revision 37a72b0150ec36b4ea27175039afc28c62207b0c)
Functions
cont.h File Reference

(37a72b0150ec36b4ea27175039afc28c62207b0c)

Public APIs related to rb_cFiber. More...

#include "ruby/internal/dllexport.h"
#include "ruby/internal/value.h"
#include "ruby/internal/iterator.h"
Include dependency graph for cont.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions

VALUE rb_fiber_new (rb_block_call_func_t func, VALUE callback_obj)
 Creates a Fiber instance from a C-backended block. More...
 
VALUE rb_fiber_new_storage (rb_block_call_func_t func, VALUE callback_obj, VALUE storage)
 Creates a Fiber instance from a C-backended block with the specified storage. More...
 
VALUE rb_fiber_current (void)
 Queries the fiber which is calling this function. More...
 
VALUE rb_fiber_alive_p (VALUE fiber)
 Queries the liveness of the passed fiber. More...
 
VALUE rb_obj_is_fiber (VALUE obj)
 Queries if an object is a fiber. More...
 
VALUE rb_fiber_resume (VALUE fiber, int argc, const VALUE *argv)
 Resumes the execution of the passed fiber, either from the point at which the last rb_fiber_yield() was called if any, or at the beginning of the fiber body if it is the first call to this function. More...
 
VALUE rb_fiber_resume_kw (VALUE fiber, int argc, const VALUE *argv, int kw_splat)
 Identical to rb_fiber_resume(), except you can specify how to handle the last element of the given array. More...
 
VALUE rb_fiber_yield (int argc, const VALUE *argv)
 Yields the control back to the point where the current fiber was resumed. More...
 
VALUE rb_fiber_yield_kw (int argc, const VALUE *argv, int kw_splat)
 Identical to rb_fiber_yield(), except you can specify how to handle the last element of the given array. More...
 
VALUE rb_fiber_transfer (VALUE fiber, int argc, const VALUE *argv)
 Transfers control to another fiber, resuming it from where it last stopped or starting it if it was not resumed before. More...
 
VALUE rb_fiber_transfer_kw (VALUE fiber, int argc, const VALUE *argv, int kw_splat)
 Identical to rb_fiber_transfer(), except you can specify how to handle the last element of the given array. More...
 
VALUE rb_fiber_raise (VALUE fiber, int argc, const VALUE *argv)
 Identical to rb_fiber_resume() but instead of resuming normal execution of the passed fiber, it raises the given exception in it. More...
 

Detailed Description

Public APIs related to rb_cFiber.

Author
Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org
Warning
Symbols prefixed with either RBIMPL or rbimpl are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will.
Note
To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance __VA_ARGS__ is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98.

Definition in file cont.h.

Function Documentation

◆ rb_fiber_alive_p()

VALUE rb_fiber_alive_p ( VALUE  fiber)

Queries the liveness of the passed fiber.

"Alive" in this context means that the fiber can still be resumed. Once it reaches is its end of execution, this function returns RUBY_Qfalse.

Parameters
[in]fiberA target fiber.
Return values
RUBY_QtrueIt is.
RUBY_QfalseIt isn't.

Definition at line 2907 of file cont.c.

◆ rb_fiber_current()

VALUE rb_fiber_current ( void  )

Queries the fiber which is calling this function.

Any ruby execution context has its fiber, either explicitly or implicitly.

Returns
The current fiber.

Definition at line 2555 of file cont.c.

◆ rb_fiber_new()

VALUE rb_fiber_new ( rb_block_call_func_t  func,
VALUE  callback_obj 
)

Creates a Fiber instance from a C-backended block.

Parameters
[in]funcA function, to become the fiber's body.
[in]callback_objPassed as-is to func.
Returns
An allocated new instance of rb_cFiber, which is ready to be "resume"d.

Definition at line 2297 of file cont.c.

Referenced by ruby::backward::cxxanyargs::rb_fiber_new().

◆ rb_fiber_new_storage()

VALUE rb_fiber_new_storage ( rb_block_call_func_t  func,
VALUE  callback_obj,
VALUE  storage 
)

Creates a Fiber instance from a C-backended block with the specified storage.

If the given storage is Qundef or Qtrue, this function is equivalent to rb_fiber_new() which inherits storage from the current fiber.

Specifying Qtrue is experimental and may be changed in the future.

If the given storage is Qnil, this function will lazy initialize the internal storage which starts of empty (without any inheritance).

Otherwise, the given storage is used as the internal storage.

Parameters
[in]funcA function, to become the fiber's body.
[in]callback_objPassed as-is to func.
[in]storageThe way to set up the storage for the fiber.
Returns
An allocated new instance of rb_cFiber, which is ready to be "resume"d.

Definition at line 2291 of file cont.c.

Referenced by rb_fiber_new().

◆ rb_fiber_raise()

VALUE rb_fiber_raise ( VALUE  fiber,
int  argc,
const VALUE argv 
)

Identical to rb_fiber_resume() but instead of resuming normal execution of the passed fiber, it raises the given exception in it.

From inside of the fiber this would be seen as if rb_fiber_yield() raised.

This function does return in case the passed fiber gracefully handled the passed exception. But if it does not, the raised exception propagates out of the passed fiber; this function then does not return.

Parameters are passed to rb_make_exception() to create an exception object. See its document for what are allowed here.

It is a failure to call this function against a fiber which is resuming, have never run yet, or has already finished running.

Parameters
[out]fiberWhere exception is raised.
[in]argcPassed as-is to rb_make_exception().
[in]argvPassed as-is to rb_make_exception().
Exceptions
rb_eFiberErrorfiber is terminated etc.
Returns
(See rb_fiber_resume() for details)

Definition at line 3152 of file cont.c.

◆ rb_fiber_resume()

VALUE rb_fiber_resume ( VALUE  fiber,
int  argc,
const VALUE argv 
)

Resumes the execution of the passed fiber, either from the point at which the last rb_fiber_yield() was called if any, or at the beginning of the fiber body if it is the first call to this function.

Other arguments are passed into the fiber's body, either as return values of rb_fiber_yield() in case it switches to there, or as the block parameter of the fiber body if it switches to the beginning of the fiber.

The return value of this function is either the value passed to previous rb_fiber_yield() call, or the ultimate evaluated value of the entire fiber body if the execution reaches the end of it.

When an exception happens inside of a fiber it propagates to this function.

f = Fiber.new do |i|
puts "<x> =>> #{i}"
puts "<y> <-- #{i + 1}"
j = Fiber.yield(i + 1)
puts "<z> =>> #{j}"
puts "<w> <-- #{j + 1}"
next j + 1
end
puts "[a] <-- 1"
p = f.resume(1)
puts "[b] =>> #{p}"
puts "[c] <-- #{p + 1}"
q = f.resume(p + 1)
puts "[d] =>> #{q}"

Above program executes in [a] <x> <y> [b] [c] <z> <w> [d].

Parameters
[out]fiberThe fiber to resume.
[in]argcNumber of objects of argv.
[in]argvPassed (somehow) to fiber.
Exceptions
rb_eFiberErrorfib is terminated etc.
rb_eExceptionAny exceptions happen in fiber.
Returns
(See above)
Note
This function does return.

Definition at line 2873 of file cont.c.

◆ rb_fiber_resume_kw()

VALUE rb_fiber_resume_kw ( VALUE  fiber,
int  argc,
const VALUE argv,
int  kw_splat 
)

Identical to rb_fiber_resume(), except you can specify how to handle the last element of the given array.

Parameters
[out]fiberThe fiber to resume.
[in]argcNumber of objects of argv.
[in]argvPassed (somehow) to fiber.
[in]kw_splatHandling of keyword parameters:
  • RB_NO_KEYWORDS argv's last is not a keyword argument.
  • RB_PASS_KEYWORDS argv's last is a keyword argument.
  • RB_PASS_CALLED_KEYWORDS it depends if there is a passed block.
Exceptions
rb_eFiberErrorfiber is terminated etc.
rb_eExceptionAny exceptions happen in fiber.
Returns
Either what was yielded or the last value of the fiber body.

Definition at line 2867 of file cont.c.

◆ rb_fiber_transfer()

VALUE rb_fiber_transfer ( VALUE  fiber,
int  argc,
const VALUE argv 
)

Transfers control to another fiber, resuming it from where it last stopped or starting it if it was not resumed before.

The calling fiber will be suspended much like in a call to rb_fiber_yield().

The fiber which receives the transfer call treats it much like a resume call. Arguments passed to transfer are treated like those passed to resume.

The two style of control passing to and from fiber (one is rb_fiber_resume() and rb_fiber_yield(), another is rb_fiber_transfer() to and from fiber) can't be freely mixed.

  • If the Fiber's lifecycle had started with transfer, it will never be able to yield or be resumed control passing, only finish or transfer back. (It still can resume other fibers that are allowed to be resumed.)
  • If the Fiber's lifecycle had started with resume, it can yield or transfer to another Fiber, but can receive control back only the way compatible with the way it was given away: if it had transferred, it only can be transferred back, and if it had yielded, it only can be resumed back. After that, it again can transfer or yield.

If those rules are broken, rb_eFiberError is raised.

For an individual Fiber design, yield/resume is easier to use (the Fiber just gives away control, it doesn't need to think about who the control is given to), while transfer is more flexible for complex cases, allowing to build arbitrary graphs of Fibers dependent on each other.

Parameters
[out]fiberExplicit control destination.
[in]argcNumber of objects of argv.
[in]argvPassed to rb_fiber_resume().
Exceptions
rb_eFiberError(See above)
rb_eExceptionWhat was raised using Fiber#raise.
Returns
(See rb_fiber_resume() for details)

Definition at line 2700 of file cont.c.

◆ rb_fiber_transfer_kw()

VALUE rb_fiber_transfer_kw ( VALUE  fiber,
int  argc,
const VALUE argv,
int  kw_splat 
)

Identical to rb_fiber_transfer(), except you can specify how to handle the last element of the given array.

Parameters
[out]fiberExplicit control destination.
[in]argcNumber of objects of argv.
[in]argvPassed to rb_fiber_resume().
[in]kw_splatHandling of keyword parameters:
  • RB_NO_KEYWORDS argv's last is not a keyword argument.
  • RB_PASS_KEYWORDS argv's last is a keyword argument.
  • RB_PASS_CALLED_KEYWORDS it depends if there is a passed block.
Exceptions
rb_eFiberError(See above)
rb_eExceptionWhat was raised using Fiber#raise.
Returns
(See rb_fiber_resume() for details)

Definition at line 3113 of file cont.c.

◆ rb_fiber_yield()

VALUE rb_fiber_yield ( int  argc,
const VALUE argv 
)

Yields the control back to the point where the current fiber was resumed.

The passed objects would be the return value of rb_fiber_resume(). This fiber then suspends its execution until next time it is resumed.

This function can also raise arbitrary exceptions injected from outside of the fiber using rb_fiber_raise().

exc = Class.new Exception
f = Fiber.new do
Fiber.yield
rescue exc => e
puts e.message
end
f.resume
f.raise exc, "Hi!"
Parameters
[in]argcNumber of objects of argv.
[in]argvPassed to rb_fiber_resume().
Exceptions
rb_eException(See above)
Returns
(See rb_fiber_resume() for details)

Definition at line 2885 of file cont.c.

◆ rb_fiber_yield_kw()

VALUE rb_fiber_yield_kw ( int  argc,
const VALUE argv,
int  kw_splat 
)

Identical to rb_fiber_yield(), except you can specify how to handle the last element of the given array.

Parameters
[in]argcNumber of objects of argv.
[in]argvPassed to rb_fiber_resume().
[in]kw_splatHandling of keyword parameters:
  • RB_NO_KEYWORDS argv's last is not a keyword argument.
  • RB_PASS_KEYWORDS argv's last is a keyword argument.
  • RB_PASS_CALLED_KEYWORDS it depends if there is a passed block.
Exceptions
rb_eExceptionWhat was raised using Fiber#raise.
Returns
(See rb_fiber_resume() for details)

Definition at line 2879 of file cont.c.

◆ rb_obj_is_fiber()

VALUE rb_obj_is_fiber ( VALUE  obj)

Queries if an object is a fiber.

Parameters
[in]objArbitrary ruby object.
Return values
RUBY_QtrueIt is.
RUBY_QfalseIt isn't.

Definition at line 1180 of file cont.c.

Referenced by rb_fiber_scheduler_unblock().