Ruby  3.4.0dev (2024-11-05 revision 348a53415339076afc4a02fcd09f3ae36e9c4c61)
Functions
proc.h File Reference

(348a53415339076afc4a02fcd09f3ae36e9c4c61)

Public APIs related to rb_cProc. More...

#include "ruby/internal/dllexport.h"
#include "ruby/internal/iterator.h"
#include "ruby/internal/value.h"
Include dependency graph for proc.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions

VALUE rb_block_proc (void)
 Constructs a Proc object from implicitly passed components. More...
 
VALUE rb_block_lambda (void)
 Identical to rb_proc_new(), except it returns a lambda. More...
 
VALUE rb_proc_new (rb_block_call_func_t func, VALUE callback_arg)
 This is an rb_iterate() + rb_block_proc() combo. More...
 
VALUE rb_obj_is_proc (VALUE recv)
 Queries if the given object is a proc. More...
 
VALUE rb_proc_call (VALUE recv, VALUE args)
 Evaluates the passed proc with the passed arguments. More...
 
VALUE rb_proc_call_kw (VALUE recv, VALUE args, int kw_splat)
 Identical to rb_proc_call(), except you can specify how to handle the last element of the given array. More...
 
VALUE rb_proc_call_with_block (VALUE recv, int argc, const VALUE *argv, VALUE proc)
 Identical to rb_proc_call(), except you can additionally pass another proc object, as a block. More...
 
VALUE rb_proc_call_with_block_kw (VALUE recv, int argc, const VALUE *argv, VALUE proc, int kw_splat)
 Identical to rb_proc_call_with_block(), except you can specify how to handle the last element of the given array. More...
 
int rb_proc_arity (VALUE recv)
 Queries the number of mandatory arguments of the given Proc. More...
 
VALUE rb_proc_lambda_p (VALUE recv)
 Queries if the given object is a lambda. More...
 
VALUE rb_binding_new (void)
 Snapshots the current execution context and turn it into an instance of rb_cBinding. More...
 
VALUE rb_obj_method (VALUE recv, VALUE mid)
 Creates a method object. More...
 
VALUE rb_obj_is_method (VALUE recv)
 Queries if the given object is a method. More...
 
VALUE rb_method_call (int argc, const VALUE *argv, VALUE recv)
 Evaluates the passed method with the passed arguments. More...
 
VALUE rb_method_call_kw (int argc, const VALUE *argv, VALUE recv, int kw_splat)
 Identical to rb_method_call(), except you can specify how to handle the last element of the given array. More...
 
VALUE rb_method_call_with_block (int argc, const VALUE *argv, VALUE recv, VALUE proc)
 Identical to rb_proc_call(), except you can additionally pass a proc as a block. More...
 
VALUE rb_method_call_with_block_kw (int argc, const VALUE *argv, VALUE recv, VALUE proc, int kw_splat)
 Identical to rb_method_call_with_block(), except you can specify how to handle the last element of the given array. More...
 
int rb_mod_method_arity (VALUE mod, ID mid)
 Queries the number of mandatory arguments of the method defined in the given module. More...
 
int rb_obj_method_arity (VALUE obj, ID mid)
 Identical to rb_mod_method_arity(), except it searches for singleton methods rather than instance methods. More...
 
VALUE rb_protect (VALUE(*func)(VALUE args), VALUE args, int *state)
 Protects a function call from potential global escapes from the function. More...
 

Detailed Description

Public APIs related to rb_cProc.

Author
Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org
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 proc.h.

Function Documentation

◆ rb_binding_new()

VALUE rb_binding_new ( void  )

Snapshots the current execution context and turn it into an instance of rb_cBinding.

Returns
An instance of rb_cBinding.

Definition at line 324 of file proc.c.

◆ rb_block_lambda()

VALUE rb_block_lambda ( void  )

Identical to rb_proc_new(), except it returns a lambda.

Exceptions
rb_eArgErrorThere is no passed block.
Returns
An instance of rb_cProc.

Definition at line 832 of file proc.c.

◆ rb_block_proc()

VALUE rb_block_proc ( void  )

Constructs a Proc object from implicitly passed components.

When a ruby method is called with a block, that block is not explicitly passed around using C level function parameters. This function gathers all the necessary info to turn them into a Ruby level instance of rb_cProc.

Exceptions
rb_eArgErrorThere is no passed block.
Returns
An instance of rb_cProc.

Definition at line 813 of file proc.c.

Referenced by rb_f_trace_var(), rb_method_call(), and rb_method_call_kw().

◆ rb_method_call()

VALUE rb_method_call ( int  argc,
const VALUE argv,
VALUE  recv 
)

Evaluates the passed method with the passed arguments.

Parameters
[in]argcNumber of objects of argv.
[in]argvArbitrary number of method arguments.
[in]recvThe method object to call.
Exceptions
rb_eTypeErrorrecv is not a method.
rb_eExceptionAny exceptions happen inside.
Returns
What the method returns.

Definition at line 2488 of file proc.c.

◆ rb_method_call_kw()

VALUE rb_method_call_kw ( int  argc,
const VALUE argv,
VALUE  recv,
int  kw_splat 
)

Identical to rb_method_call(), except you can specify how to handle the last element of the given array.

Parameters
[in]argcNumber of objects of argv.
[in]argvArbitrary number of method arguments.
[in]recvThe method object to call.
[in]kw_splatHandling of keyword parameters:
  • RB_NO_KEYWORDS args' last is not a keyword argument.
  • RB_PASS_KEYWORDS args' last is a keyword argument.
  • RB_PASS_CALLED_KEYWORDS it depends if there is a passed block.
Exceptions
rb_eTypeErrorrecv is not a method.
rb_eExceptionAny exceptions happen inside.
Returns
What the method returns.

Definition at line 2481 of file proc.c.

◆ rb_method_call_with_block()

VALUE rb_method_call_with_block ( int  argc,
const VALUE argv,
VALUE  recv,
VALUE  proc 
)

Identical to rb_proc_call(), except you can additionally pass a proc as a block.

Parameters
[in]argcNumber of objects of argv.
[in]argvArbitrary number of method arguments.
[in]recvThe method object to call.
[in]procProc as a passed block.
Exceptions
rb_eTypeErrorrecv is not a method.
rb_eExceptionAny exceptions happen inside.
Returns
What the method returns.

Definition at line 2524 of file proc.c.

Referenced by rb_method_call().

◆ rb_method_call_with_block_kw()

VALUE rb_method_call_with_block_kw ( int  argc,
const VALUE argv,
VALUE  recv,
VALUE  proc,
int  kw_splat 
)

Identical to rb_method_call_with_block(), except you can specify how to handle the last element of the given array.

It can also be seen as a routine identical to rb_method_call_kw(), except you can additionally pass another proc object as a block.

Parameters
[in]argcNumber of objects of argv.
[in]argvArbitrary number of method arguments.
[in]recvThe method object to call.
[in]procProc as a passed block.
[in]kw_splatHandling of keyword parameters:
  • RB_NO_KEYWORDS args' last is not a keyword argument.
  • RB_PASS_KEYWORDS args' last is a keyword argument.
  • RB_PASS_CALLED_KEYWORDS it depends if there is a passed block.
Exceptions
rb_eTypeErrorrecv is not a method.
rb_eExceptionAny exceptions happen inside.
Returns
What the method returns.

Definition at line 2511 of file proc.c.

Referenced by rb_method_call_kw(), and rb_method_call_with_block().

◆ rb_mod_method_arity()

int rb_mod_method_arity ( VALUE  mod,
ID  mid 
)

Queries the number of mandatory arguments of the method defined in the given module.

If it is declared to take no arguments, returns 0. If it takes exactly n arguments, returns n. If it has optional arguments, returns -n-1, where n is the number of mandatory arguments. Keyword arguments will be considered as a single additional argument, that argument being mandatory if any keyword argument is mandatory.

Parameters
[in]modNamespace to search a method for.
[in]midMethod id.
Return values
0It takes no arguments.
>0It takes exactly this number of arguments.
<0It takes optional arguments.

Definition at line 2892 of file proc.c.

Referenced by rb_obj_method_arity().

◆ rb_obj_is_method()

VALUE rb_obj_is_method ( VALUE  recv)

Queries if the given object is a method.

Note
This is about the object's data structure, not its class etc.
Parameters
[in]recvObject in question.
Return values
RUBY_QtrueIt is a method.
RUBY_QfalseOtherwise.

Definition at line 1610 of file proc.c.

Referenced by rb_econv_prepare_options().

◆ rb_obj_is_proc()

VALUE rb_obj_is_proc ( VALUE  recv)

Queries if the given object is a proc.

Note
This is about the object's data structure, not its class etc.
Parameters
[in]recvObject in question.
Return values
RUBY_QtrueIt is a proc.
RUBY_QfalseOtherwise.

Definition at line 119 of file proc.c.

Referenced by rb_econv_prepare_options().

◆ rb_obj_method()

VALUE rb_obj_method ( VALUE  recv,
VALUE  mid 
)

Creates a method object.

A method object is a proc-like object that you can "call". Note that a method object snapshots the method at the time the object is created:

class Foo
def foo
return 1
end
end
obj = Foo.new.method(:foo)
class Foo
def foo
return 2
end
end
obj.call # => 1, not 2.
Parameters
[in]recvReceiver of the method.
[in]midMethod name, in either String or Symbol.
Exceptions
rb_eNoMethodErrorNo such method.
Returns
An instance of rb_cMethod.

Definition at line 2048 of file proc.c.

◆ rb_obj_method_arity()

int rb_obj_method_arity ( VALUE  obj,
ID  mid 
)

Identical to rb_mod_method_arity(), except it searches for singleton methods rather than instance methods.

Parameters
[in]objObject to search for a singleton method.
[in]midMethod id.
Return values
0It takes no arguments.
>0It takes exactly this number of arguments.
<0It takes optional arguments.

Definition at line 2900 of file proc.c.

◆ rb_proc_arity()

int rb_proc_arity ( VALUE  recv)

Queries the number of mandatory arguments of the given Proc.

If its block is declared to take no arguments, returns 0. If the block is known to take exactly n arguments, returns n. If the block has optional arguments, returns -n-1, where n is the number of mandatory arguments, with the exception for blocks that are not lambdas and have only a finite number of optional arguments; in this latter case, returns n. Keyword arguments will be considered as a single additional argument, that argument being mandatory if any keyword argument is mandatory.

Parameters
[in]recvTarget Proc object.
Return values
0It takes no arguments.
>0It takes exactly this number of arguments.
<0It takes optional arguments.

Definition at line 1102 of file proc.c.

◆ rb_proc_call()

VALUE rb_proc_call ( VALUE  recv,
VALUE  args 
)

Evaluates the passed proc with the passed arguments.

Parameters
[in]recvThe proc to call.
[in]argsAn instance of RArray which is the arguments.
Exceptions
rb_eExceptionAny exceptions happen inside.
Returns
What the proc evaluates to.

Definition at line 971 of file proc.c.

◆ rb_proc_call_kw()

VALUE rb_proc_call_kw ( VALUE  recv,
VALUE  args,
int  kw_splat 
)

Identical to rb_proc_call(), except you can specify how to handle the last element of the given array.

Parameters
[in]recvThe proc to call.
[in]argsAn instance of RArray which is the arguments.
[in]kw_splatHandling of keyword parameters:
  • RB_NO_KEYWORDS args' last is not a keyword argument.
  • RB_PASS_KEYWORDS args' last is a keyword argument.
  • RB_PASS_CALLED_KEYWORDS it depends if there is a passed block.
Exceptions
rb_eExceptionAny exceptions happen inside.
Returns
What the proc evaluates to.

Definition at line 956 of file proc.c.

Referenced by rb_proc_call().

◆ rb_proc_call_with_block()

VALUE rb_proc_call_with_block ( VALUE  recv,
int  argc,
const VALUE argv,
VALUE  proc 
)

Identical to rb_proc_call(), except you can additionally pass another proc object, as a block.

Nowadays procs can take blocks:

l = -> (positional, optional=nil, *rest, kwarg:, **kwrest, &block) {
# ... how can we pass this `&block`? ^^^^^^
}

And this function is to pass one to such procs.

Parameters
[in]recvThe proc to call.
[in]argcNumber of arguments.
[in]argvArbitrary number of proc arguments.
[in]procProc as a passed block.
Exceptions
rb_eExceptionAny exceptions happen inside.
Returns
What the proc evaluates to.

Definition at line 995 of file proc.c.

◆ rb_proc_call_with_block_kw()

VALUE rb_proc_call_with_block_kw ( VALUE  recv,
int  argc,
const VALUE argv,
VALUE  proc,
int  kw_splat 
)

Identical to rb_proc_call_with_block(), except you can specify how to handle the last element of the given array.

It can also be seen as a routine identical to rb_proc_call_kw(), except you can additionally pass another proc object as a block.

Parameters
[in]recvThe proc to call.
[in]argcNumber of arguments.
[in]argvArbitrary number of proc arguments.
[in]procProc as a passed block.
[in]kw_splatHandling of keyword parameters:
  • RB_NO_KEYWORDS args' last is not a keyword argument.
  • RB_PASS_KEYWORDS args' last is a keyword argument.
  • RB_PASS_CALLED_KEYWORDS it depends if there is a passed block.
Exceptions
rb_eExceptionAny exceptions happen inside.
Returns
What the proc evaluates to.

Definition at line 983 of file proc.c.

Referenced by rb_proc_call_with_block().

◆ rb_proc_lambda_p()

VALUE rb_proc_lambda_p ( VALUE  recv)

Queries if the given object is a lambda.

Instances of rb_cProc are either lambda or proc. They differ in several points. This function can distinguish them without actually evaluating their contents.

Parameters
[in]recvTarget proc object.
Return values
RUBY_QtrueIt is a lambda.
RUBY_QfalseOtherwise.

Definition at line 244 of file proc.c.

◆ rb_proc_new()

VALUE rb_proc_new ( rb_block_call_func_t  func,
VALUE  callback_arg 
)

This is an rb_iterate() + rb_block_proc() combo.

my_own_iterator(RB_BLOCK_CALL_FUNC_ARGLIST(y, c))
{
const auto plus = rb_intern("+");
return rb_funcall(c, plus, 1, y);
}
my_own_method(VALUE self)
{
return rb_proc_new(my_own_iterator, self);
}
VALUE rb_funcall(VALUE recv, ID mid, int n,...)
Calls a method.
Definition: vm_eval.c:1099
VALUE rb_proc_new(rb_block_call_func_t func, VALUE callback_arg)
This is an rb_iterate() + rb_block_proc() combo.
Definition: proc.c:3332
ID rb_intern(const char *name)
Finds or creates a symbol of the given name.
Definition: symbol.c:823
#define RB_BLOCK_CALL_FUNC_ARGLIST(yielded_arg, callback_arg)
Shim for block function parameters.
Definition: iterator.h:58
uintptr_t VALUE
Type that represents a Ruby object.
Definition: value.h:40
Parameters
[in]funcA backend function of a proc.
[in]callback_argPassed to func's callback_arg.
Returns
A C-backended proc object.

Definition at line 3332 of file proc.c.

Referenced by rb_fiber_new_storage(), rb_fiber_scheduler_blocking_region(), and ruby::backward::cxxanyargs::rb_proc_new().

◆ rb_protect()

VALUE rb_protect ( VALUE(*)(VALUE args)  func,
VALUE  args,
int *  state 
)

Protects a function call from potential global escapes from the function.

Such global escapes include exceptions, throw, break, for example.

It first calls the function func with args as the argument. If no global escape occurred during the function, it returns the result and *state is zero. Otherwise, it returns RUBY_Qnil and sets *state to nonzero. If state is NULL, it is not set in both cases.

Parameters
[in]funcA function that potentially escapes globally.
[in]argsPassed as-is to func.
[out]stateState of execution.
Returns
What func returns, or an undefined value when it did not return.
Postcondition
*state is set to zero if succeeded. Nonzero otherwise.
Warning
You have to clear the error info with rb_set_errinfo(Qnil) if you decide to ignore the caught exception.
See also
rb_eval_string_protect()
rb_load_protect()

Referenced by rb_eval_string_protect(), rb_eval_string_wrap(), rb_f_exec(), and rb_io_open_descriptor().