Ruby
3.4.0dev (2024-12-06 revision 892c46283a5ea4179500d951c9d4866c0051f27b)
|
Block related APIs. More...
#include "ruby/internal/attr/deprecated.h"
#include "ruby/internal/attr/noreturn.h"
#include "ruby/internal/dllexport.h"
#include "ruby/internal/value.h"
Go to the source code of this file.
Namespaces | |
ruby | |
The main namespace. | |
ruby::backward | |
Backwards compatibility layer. | |
Macros | |
#define | RB_BLOCK_CALL_FUNC_STRICT 1 |
#define | RUBY_BLOCK_CALL_FUNC_TAKES_BLOCKARG 1 |
#define | RB_BLOCK_CALL_FUNC_ARGLIST(yielded_arg, callback_arg) VALUE yielded_arg, VALUE callback_arg, int argc, const VALUE *argv, VALUE blockarg |
Shim for block function parameters. More... | |
Typedefs | |
typedef VALUE | rb_block_call_func(RB_BLOCK_CALL_FUNC_ARGLIST(yielded_arg, callback_arg)) |
This is the type of a function that the interpreter expect for C-backended blocks. More... | |
typedef rb_block_call_func * | rb_block_call_func_t |
Shorthand type that represents an iterator-written-in-C function pointer. More... | |
Functions | |
VALUE | rb_each (VALUE obj) |
This is a shorthand of calling obj.each . More... | |
VALUE | rb_yield (VALUE val) |
Yields the block. More... | |
VALUE | rb_yield_values (int n,...) |
Identical to rb_yield(), except it takes variadic number of parameters and pass them to the block. More... | |
VALUE | rb_yield_values2 (int n, const VALUE *argv) |
Identical to rb_yield_values(), except it takes the parameters as a C array instead of variadic arguments. More... | |
VALUE | rb_yield_values_kw (int n, const VALUE *argv, int kw_splat) |
Identical to rb_yield_values2(), except you can specify how to handle the last element of the given array. More... | |
VALUE | rb_yield_splat (VALUE ary) |
Identical to rb_yield_values(), except it splats an array to generate the list of parameters. More... | |
VALUE | rb_yield_splat_kw (VALUE ary, int kw_splat) |
Identical to rb_yield_splat(), except you can specify how to handle the last element of the given array. More... | |
VALUE | rb_yield_block (RB_BLOCK_CALL_FUNC_ARGLIST(yielded_arg, callback_arg)) |
Pass a passed block. More... | |
int | rb_keyword_given_p (void) |
Determines if the current method is given a keyword argument. More... | |
int | rb_block_given_p (void) |
Determines if the current method is given a block. More... | |
void | rb_need_block (void) |
Declares that the current method needs a block. More... | |
VALUE | rb_iterate (VALUE(*func1)(VALUE), VALUE data1, rb_block_call_func_t proc, VALUE data2) |
Old way to iterate a block. More... | |
static VALUE | ruby::backward::rb_iterate_deprecated (VALUE(*iter)(VALUE), VALUE data1, rb_block_call_func_t bl, VALUE data2) |
Old way to iterate a block. More... | |
VALUE | rb_block_call (VALUE obj, ID mid, int argc, const VALUE *argv, rb_block_call_func_t proc, VALUE data2) |
Identical to rb_funcallv(), except it additionally passes a function as a block. More... | |
VALUE | rb_block_call_kw (VALUE obj, ID mid, int argc, const VALUE *argv, rb_block_call_func_t proc, VALUE data2, int kw_splat) |
Identical to rb_funcallv_kw(), except it additionally passes a function as a block. More... | |
VALUE | rb_rescue (VALUE(*b_proc)(VALUE), VALUE data1, VALUE(*r_proc)(VALUE, VALUE), VALUE data2) |
Identical to rb_rescue2(), except it does not take a list of exception classes. More... | |
VALUE | rb_rescue2 (VALUE(*b_proc)(VALUE), VALUE data1, VALUE(*r_proc)(VALUE, VALUE), VALUE data2,...) |
An equivalent of rescue clause. More... | |
VALUE | rb_vrescue2 (VALUE(*b_proc)(VALUE), VALUE data1, VALUE(*r_proc)(VALUE, VALUE), VALUE data2, va_list ap) |
Identical to rb_rescue2(), except it takes va_list instead of variadic number of arguments. More... | |
VALUE | rb_ensure (VALUE(*b_proc)(VALUE), VALUE data1, VALUE(*e_proc)(VALUE), VALUE data2) |
An equivalent to ensure clause. More... | |
VALUE | rb_catch (const char *tag, rb_block_call_func_t func, VALUE data) |
Executes the passed block and catches values thrown from inside of it. More... | |
VALUE | rb_catch_obj (VALUE tag, rb_block_call_func_t func, VALUE data) |
Identical to rb_catch(), except it catches arbitrary Ruby objects. More... | |
void | rb_throw (const char *tag, VALUE val) |
Transfers control to the end of the active catch block waiting for tag . More... | |
void | rb_throw_obj (VALUE tag, VALUE val) |
Identical to rb_throw(), except it allows arbitrary Ruby object to become a tag. More... | |
Block related APIs.
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 iterator.h.
#define RB_BLOCK_CALL_FUNC_ARGLIST | ( | yielded_arg, | |
callback_arg | |||
) | VALUE yielded_arg, VALUE callback_arg, int argc, const VALUE *argv, VALUE blockarg |
Shim for block function parameters.
Historically rb_block_call_func_t had only two parameters. Over time it evolved to have much more than that. By using this macro you can absorb such API differences.
Definition at line 58 of file iterator.h.
#define RB_BLOCK_CALL_FUNC_STRICT 1 |
Exists here for backwards compatibility only. You can safely forget about it.
Definition at line 37 of file iterator.h.
#define RUBY_BLOCK_CALL_FUNC_TAKES_BLOCKARG 1 |
Exists here for backwards compatibility only. You can safely forget about it.
Definition at line 46 of file iterator.h.
typedef VALUE rb_block_call_func(RB_BLOCK_CALL_FUNC_ARGLIST(yielded_arg, callback_arg)) |
This is the type of a function that the interpreter expect for C-backended blocks.
Blocks are often written in Ruby. But C extensions might want to have their own blocks. In order to do so authors have to create a separate C function of this type, and pass its pointer to rb_block_call().
Definition at line 83 of file iterator.h.
typedef rb_block_call_func* rb_block_call_func_t |
Shorthand type that represents an iterator-written-in-C function pointer.
Definition at line 88 of file iterator.h.
VALUE rb_block_call | ( | VALUE | obj, |
ID | mid, | ||
int | argc, | ||
const VALUE * | argv, | ||
rb_block_call_func_t | proc, | ||
VALUE | data2 | ||
) |
Identical to rb_funcallv(), except it additionally passes a function as a block.
When the method yields, proc
is called with the yielded value as its first argument, and data2
as the second. Yielded values would be packed into an array if multiple values are yielded at once.
[in,out] | obj | Receiver. |
[in] | mid | Method signature. |
[in] | argc | Number of arguments. |
[in] | argv | Arguments passed to obj.mid . |
[in] | proc | A function acts as a block. |
[in,out] | data2 | Passed to proc as the data2 parameter. |
obj.mid
returns. Definition at line 1534 of file vm_eval.c.
Referenced by ruby::backward::cxxanyargs::rb_block_call(), and rb_proc_new().
VALUE rb_block_call_kw | ( | VALUE | obj, |
ID | mid, | ||
int | argc, | ||
const VALUE * | argv, | ||
rb_block_call_func_t | proc, | ||
VALUE | data2, | ||
int | kw_splat | ||
) |
Identical to rb_funcallv_kw(), except it additionally passes a function as a block.
It can also be seen as a routine identical to rb_block_call(), except it handles keyword-ness of argv[argc-1]
.
[in,out] | obj | Receiver. |
[in] | mid | Method signature. |
[in] | argc | Number of arguments including the keywords. |
[in] | argv | Arguments passed to obj.mid . |
[in] | proc | A function acts as a block. |
[in,out] | data2 | Passed to proc as the data2 parameter. |
[in] | kw_splat | Handling of keyword parameters:
|
obj.mid
returns. Definition at line 1541 of file vm_eval.c.
Referenced by rb_block_call().
VALUE rb_catch | ( | const char * | tag, |
rb_block_call_func_t | func, | ||
VALUE | data | ||
) |
Executes the passed block and catches values thrown from inside of it.
In case the block does not contain any throw`, this function returns the value of the last expression evaluated.
In case there do exist throw
, Ruby searches up its execution context for a catch
block. When a matching catch is found, the block stops executing and returns that thrown value instead.
[in] | tag | Arbitrary tag string. |
[in] | func | Function pointer that acts as a block. |
[in,out] | data | Extra parameter passed to func . |
tag
, or the return value of func
if nothing is thrown. Definition at line 2505 of file vm_eval.c.
Referenced by ruby::backward::cxxanyargs::rb_catch().
VALUE rb_catch_obj | ( | VALUE | tag, |
rb_block_call_func_t | func, | ||
VALUE | data | ||
) |
Identical to rb_catch(), except it catches arbitrary Ruby objects.
[in] | tag | Arbitrary tag object. |
[in] | func | Function pointer that acts as a block. |
[in,out] | data | Extra parameter passed to func . |
tag
, or the return value of func
if nothing is thrown. Definition at line 2547 of file vm_eval.c.
Referenced by ruby::backward::cxxanyargs::rb_catch_obj().
Old way to iterate a block.
[in] | func1 | A function that could yield a value. |
[in,out] | data1 | Passed to func1 |
[in] | proc | A function acts as a block. |
[in,out] | data2 | Passed to proc as the data2 parameter. |
func1
returns. Definition at line 1508 of file vm_eval.c.
Referenced by ruby::backward::rb_iterate_deprecated().
void rb_throw | ( | const char * | tag, |
VALUE | val | ||
) |
Transfers control to the end of the active catch
block waiting for tag
.
Raises rb_eUncughtThrow if there is no catch
block for the tag. The second parameter supplies a return value for the catch
block, which otherwise defaults to RUBY_Qnil. For examples, see rb_catch().
[in] | tag | Tag string. |
[in] | val | Value to throw. |
rb_eUncughtThrow | There is no corresponding catch clause. |
Identical to rb_throw(), except it allows arbitrary Ruby object to become a tag.
[in] | tag | Arbitrary object. |
[in] | val | Value to throw. |
rb_eUncughtThrow | There is no corresponding catch clause. |
Definition at line 2410 of file vm_eval.c.
Referenced by rb_throw().
Yields the block.
In Ruby there is a concept called a block. You can pass one to a method. In a method, when called with a block, you can yield it using this function.
[in] | val | Passed to the block. |
rb_eLocalJumpError | There is no block given. |
Definition at line 1354 of file vm_eval.c.
Referenced by rb_ary_delete(), and rb_ary_each().
VALUE rb_yield_block | ( | RB_BLOCK_CALL_FUNC_ARGLIST(yielded_arg, callback_arg) | ) |
Pass a passed block.
Sometimes you want to "pass" a block form one method to another. Suppose you have this Ruby method foo
:
And suppose you want to translate this into C. Then rb_yield_block() function is usable in this situation.
Identical to rb_yield_values(), except it splats an array to generate the list of parameters.
[in] | ary | Array to splat. |
rb_eLocalJumpError | There is no block given. |
Identical to rb_yield_splat(), except you can specify how to handle the last element of the given array.
[in] | ary | Array to splat. |
[in] | kw_splat | Handling of keyword parameters:
|
rb_eLocalJumpError | There is no block given. |
VALUE rb_yield_values | ( | int | n, |
... | |||
) |
Identical to rb_yield(), except it takes variadic number of parameters and pass them to the block.
[in] | n | Number of parameters. |
[in] | ... | List of arguments passed to the block. |
rb_eLocalJumpError | There is no block given. |
Identical to rb_yield_values(), except it takes the parameters as a C array instead of variadic arguments.
[in] | n | Number of parameters. |
[in] | argv | List of arguments passed to the block. |
rb_eLocalJumpError | There is no block given. |
Identical to rb_yield_values2(), except you can specify how to handle the last element of the given array.
[in] | n | Number of parameters. |
[in] | argv | List of arguments passed to the block. |
[in] | kw_splat | Handling of keyword parameters:
|
rb_eLocalJumpError | There is no block given. |