(892c46283a5ea4179500d951c9d4866c0051f27b)

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:

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

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.

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_eArgError There 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_eArgError There 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]	argc	Number of objects of `argv`.
[in]	argv	Arbitrary number of method arguments.
[in]	recv	The method object to call.

Exceptions

rb_eTypeError	`recv` is not a method.
rb_eException	Any 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]	argc	Number of objects of `argv`.
[in]	argv	Arbitrary number of method arguments.
[in]	recv	The method object to call.
[in]	kw_splat	Handling 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_eTypeError	`recv` is not a method.
rb_eException	Any 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]	argc	Number of objects of `argv`.
[in]	argv	Arbitrary number of method arguments.
[in]	recv	The method object to call.
[in]	proc	Proc as a passed block.

Exceptions

rb_eTypeError	`recv` is not a method.
rb_eException	Any 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]	argc	Number of objects of `argv`.
[in]	argv	Arbitrary number of method arguments.
[in]	recv	The method object to call.
[in]	proc	Proc as a passed block.
[in]	kw_splat	Handling 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_eTypeError	`recv` is not a method.
rb_eException	Any 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]	mod	Namespace to search a method for.
[in]	mid	Method id.

Return values

0	It takes no arguments.
>0	It takes exactly this number of arguments.
<0	It 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] recv Object in question.

Return values

RUBY_Qtrue	It is a method.
RUBY_Qfalse	Otherwise.

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] recv Object in question.

Return values

RUBY_Qtrue	It is a proc.
RUBY_Qfalse	Otherwise.

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]	recv	Receiver of the method.
[in]	mid	Method name, in either String or Symbol.

Exceptions

rb_eNoMethodError No 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]	obj	Object to search for a singleton method.
[in]	mid	Method id.

Return values

0	It takes no arguments.
>0	It takes exactly this number of arguments.
<0	It 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] recv Target Proc object.

Return values

0	It takes no arguments.
>0	It takes exactly this number of arguments.
<0	It 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]	recv	The proc to call.
[in]	args	An instance of RArray which is the arguments.

Exceptions

rb_eException Any 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]	recv	The proc to call.
[in]	args	An instance of RArray which is the arguments.
[in]	kw_splat	Handling 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_eException Any 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]	recv	The proc to call.
[in]	argc	Number of arguments.
[in]	argv	Arbitrary number of proc arguments.
[in]	proc	Proc as a passed block.

Exceptions

rb_eException Any 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]	recv	The proc to call.
[in]	argc	Number of arguments.
[in]	argv	Arbitrary number of proc arguments.
[in]	proc	Proc as a passed block.
[in]	kw_splat	Handling 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_eException Any 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] recv Target proc object.

Return values

RUBY_Qtrue	It is a lambda.
RUBY_Qfalse	Otherwise.

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.

VALUE
my_own_iterator(RB_BLOCK_CALL_FUNC_ARGLIST(y, c))
{
    const auto plus = rb_intern("+");
    return rb_funcall(c, plus, 1, y);
}
 
VALUE
my_own_method(VALUE self)
{
    return rb_proc_new(my_own_iterator, self);
}

Parameters

[in]	func	A backend function of a proc.
[in]	callback_arg	Passed 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_operation_wait(), 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]	func	A function that potentially escapes globally.
[in]	args	Passed as-is to `func`.
[out]	state	State 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().

(892c46283a5ea4179500d951c9d4866c0051f27b)

Functions

Detailed Description

Function Documentation

◆ rb_binding_new()

◆ rb_block_lambda()

◆ rb_block_proc()

◆ rb_method_call()

◆ rb_method_call_kw()

◆ rb_method_call_with_block()

◆ rb_method_call_with_block_kw()

◆ rb_mod_method_arity()

◆ rb_obj_is_method()

◆ rb_obj_is_proc()

◆ rb_obj_method()

◆ rb_obj_method_arity()

◆ rb_proc_arity()

◆ rb_proc_call()

◆ rb_proc_call_kw()

◆ rb_proc_call_with_block()

◆ rb_proc_call_with_block_kw()

◆ rb_proc_lambda_p()

◆ rb_proc_new()

◆ rb_protect()