diff options
Diffstat (limited to 'include/ruby/internal/intern/cont.h')
| -rw-r--r-- | include/ruby/internal/intern/cont.h | 54 |
1 files changed, 45 insertions, 9 deletions
diff --git a/include/ruby/internal/intern/cont.h b/include/ruby/internal/intern/cont.h index b0d9137dd9..32647f48aa 100644 --- a/include/ruby/internal/intern/cont.h +++ b/include/ruby/internal/intern/cont.h @@ -39,6 +39,28 @@ RBIMPL_SYMBOL_EXPORT_BEGIN() 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. * @@ -139,8 +161,7 @@ VALUE rb_fiber_resume_kw(VALUE fiber, int argc, const VALUE *argv, int kw_splat) * 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 `Fiber#raise` Ruby level API. There is no way to do that - * from C though. + * the fiber using rb_fiber_raise(). * * ```ruby * exc = Class.new Exception @@ -159,12 +180,6 @@ VALUE rb_fiber_resume_kw(VALUE fiber, int argc, const VALUE *argv, int kw_splat) * @param[in] argv Passed to rb_fiber_resume(). * @exception rb_eException (See above) * @return (See rb_fiber_resume() for details) - * - * @internal - * - * "There is no way to do that from C" is a lie. But @shyouhei doesn't think - * this very intentionally obfuscated way to raise arbitrary exceptions from C - * is an official C API. Extension libraries must not know this fact. */ VALUE rb_fiber_yield(int argc, const VALUE *argv); @@ -239,7 +254,28 @@ VALUE rb_fiber_transfer(VALUE fiber, int argc, const VALUE *argv); */ VALUE rb_fiber_transfer_kw(VALUE fiber, int argc, const VALUE *argv, int kw_splat); -VALUE rb_fiber_raise(VALUE fiber, int argc, 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. + * + * @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() |