Ruby
3.4.0dev (2024-11-05 revision 348a53415339076afc4a02fcd09f3ae36e9c4c61)
|
Public APIs related to rb_cFiber. More...
#include "ruby/internal/dllexport.h"
#include "ruby/internal/value.h"
#include "ruby/internal/iterator.h"
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... | |
Public APIs related to rb_cFiber.
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. __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.
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.
[in] | fiber | A target fiber. |
RUBY_Qtrue | It is. |
RUBY_Qfalse | It isn't. |
VALUE rb_fiber_current | ( | void | ) |
VALUE rb_fiber_new | ( | rb_block_call_func_t | func, |
VALUE | callback_obj | ||
) |
Creates a Fiber instance from a C-backended block.
[in] | func | A function, to become the fiber's body. |
[in] | callback_obj | Passed as-is to func . |
Definition at line 2295 of file cont.c.
Referenced by ruby::backward::cxxanyargs::rb_fiber_new().
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.
[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. |
Definition at line 2289 of file cont.c.
Referenced by rb_fiber_new().
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.
[out] | fiber | Where exception is raised. |
[in] | argc | Passed as-is to rb_make_exception(). |
[in] | argv | Passed as-is to rb_make_exception(). |
rb_eFiberError | fiber is terminated etc. |
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.
Above program executes in [a] <x> <y> [b] [c] <z> <w> [d]
.
[out] | fiber | The fiber to resume. |
[in] | argc | Number of objects of argv . |
[in] | argv | Passed (somehow) to fiber . |
rb_eFiberError | fib is terminated etc. |
rb_eException | Any exceptions happen in fiber . |
Identical to rb_fiber_resume(), except you can specify how to handle the last element of the given array.
[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_eFiberError | fiber is terminated etc. |
rb_eException | Any exceptions happen in fiber . |
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 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.
[out] | fiber | Explicit control destination. |
[in] | argc | Number of objects of argv . |
[in] | argv | Passed to rb_fiber_resume(). |
rb_eFiberError | (See above) |
rb_eException | What was raised using Fiber#raise . |
Identical to rb_fiber_transfer(), except you can specify how to handle the last element of the given array.
[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_eFiberError | (See above) |
rb_eException | What was raised using Fiber#raise . |
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().
[in] | argc | Number of objects of argv . |
[in] | argv | Passed to rb_fiber_resume(). |
rb_eException | (See above) |
Identical to rb_fiber_yield(), except you can specify how to handle the last element of the given array.
[in] | argc | Number of objects of argv . |
[in] | argv | Passed to rb_fiber_resume(). |
[in] | kw_splat | Handling of keyword parameters:
|
rb_eException | What was raised using Fiber#raise . |
Queries if an object is a fiber.
[in] | obj | Arbitrary ruby object. |
RUBY_Qtrue | It is. |
RUBY_Qfalse | It isn't. |
Definition at line 1178 of file cont.c.
Referenced by rb_fiber_scheduler_unblock().