(ff5fc4b5a13e0833d306d472a0a7633f6b838f86)

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

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 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]	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 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]	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_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.

◆ 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]	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 2040 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);

rb_define_method

void rb_define_method(VALUE klass, const char *name, VALUE(*func)(ANYARGS), int argc)

Defines a method.

Definition: class.c:2142

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.

◆ 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 2877 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 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]	klass	The class in question.
[in]	mid	The method name in question.

Return values

1	It is.
0	It 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]	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 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]	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 2284 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 2318 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 2215 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 2245 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 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]	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 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]	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 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]	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 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

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 1862 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 1876 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 1286 of file vm_method.c.

(ff5fc4b5a13e0833d306d472a0a7633f6b838f86)

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ HAVE_RB_DEFINE_ALLOC_FUNC

Typedef Documentation

◆ rb_alloc_func_t

Function Documentation

◆ rb_alias()

◆ rb_apply()

◆ rb_attr()

◆ rb_backtrace()

◆ rb_check_funcall()

◆ rb_check_funcall_kw()

◆ rb_clear_constant_cache_for_id()

◆ rb_define_alloc_func()

◆ rb_eval_cmd_kw()

◆ rb_f_notimplement()

◆ rb_frame_method_id_and_class()

◆ rb_get_alloc_func()

◆ rb_make_backtrace()

◆ rb_method_basic_definition_p()

◆ rb_method_boundp()

◆ rb_mod_module_eval()

◆ rb_mod_module_exec()

◆ rb_obj_instance_eval()

◆ rb_obj_instance_exec()

◆ rb_obj_respond_to()

◆ rb_remove_method()

◆ rb_remove_method_id()

◆ rb_respond_to()

◆ rb_sourcefile()

◆ rb_sourceline()

◆ rb_undef_alloc_func()