| Current File : //proc/thread-self/root/opt/alt/ruby33/include/ruby/internal/intern/cont.h |
#ifndef RBIMPL_INTERN_CONT_H /*-*-C++-*-vi:se ft=cpp:*/
#define RBIMPL_INTERN_CONT_H
/**
* @file
* @author Ruby developers <ruby-core@ruby-lang.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.
* @brief Public APIs related to rb_cFiber.
*/
#include "ruby/internal/dllexport.h"
#include "ruby/internal/value.h"
#include "ruby/internal/iterator.h"
RBIMPL_SYMBOL_EXPORT_BEGIN()
/* cont.c */
/**
* Creates a Fiber instance from a C-backended block.
*
* @param[in] func A function, to become the fiber's body.
* @param[in] callback_obj Passed as-is to `func`.
* @return An allocated new instance of rb_cFiber, which is ready to be
* "resume"d.
*/
VALUE rb_fiber_new(rb_block_call_func_t func, VALUE callback_obj);
/**
* 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.
*
* @param[in] func A function, to become the fiber's body.
* @param[in] callback_obj Passed as-is to `func`.
* @param[in] storage The way to set up the storage for the fiber.
* @return An allocated new instance of rb_cFiber, which is ready to be
* "resume"d.
*/
VALUE rb_fiber_new_storage(rb_block_call_func_t func, VALUE callback_obj, VALUE storage);
/**
* Queries the fiber which is calling this function. Any ruby execution
* context has its fiber, either explicitly or implicitly.
*
* @return The current fiber.
*/
VALUE rb_fiber_current(void);
/**
* 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.
*
* @param[in] fiber A target fiber.
* @retval RUBY_Qtrue It is.
* @retval RUBY_Qfalse It isn't.
*/
VALUE rb_fiber_alive_p(VALUE fiber);
/**
* Queries if an object is a fiber.
*
* @param[in] obj Arbitrary ruby object.
* @retval RUBY_Qtrue It is.
* @retval RUBY_Qfalse It isn't.
*/
VALUE rb_obj_is_fiber(VALUE obj);
/**
* 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.
*
* ```ruby
* 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]`.
*
* @param[out] fiber The fiber to resume.
* @param[in] argc Number of objects of `argv`.
* @param[in] argv Passed (somehow) to `fiber`.
* @exception rb_eFiberError `fib` is terminated etc.
* @exception rb_eException Any exceptions happen in `fiber`.
* @return (See above)
* @note This function _does_ return.
*
* @internal
*
* @shyouhei expected this function to raise ::rb_eFrozenError for frozen
* fibers but it doesn't in practice. Intentional or ...?
*/
VALUE rb_fiber_resume(VALUE fiber, int argc, const VALUE *argv);
/**
* Identical to rb_fiber_resume(), except you can specify how to handle the
* last element of the given array.
*
* @param[out] fiber The fiber to resume.
* @param[in] argc Number of objects of `argv`.
* @param[in] argv Passed (somehow) to `fiber`.
* @param[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.
* @exception rb_eFiberError `fiber` is terminated etc.
* @exception rb_eException Any exceptions happen in `fiber`.
* @return Either what was yielded or the last value of the fiber body.
*/
VALUE rb_fiber_resume_kw(VALUE fiber, int argc, const VALUE *argv, int kw_splat);
/**
* 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().
*
* ```ruby
* exc = Class.new Exception
*
* f = Fiber.new do
* Fiber.yield
* rescue exc => e
* puts e.message
* end
*
* f.resume
* f.raise exc, "Hi!"
* ```
*
* @param[in] argc Number of objects of `argv`.
* @param[in] argv Passed to rb_fiber_resume().
* @exception rb_eException (See above)
* @return (See rb_fiber_resume() for details)
*/
VALUE rb_fiber_yield(int argc, const VALUE *argv);
/**
* Identical to rb_fiber_yield(), except you can specify how to handle the last
* element of the given array.
*
* @param[in] argc Number of objects of `argv`.
* @param[in] argv Passed to rb_fiber_resume().
* @param[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.
* @exception rb_eException What was raised using `Fiber#raise`.
* @return (See rb_fiber_resume() for details)
*/
VALUE rb_fiber_yield_kw(int argc, const VALUE *argv, int kw_splat);
/**
* 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.
*
* @param[out] fiber Explicit control destination.
* @param[in] argc Number of objects of `argv`.
* @param[in] argv Passed to rb_fiber_resume().
* @exception rb_eFiberError (See above)
* @exception rb_eException What was raised using `Fiber#raise`.
* @return (See rb_fiber_resume() for details)
*/
VALUE rb_fiber_transfer(VALUE fiber, int argc, const VALUE *argv);
/**
* Identical to rb_fiber_transfer(), except you can specify how to handle the
* last element of the given array.
*
* @param[out] fiber Explicit control destination.
* @param[in] argc Number of objects of `argv`.
* @param[in] argv Passed to rb_fiber_resume().
* @param[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.
* @exception rb_eFiberError (See above)
* @exception rb_eException What was raised using `Fiber#raise`.
* @return (See rb_fiber_resume() for details)
*/
VALUE rb_fiber_transfer_kw(VALUE fiber, int argc, const VALUE *argv, int kw_splat);
/**
* 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.
*
* @param[out] fiber Where exception is raised.
* @param[in] argc Passed as-is to rb_make_exception().
* @param[in] argv Passed as-is to rb_make_exception().
* @exception rb_eFiberError `fiber` is terminated etc.
* @return (See rb_fiber_resume() for details)
*/
VALUE rb_fiber_raise(VALUE fiber, int argc, const VALUE *argv);
RBIMPL_SYMBOL_EXPORT_END()
#endif /* RBIMPL_INTERN_CONT_H */