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

Ruby 3.4.1p0 (2024-12-25 revision 48d4efcb85000e1ebae42004e963b5d0cedddcf2)

Macros | Typedefs | Functions
vm.h File Reference

Public APIs related to rb_cRubyVM. More...

`#include "ruby/internal/attr/nonnull.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.

## Macros
#define | HAVE_RB_DEFINE_ALLOC_FUNC 1

## Typedefs
typedef VALUE(* | rb_alloc_func_t) (VALUE klass)
| This is the type of functions that ruby calls when trying to allocate an object.

## Functions
int | rb_sourceline (void)
| Resembles `__LINE__`.
const char * | rb_sourcefile (void)
| Resembles `__FILE__`.
int | rb_frame_method_id_and_class (ID *idp, VALUE *klassp)
| Resembles `__method__`.
VALUE | rb_check_funcall (VALUE recv, ID mid, int argc, const VALUE *argv)
| Identical to rb_funcallv(), except it returns RUBY_Qundef instead of raising rb_eNoMethodError.
VALUE | rb_check_funcall_kw (VALUE recv, ID mid, int argc, const VALUE *argv, int kw_splat)
| Identical to rb_check_funcall(), except you can specify how to handle the last element of the given array.
VALUE | rb_eval_cmd_kw (VALUE cmd, VALUE arg, int kw_splat)
| This API is practically a variant of rb_proc_call_kw() now.
VALUE | rb_apply (VALUE recv, ID mid, VALUE args)
| Identical to rb_funcallv(), except it takes Ruby's array instead of C's.
VALUE | rb_obj_instance_eval (int argc, const VALUE *argv, VALUE recv)
| Evaluates a string containing Ruby source code, or the given block, within the context of the receiver.
VALUE | rb_obj_instance_exec (int argc, const VALUE *argv, VALUE recv)
| Executes the given block within the context of the receiver.
VALUE | rb_mod_module_eval (int argc, const VALUE *argv, VALUE mod)
| Identical to rb_obj_instance_eval(), except it evaluates within the context of module.
VALUE | rb_mod_module_exec (int argc, const VALUE *argv, VALUE mod)
| Identical to rb_obj_instance_exec(), except it evaluates within the context of module.
void | rb_define_alloc_func (VALUE klass, rb_alloc_func_t func)
| Sets the allocator function of a class.
void | rb_undef_alloc_func (VALUE klass)
| Deletes the allocator function of a class.
rb_alloc_func_t | rb_get_alloc_func (VALUE klass)
| Queries the allocator function of a class.
void | rb_clear_constant_cache_for_id (ID id)
| Clears the inline constant caches associated with a particular ID.
void | rb_alias (VALUE klass, ID dst, ID src)
| Resembles `alias`.
void | rb_attr (VALUE klass, ID name, int need_reader, int need_writer, int honour_visibility)
| This function resembles now-deprecated `Module#attr`.
void | rb_remove_method (VALUE klass, const char *name)
| Removes a method.
void | rb_remove_method_id (VALUE klass, ID mid)
| Identical to rb_remove_method(), except it accepts the method name as ID.
int | rb_method_boundp (VALUE klass, ID id, int ex)
| Queries if the klass has this method.
int | rb_method_basic_definition_p (VALUE klass, ID mid)
| Well... Let us hesitate from describing what a "basic definition" is.
int | rb_obj_respond_to (VALUE obj, ID mid, int private_p)
| Identical to rb_respond_to(), except it additionally takes the visibility parameter.
int | rb_respond_to (VALUE obj, ID mid)
| Queries if the object responds to the method.
VALUE | rb_f_notimplement (int argc, const VALUE *argv, VALUE obj, VALUE marker)
| Raises rb_eNotImpError.
void | rb_backtrace (void)
| Prints the backtrace out to the standard error.
VALUE | rb_make_backtrace (void)
| Creates the good old fashioned array-of-strings style backtrace info.

## Detailed Description

Public APIs related to rb_cRubyVM.

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 vm.h.

## Macro Definition Documentation

## ◆ HAVE_RB_DEFINE_ALLOC_FUNC

#define HAVE_RB_DEFINE_ALLOC_FUNC 1

Deprecated
  This macro once was a thing in the old days, but makes no sense any longer today. Exists here for backwards compatibility only. You can safely forget about it.

Definition at line 204 of file vm.h.

## Typedef Documentation

## ◆ rb_alloc_func_t

typedef VALUE(* rb_alloc_func_t) (VALUE klass)

This is the type of functions that ruby calls when trying to allocate an object.

It is sometimes necessary to allocate extra memory regions for an object. When you define a class that uses RTypedData, it is typically the case. On such situations define a function of this type and pass it to rb_define_alloc_func().

Parameters

  [in] | klass | The class that this function is registered.

Returns
  A newly allocated instance of `klass`.

Definition at line 216 of file vm.h.

## Function Documentation

## ◆ rb_alias()

void rb_alias | ( | VALUE | klass,
|  | ID | dst,
|  | ID | src )

Resembles `alias`.

Parameters

  [out] | klass | Where to define an alias.
  [in] | dst | New name.
  [in] | src | Existing name.

Exceptions

  rb_eTypeError | `klass` is not a class.
  rb_eFrozenError | `klass` is frozen.
  rb_eNameError | No such method named `src`.

Postcondition
  `klass` has a method named `dst`, which is the identical to its method named `src`.

Definition at line 2289 of file vm_method.c.

Referenced by rb_define_alias().

## ◆ rb_apply()

VALUE rb_apply | ( | VALUE | recv,
|  | ID | mid,
|  | VALUE | args )

Identical to rb_funcallv(), except it takes Ruby's array instead of C's.

Parameters

  [in,out] | recv | Receiver of the method.
  [in] | mid | Name of the method to call.
  [in] | args | An instance of RArray.

Exceptions

  rb_eNoMethodError | No such method.
  rb_eException | Any exceptions happen inside.

Returns
  What the method evaluates to.

Precondition
  `args` must be an RArray. Call `to_ary` beforehand when necessary.

Definition at line 1074 of file vm_eval.c.

## ◆ rb_attr()

void rb_attr | ( | VALUE | klass,
|  | ID | name,
|  | int | need_reader,
|  | int | need_writer,
|  | int | honour_visibility )

This function resembles now-deprecated `Module#attr`.

Parameters

  [out] | klass | Where to define an attribute.
  [in] | name | Name of an instance variable.
  [in] | need_reader | Whether attr_reader is needed.
  [in] | need_writer | Whether attr_writer is needed.
  [in] | honour_visibility | Whether to use the current visibility.

Exceptions

  rb_eTypeError | `klass` is not a class.
  rb_eFrozenError | `klass` is frozen.

Postcondition
  If `need_reader` is set `klass` has a method named `name`.
  If `need_writer` is set `klass` has a method named `name=`.

Definition at line 1869 of file vm_method.c.

Referenced by rb_define_attr().

## ◆ rb_backtrace()

void rb_backtrace | ( | void |  | ) |

Prints the backtrace out to the standard error.

This just confuses people for no reason. Evil souls must only use it.

Definition at line 1149 of file vm_backtrace.c.

Referenced by rb_backtrace().

## ◆ rb_check_funcall()

VALUE rb_check_funcall | ( | VALUE | recv,
|  | ID | mid,
|  | int | argc,
|  | const VALUE * | argv )

Identical to rb_funcallv(), except it returns RUBY_Qundef instead of raising rb_eNoMethodError.

Parameters

  [in,out] | recv | Receiver of the method.
  [in] | mid | Name of the method to call.
  [in] | argc | Number of arguments.
  [in] | argv | Arbitrary number of method arguments.

Return values

  RUBY_Qundef | `recv` doesn't respond to `mid`.
  otherwise | What the method evaluates to.

Definition at line 668 of file vm_eval.c.

Referenced by rb_check_funcall(), rb_fiber_scheduler_address_resolve(), rb_fiber_scheduler_blocking_operation_wait(), rb_fiber_scheduler_close(), rb_fiber_scheduler_io_close(), rb_fiber_scheduler_io_pread(), rb_fiber_scheduler_io_pwrite(), rb_fiber_scheduler_io_read(), rb_fiber_scheduler_io_selectv(), rb_fiber_scheduler_io_write(), rb_fiber_scheduler_process_wait(), rb_io_descriptor(), and rb_range_values().

## ◆ rb_check_funcall_kw()

VALUE rb_check_funcall_kw | ( | VALUE | recv,
|  | ID | mid,
|  | int | argc,
|  | const VALUE * | argv,
|  | int | kw_splat )

Identical to rb_check_funcall(), 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_funcallv_kw(), except it returns RUBY_Qundef instead of raising rb_eNoMethodError.

Parameters

  [in,out] | recv | Receiver of the method.
  [in] | mid | Name of the method to call.
  [in] | argc | Number of arguments.
  [in] | argv | Arbitrary number of method arguments.
  [in] | kw_splat | Handling of keyword parameters: RB_NO_KEYWORDS `argv`'s last is not a keyword argument. RB_PASS_KEYWORDS `argv`'s last is a keyword argument. RB_PASS_CALLED_KEYWORDS it depends if there is a passed block.

Return values

  RUBY_Qundef | `recv` doesn't respond to `mid`.
  otherwise | What the method evaluates to.

Definition at line 662 of file vm_eval.c.

Referenced by rb_check_funcall_kw().

## ◆ rb_clear_constant_cache_for_id()

void rb_clear_constant_cache_for_id | ( | ID | id | ) |

Clears the inline constant caches associated with a particular ID.

Extension libraries should not bother with such things. Just forget about this API (or even, the presence of constant caches).

Definition at line 140 of file vm_method.c.

Referenced by rb_const_remove().

## ◆ rb_define_alloc_func()

void rb_define_alloc_func | ( | VALUE | klass,
|  | rb_alloc_func_t | func )

Sets the allocator function of a class.

Parameters

  [out] | klass | The class to modify.
  [in] | func | An allocator function for the class.

Precondition
  `klass` must be an instance of Class.

Referenced by rb_undef_alloc_func().

## ◆ rb_eval_cmd_kw()

VALUE rb_eval_cmd_kw | ( | VALUE | cmd,
|  | VALUE | arg,
|  | int | kw_splat )

This API is practically a variant of rb_proc_call_kw() now.

Historically when there still was a concept called `$SAFE`, this was an API for that. But we no longer have that. This function basically ended its role. It just remains here because of no harm.

Parameters

  [in] | cmd | A string, or something callable.
  [in] | arg | Argument passed to the call.
  [in] | kw_splat | Handling of keyword parameters: RB_NO_KEYWORDS `arg`'s last is not a keyword argument. RB_PASS_KEYWORDS `arg`'s last is a keyword argument. RB_PASS_CALLED_KEYWORDS it depends if there is a passed block.

Returns
  What the command evaluates to.

Definition at line 2055 of file vm_eval.c.

Referenced by rb_eval_cmd_kw().

## ◆ rb_f_notimplement()

VALUE rb_f_notimplement | ( | int | argc,
|  | const VALUE * | argv,
|  | VALUE | obj,
|  | VALUE | marker )

Raises rb_eNotImpError.

This function is used as an argument to rb_define_method() etc.

rb_define_method(rb_cFoo, "foo", rb_f_notimplement, -1);
rb_define_method
#define rb_define_method(klass, mid, func, arity)
Defines klass#mid.
Definition cxxanyargs.hpp:670
rb_f_notimplement
VALUE rb_f_notimplement(int argc, const VALUE *argv, VALUE obj, VALUE marker)
Raises rb_eNotImpError.
Definition vm_method.c:481

Parameters

  argc | Unused parameter.
  argv | Unused parameter.
  obj | Unused parameter.
  marker | Unused parameter.

Exceptions

  rb_eNotImpError | Always.

Returns
  Never returns.

Definition at line 481 of file vm_method.c.

Referenced by rb_define_alloc_func().

## ◆ rb_frame_method_id_and_class()

int rb_frame_method_id_and_class | ( | ID * | idp,
|  | VALUE * | klassp )

Resembles `__method__`.

Parameters

  [out] | idp | Return buffer for method id.
  [out] | klassp | Return buffer for class.

Return values

  0 | Current execution context not in a method.
  1 | Successful return.

Postcondition
  Upon successful return `*idp` and `*klassp` are updated to have the current method name and its defined class respectively.

Note
  Both parameters can be `NULL`.

Definition at line 2888 of file vm.c.

## ◆ rb_get_alloc_func()

rb_alloc_func_t rb_get_alloc_func | ( | VALUE | klass | ) |

Queries the allocator function of a class.

Parameters

  [in] | klass | The class in question.

Precondition
  `klass` must be an instance of Class.

Return values

  0 | No allocator function is registered.
  otherwise | The allocator function.

Definition at line 1297 of file vm_method.c.

Referenced by rb_get_alloc_func().

## ◆ rb_make_backtrace()

VALUE rb_make_backtrace | ( | void |  | ) |

Creates the good old fashioned array-of-strings style backtrace info.

Returns
  An array which contains strings, which are the textual representations of the backtrace locations of the current thread of the current ractor of the current execution context.

Note
  Ruby scripts can access more sophisticated `Thread::Backtrace::Location`. But it seems there is no way for C extensions to use that API.

Definition at line 1192 of file vm_backtrace.c.

## ◆ rb_method_basic_definition_p()

int rb_method_basic_definition_p | ( | VALUE | klass,
|  | ID | mid )

Well... Let us hesitate from describing what a "basic definition" is.

This nuanced concept should have been kept private. Just please. Don't touch it. This function is a badly distributed random number generator. Right?

Parameters

  [in] | klass | The class in question.
  [in] | mid | The method name in question.

Return values

  1 | It is.
  0 | It isn't.

Definition at line 2838 of file vm_method.c.

## ◆ rb_method_boundp()

int rb_method_boundp | ( | VALUE | klass,
|  | ID | id,
|  | int | ex )

Queries if the klass has this method.

This function has only one line of document in the implementation that states "// deprecated". Don't know what that means though.

Parameters

  [in] | klass | The class in question.
  [in] | id | The method name to query.
  [in] | ex | Undocumented magic value.

Return values

  false | Method not found.
  true | There is a method.

Precondition
  `klass` must be a module.

Definition at line 1830 of file vm_method.c.

Referenced by rb_define_alloc_func().

## ◆ rb_mod_module_eval()

VALUE rb_mod_module_eval | ( | int | argc,
|  | const VALUE * | argv,
|  | VALUE | mod )

Identical to rb_obj_instance_eval(), except it evaluates within the context of module.

Parameters

  [in] | argc | Number of objects in `argv`
  [in] | argv | C array of 0 up to 3 elements.
  [in] | mod | The module in question.

Precondition
  `mod` must be a Module.

Returns
  What was evaluated.

Definition at line 2299 of file vm_eval.c.

## ◆ rb_mod_module_exec()

VALUE rb_mod_module_exec | ( | int | argc,
|  | const VALUE * | argv,
|  | VALUE | mod )

Identical to rb_obj_instance_exec(), except it evaluates within the context of module.

Parameters

  [in] | argc | Number of objects in `argv`
  [in] | argv | Arbitrary parameters to be passed to the block.
  [in] | mod | The module in question.

Precondition
  `mod` must be a Module.

Returns
  What was evaluated.

Definition at line 2333 of file vm_eval.c.

## ◆ rb_obj_instance_eval()

VALUE rb_obj_instance_eval | ( | int | argc,
|  | const VALUE * | argv,
|  | VALUE | recv )

Evaluates a string containing Ruby source code, or the given block, within the context of the receiver.

In order to set the context, the variable `self` is set to `recv` while the code is executing, giving the code access to `recv`'s instance variables and private methods.

When given a block, `recv` is also passed in as the block's only argument.

When given a string, the optional second and third parameters supply a filename and starting line number that are used when reporting compilation errors.

Parameters

  [in] | argc | Number of objects in `argv`
  [in] | argv | C array of 0 up to 3 elements.
  [in] | recv | The object in question.

Returns
  What was evaluated.

Definition at line 2230 of file vm_eval.c.

## ◆ rb_obj_instance_exec()

VALUE rb_obj_instance_exec | ( | int | argc,
|  | const VALUE * | argv,
|  | VALUE | recv )

Executes the given block within the context of the receiver.

In order to set the context, the variable `self` is set to `recv` while the code is executing, giving the code access to `recv`'s instance variables. Arguments are passed as block parameters.

Parameters

  [in] | argc | Number of objects in `argv`
  [in] | argv | Arbitrary parameters to be passed to the block.
  [in] | recv | The object in question.

Returns
  What was evaluated.

Note
  Don't confuse this with rb_obj_instance_eval(). The key difference is whether you can pass arbitrary parameters to the block, like this:

class Foo
def initialize
@foo = 5
end
end
Foo.new.instance_exec(7) {|i| @foo + i } # => 12

Definition at line 2260 of file vm_eval.c.

## ◆ rb_obj_respond_to()

int rb_obj_respond_to | ( | VALUE | obj,
|  | ID | mid,
|  | int | private_p )

Identical to rb_respond_to(), except it additionally takes the visibility parameter.

This does not make difference unless the object has `respond_to?` undefined, but has `respond_to_missing?` defined. That case the passed argument becomes the second argument of `respond_to_missing?`.

Parameters

  [in] | obj | The object in question.
  [in] | mid | The method name in question.
  [in] | private_p | This is the second argument of `obj`'s `respond_to_missing?`.

Return values

  1 | Yes it does.
  0 | No it doesn't.

Definition at line 2944 of file vm_method.c.

Referenced by rb_define_alloc_func(), and rb_respond_to().

## ◆ rb_remove_method()

void rb_remove_method | ( | VALUE | klass,
|  | const char * | name )

Removes a method.

Don't confuse this to rb_undef_method(), which doesn't remove a method. This one resembles `Module#remove_method`.

Parameters

  [out] | klass | The class to remove a method.
  [in] | name | Name of a method to be removed.

Exceptions

  rb_eTypeError | `klass` is a non-module.
  rb_eFrozenError | `klass` is frozen.
  rb_eNameError | No such method.

See also
  rb_undef_method

Definition at line 1718 of file vm_method.c.

Referenced by rb_define_alloc_func().

## ◆ rb_remove_method_id()

void rb_remove_method_id | ( | VALUE | klass,
|  | ID | mid )

Identical to rb_remove_method(), except it accepts the method name as ID.

Parameters

  [out] | klass | The class to remove a method.
  [in] | mid | Name of a method to be removed.

Exceptions

  rb_eTypeError | `klass` is a non-module.
  rb_eFrozenError | `klass` is frozen.
  rb_eNameError | No such method.

See also
  rb_undef

Definition at line 1712 of file vm_method.c.

Referenced by rb_define_alloc_func().

## ◆ rb_respond_to()

int rb_respond_to | ( | VALUE | obj,
|  | ID | mid )

Queries if the object responds to the method.

This involves calling the object's `respond_to?` method.

Parameters

  [in] | obj | The object in question.
  [in] | mid | The method name in question.

Return values

  1 | Yes it does.
  0 | No it doesn't.

Definition at line 2960 of file vm_method.c.

Referenced by rb_define_alloc_func(), rb_econv_prepare_options(), and rb_str_equal().

## ◆ rb_sourcefile()

const char * rb_sourcefile | ( | void |  | ) |

Resembles `__FILE__`.

Return values

  0 | Current execution context not in a ruby method.
  otherwise | The current source path of the current thread of the current ractor of the current execution context.

Note
  This may or may not be an absolute path.

Definition at line 1872 of file vm.c.

## ◆ rb_sourceline()

int rb_sourceline | ( | void |  | ) |

Resembles `__LINE__`.

Return values

  0 | Current execution context not in a ruby method.
  otherwise | The current line number of the current thread of the current ractor of the current execution context.

Definition at line 1886 of file vm.c.

## ◆ rb_undef_alloc_func()

void rb_undef_alloc_func | ( | VALUE | klass | ) |

Deletes the allocator function of a class.

It is sometimes desirable to restrict creation of an instance of a class. For example it rarely makes sense for a DB adaptor class to allow programmers creating DB row objects without querying the DB itself. You can kill sporadic creation of such objects then, by nullifying the allocator function using this API.

Parameters

  [out] | klass | The class to modify.

Precondition
  `klass` must be an instance of Class.

Definition at line 1291 of file vm_method.c.

Referenced by rb_undef_alloc_func().