Ruby: include/ruby/internal/intern/proc.h File Reference

Ruby 3.3.5p100 (2024-09-03 revision ef084cc8f4958c1b6e4ead99136631bef6d8ddba)

Functions
proc.h File Reference

Public APIs related to rb_cProc. More...

`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/iterator.h"`
`#include "ruby/internal/value.h"`

Go to the source code of this file.

## Functions
VALUE | rb_block_proc (void)
| Constructs a Proc object from implicitly passed components.
VALUE | rb_block_lambda (void)
| Identical to rb_proc_new(), except it returns a lambda.
VALUE | rb_proc_new (rb_block_call_func_t func, VALUE callback_arg)
| This is an rb_iterate() + rb_block_proc() combo.
VALUE | rb_obj_is_proc (VALUE recv)
| Queries if the given object is a proc.
VALUE | rb_proc_call (VALUE recv, VALUE args)
| Evaluates the passed proc with the passed arguments.
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.
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.
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.
int | rb_proc_arity (VALUE recv)
| Queries the number of mandatory arguments of the given Proc.
VALUE | rb_proc_lambda_p (VALUE recv)
| Queries if the given object is a lambda.
VALUE | rb_binding_new (void)
| Snapshots the current execution context and turn it into an instance of rb_cBinding.
VALUE | rb_obj_method (VALUE recv, VALUE mid)
| Creates a method object.
VALUE | rb_obj_is_method (VALUE recv)
| Queries if the given object is a method.
VALUE | rb_method_call (int argc, const VALUE *argv, VALUE recv)
| Evaluates the passed method with the passed arguments.
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.
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.
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.
int | rb_mod_method_arity (VALUE mod, ID mid)
| Queries the number of mandatory arguments of the method defined in the given module.
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.
VALUE | rb_protect (VALUE(*func)(VALUE args), VALUE args, int *state)
| Protects a function call from potential global escapes from the function.

## 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 323 of file proc.c.

Referenced by rb_binding_new().

## ◆ 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 826 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 807 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 2441 of file proc.c.

Referenced by rb_method_call().

## ◆ 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 2434 of file proc.c.

Referenced by rb_method_call_kw().

## ◆ 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 2477 of file proc.c.

Referenced by rb_method_call(), and rb_method_call_with_block().

## ◆ 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 2464 of file proc.c.

Referenced by rb_method_call_kw(), rb_method_call_with_block(), and rb_method_call_with_block_kw().

## ◆ 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 2845 of file proc.c.

Referenced by rb_mod_method_arity(), and 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 1582 of file proc.c.

Referenced by rb_econv_prepare_options(), and rb_obj_is_method().

## ◆ 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 118 of file proc.c.

Referenced by rb_econv_prepare_options(), and rb_obj_is_proc().

## ◆ 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 2020 of file proc.c.

Referenced by rb_obj_method().

## ◆ 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 2853 of file proc.c.

Referenced by rb_obj_method_arity().

## ◆ 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 1096 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 965 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 950 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 989 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 977 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 243 of file proc.c.

Referenced by rb_proc_lambda_p().

## ◆ 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);
}
rb_funcall
VALUE rb_funcall(VALUE recv, ID mid, int n,...)
Calls a method.
Definition vm_eval.c:1121
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.
Definition proc.c:3285
RB_BLOCK_CALL_FUNC_ARGLIST
#define RB_BLOCK_CALL_FUNC_ARGLIST(yielded_arg, callback_arg)
Shim for block function parameters.
Definition iterator.h:58
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40

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 3285 of file proc.c.

## ◆ rb_protect()

VALUE rb_protect | ( | VALUE(* | func )(VALUE args),
|  | 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()

Definition at line 974 of file eval.c.