(892c46283a5ea4179500d951c9d4866c0051f27b)

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:

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

Copyright: This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

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] fiber A target fiber.

Return values

RUBY_Qtrue	It is.
RUBY_Qfalse	It isn't.

Definition at line 2908 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 2556 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]	func	A function, to become the fiber's body.
[in]	callback_obj	Passed as-is to `func`.

Returns: An allocated new instance of rb_cFiber, which is ready to be "resume"d.

Definition at line 2298 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]	func	A function, to become the fiber's body.
[in]	callback_obj	Passed as-is to `func`.
[in]	storage	The 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 2292 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]	fiber	Where exception is raised.
[in]	argc	Passed as-is to rb_make_exception().
[in]	argv	Passed as-is to rb_make_exception().

Exceptions

rb_eFiberError fiber is terminated etc.

Returns: (See rb_fiber_resume() for details)

Definition at line 3153 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]	fiber	The fiber to resume.
[in]	argc	Number of objects of `argv`.
[in]	argv	Passed (somehow) to `fiber`.

Exceptions

rb_eFiberError	`fib` is terminated etc.
rb_eException	Any exceptions happen in `fiber`.

Returns: (See above)

Note: This function does return.

Definition at line 2874 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]	fiber	The fiber to resume.
[in]	argc	Number of objects of `argv`.
[in]	argv	Passed (somehow) to `fiber`.
[in]	kw_splat	Handling 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	`fiber` is terminated etc.
rb_eException	Any exceptions happen in `fiber`.

Returns: Either what was yielded or the last value of the fiber body.

Definition at line 2868 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]	fiber	Explicit control destination.
[in]	argc	Number of objects of `argv`.
[in]	argv	Passed to rb_fiber_resume().

Exceptions

rb_eFiberError	(See above)
rb_eException	What was raised using `Fiber#raise`.

Returns: (See rb_fiber_resume() for details)

Definition at line 2701 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]	fiber	Explicit control destination.
[in]	argc	Number of objects of `argv`.
[in]	argv	Passed to rb_fiber_resume().
[in]	kw_splat	Handling 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_eException	What was raised using `Fiber#raise`.

Returns: (See rb_fiber_resume() for details)

Definition at line 3114 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]	argc	Number of objects of `argv`.
[in]	argv	Passed to rb_fiber_resume().

Exceptions

rb_eException (See above)

Returns: (See rb_fiber_resume() for details)

Definition at line 2886 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]	argc	Number of objects of `argv`.
[in]	argv	Passed to rb_fiber_resume().
[in]	kw_splat	Handling 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_eException What was raised using Fiber#raise.

Returns: (See rb_fiber_resume() for details)

Definition at line 2880 of file cont.c.

◆ rb_obj_is_fiber()

VALUE rb_obj_is_fiber ( VALUE obj )

Queries if an object is a fiber.

Parameters

[in] obj Arbitrary ruby object.

Return values

RUBY_Qtrue	It is.
RUBY_Qfalse	It isn't.

Definition at line 1181 of file cont.c.

Referenced by rb_fiber_scheduler_unblock().

(892c46283a5ea4179500d951c9d4866c0051f27b)

Functions

Detailed Description

Function Documentation

◆ rb_fiber_alive_p()

◆ rb_fiber_current()

◆ rb_fiber_new()

◆ rb_fiber_new_storage()

◆ rb_fiber_raise()

◆ rb_fiber_resume()

◆ rb_fiber_resume_kw()

◆ rb_fiber_transfer()

◆ rb_fiber_transfer_kw()

◆ rb_fiber_yield()

◆ rb_fiber_yield_kw()

◆ rb_obj_is_fiber()