Ruby  3.4.0dev (2024-11-05 revision 348a53415339076afc4a02fcd09f3ae36e9c4c61)
Macros | Typedefs | Functions
vm.h File Reference

(348a53415339076afc4a02fcd09f3ae36e9c4c61)

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"
Include dependency graph for vm.h:
This graph shows which files directly or indirectly include this file:

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. More...
 

Functions

int rb_sourceline (void)
 Resembles __LINE__. More...
 
const char * rb_sourcefile (void)
 Resembles __FILE__. More...
 
int rb_frame_method_id_and_class (ID *idp, VALUE *klassp)
 Resembles __method__. More...
 
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. More...
 
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. More...
 
VALUE rb_eval_cmd_kw (VALUE cmd, VALUE arg, int kw_splat)
 This API is practically a variant of rb_proc_call_kw() now. More...
 
VALUE rb_apply (VALUE recv, ID mid, VALUE args)
 Identical to rb_funcallv(), except it takes Ruby's array instead of C's. More...
 
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. More...
 
VALUE rb_obj_instance_exec (int argc, const VALUE *argv, VALUE recv)
 Executes the given block within the context of the receiver. More...
 
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. More...
 
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. More...
 
void rb_define_alloc_func (VALUE klass, rb_alloc_func_t func)
 Sets the allocator function of a class. More...
 
void rb_undef_alloc_func (VALUE klass)
 Deletes the allocator function of a class. More...
 
rb_alloc_func_t rb_get_alloc_func (VALUE klass)
 Queries the allocator function of a class. More...
 
void rb_clear_constant_cache_for_id (ID id)
 Clears the inline constant caches associated with a particular ID. More...
 
void rb_alias (VALUE klass, ID dst, ID src)
 Resembles alias. More...
 
void rb_attr (VALUE klass, ID name, int need_reader, int need_writer, int honour_visibility)
 This function resembles now-deprecated Module#attr. More...
 
void rb_remove_method (VALUE klass, const char *name)
 Removes a method. More...
 
void rb_remove_method_id (VALUE klass, ID mid)
 Identical to rb_remove_method(), except it accepts the method name as ID. More...
 
int rb_method_boundp (VALUE klass, ID id, int ex)
 Queries if the klass has this method. More...
 
int rb_method_basic_definition_p (VALUE klass, ID mid)
 Well... More...
 
int rb_obj_respond_to (VALUE obj, ID mid, int private_p)
 Identical to rb_respond_to(), except it additionally takes the visibility parameter. More...
 
int rb_respond_to (VALUE obj, ID mid)
 Queries if the object responds to the method. More...
 
VALUE rb_f_notimplement (int argc, const VALUE *argv, VALUE obj, VALUE marker)
 Raises rb_eNotImpError. More...
 
void rb_backtrace (void)
 Prints the backtrace out to the standard error. More...
 
VALUE rb_make_backtrace (void)
 Creates the good old fashioned array-of-strings style backtrace info. More...
 

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
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]klassThe 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]klassWhere to define an alias.
[in]dstNew name.
[in]srcExisting name.
Exceptions
rb_eTypeErrorklass is not a class.
rb_eFrozenErrorklass is frozen.
rb_eNameErrorNo such method named src.
Postcondition
klass has a method named dst, which is the identical to its method named src.

Definition at line 2284 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]recvReceiver of the method.
[in]midName of the method to call.
[in]argsAn instance of RArray.
Exceptions
rb_eNoMethodErrorNo such method.
rb_eExceptionAny 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]klassWhere to define an attribute.
[in]nameName of an instance variable.
[in]need_readerWhether attr_reader is needed.
[in]need_writerWhether attr_writer is needed.
[in]honour_visibilityWhether to use the current visibility.
Exceptions
rb_eTypeErrorklass is not a class.
rb_eFrozenErrorklass 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 1864 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.

◆ 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]recvReceiver of the method.
[in]midName of the method to call.
[in]argcNumber of arguments.
[in]argvArbitrary number of method arguments.
Return values
RUBY_Qundefrecv doesn't respond to mid.
otherwiseWhat the method evaluates to.

Definition at line 668 of file vm_eval.c.

Referenced by rb_fiber_scheduler_address_resolve(), rb_fiber_scheduler_blocking_region(), 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]recvReceiver of the method.
[in]midName of the method to call.
[in]argcNumber of arguments.
[in]argvArbitrary number of method arguments.
[in]kw_splatHandling 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_Qundefrecv doesn't respond to mid.
otherwiseWhat the method evaluates to.

Definition at line 662 of file vm_eval.c.

◆ 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.

◆ 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]klassThe class to modify.
[in]funcAn 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]cmdA string, or something callable.
[in]argArgument passed to the call.
[in]kw_splatHandling 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 2032 of file vm_eval.c.

◆ 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);
void rb_define_method(VALUE klass, const char *name, VALUE(*func)(ANYARGS), int argc)
Defines a method.
Definition: class.c:2142
VALUE rb_f_notimplement(int argc, const VALUE *argv, VALUE obj, VALUE marker)
Raises rb_eNotImpError.
Definition: vm_method.c:481
Parameters
argcUnused parameter.
argvUnused parameter.
objUnused parameter.
markerUnused parameter.
Exceptions
rb_eNotImpErrorAlways.
Returns
Never returns.

Definition at line 481 of file vm_method.c.

◆ rb_frame_method_id_and_class()

int rb_frame_method_id_and_class ( ID idp,
VALUE klassp 
)

Resembles __method__.

Parameters
[out]idpReturn buffer for method id.
[out]klasspReturn buffer for class.
Return values
0Current execution context not in a method.
1Successful 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 2869 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]klassThe class in question.
Precondition
klass must be an instance of Class.
Return values
0No allocator function is registered.
otherwiseThe allocator function.

Definition at line 1292 of file vm_method.c.

◆ 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]klassThe class in question.
[in]midThe method name in question.
Return values
1It is.
0It isn't.

Definition at line 2833 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]klassThe class in question.
[in]idThe method name to query.
[in]exUndocumented magic value.
Return values
falseMethod not found.
trueThere is a method.
Precondition
klass must be a module.

Definition at line 1825 of file vm_method.c.

◆ 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]argcNumber of objects in argv
[in]argvC array of 0 up to 3 elements.
[in]modThe module in question.
Precondition
mod must be a Module.
Returns
What was evaluated.

Definition at line 2276 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]argcNumber of objects in argv
[in]argvArbitrary parameters to be passed to the block.
[in]modThe module in question.
Precondition
mod must be a Module.
Returns
What was evaluated.

Definition at line 2310 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]argcNumber of objects in argv
[in]argvC array of 0 up to 3 elements.
[in]recvThe object in question.
Returns
What was evaluated.

Definition at line 2207 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]argcNumber of objects in argv
[in]argvArbitrary parameters to be passed to the block.
[in]recvThe 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 2237 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]objThe object in question.
[in]midThe method name in question.
[in]private_pThis is the second argument of obj's respond_to_missing?.
Return values
1Yes it does.
0No it doesn't.

Definition at line 2939 of file vm_method.c.

Referenced by 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]klassThe class to remove a method.
[in]nameName of a method to be removed.
Exceptions
rb_eTypeErrorklass is a non-module.
rb_eFrozenErrorklass is frozen.
rb_eNameErrorNo such method.
See also
rb_undef_method

Definition at line 1713 of file vm_method.c.

◆ 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]klassThe class to remove a method.
[in]midName of a method to be removed.
Exceptions
rb_eTypeErrorklass is a non-module.
rb_eFrozenErrorklass is frozen.
rb_eNameErrorNo such method.
See also
rb_undef

Definition at line 1707 of file vm_method.c.

◆ 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]objThe object in question.
[in]midThe method name in question.
Return values
1Yes it does.
0No it doesn't.

Definition at line 2955 of file vm_method.c.

Referenced by rb_econv_prepare_options(), and rb_str_equal().

◆ rb_sourcefile()

const char* rb_sourcefile ( void  )

Resembles __FILE__.

Return values
0Current execution context not in a ruby method.
otherwiseThe 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 1854 of file vm.c.

◆ rb_sourceline()

int rb_sourceline ( void  )

Resembles __LINE__.

Return values
0Current execution context not in a ruby method.
otherwiseThe current line number of the current thread of the current ractor of the current execution context.

Definition at line 1868 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]klassThe class to modify.
Precondition
klass must be an instance of Class.

Definition at line 1286 of file vm_method.c.