CRuby interpreter APIs. More...

Collaboration diagram for CRuby Embedding APIs:

Modules
	ruby(1) implementation
	A part of the implementation of ruby(1) command.

Functions
void	ruby_init_stack (void *addr)
	Set stack bottom of Ruby implementation. More...

int	ruby_setup (void)
	Initializes the VM and builtin libraries. More...

int	ruby_cleanup (int ex)
	Destructs the VM. More...

void	ruby_finalize (void)
	Runs the VM finalization processes. More...

void	ruby_stop (int)
	Calls ruby_cleanup() and exits the process. More...

int	ruby_stack_check (void)
	Checks for stack overflow. More...

size_t	ruby_stack_length (VALUE **topnotch)
	Queries what Ruby thinks is the machine stack. More...

int	ruby_exec_node (void *n)
	Identical to ruby_run_node(), except it returns an opaque execution status. More...

void	ruby_script (const char *name)
	Sets the current script name to this value. More...

void	ruby_set_script_name (VALUE name)
	Identical to ruby_script(), except it takes the name as a Ruby String instance. More...

void	ruby_prog_init (void)
	Defines built-in variables. More...

void	ruby_set_argv (int argc, char **argv)
	Sets argv that ruby understands. More...

void *	ruby_process_options (int argc, char **argv)
	Identical to ruby_options(), except it raises ruby-level exceptions on failure. More...

void	ruby_init_loadpath (void)
	Sets up `$LOAD_PATH`. More...

void	ruby_incpush (const char *path)
	Appends the given path to the end of the load path. More...

void	ruby_sig_finalize (void)
	Clear signal handlers. More...

Detailed Description

CRuby interpreter APIs.

These are APIs to embed MRI interpreter into your program. These functions are not a part of Ruby extension library API. Extension libraries of Ruby should not depend on these functions.

Function Documentation

◆ ruby_cleanup()

int ruby_cleanup ( int ex )

Destructs the VM.

Runs the VM finalization processes as well as ruby_finalize(), and frees resources used by the VM.

Parameters

[in] ex Default value to the return value.

Return values

EXIT_FAILURE	An error occurred.
ex	Successful cleanup.

Note: This function does not raise any exception.

Definition at line 176 of file eval.c.

Referenced by ruby_stop().

◆ ruby_exec_node()

int ruby_exec_node ( void * n )

Identical to ruby_run_node(), except it returns an opaque execution status.

You can pass it to rb_cleanup().

Parameters

[in] n Opaque "node" pointer.

Return values

0	Successful end-of-execution.
otherwise	An error occurred.

Definition at line 323 of file eval.c.

◆ ruby_finalize()

void ruby_finalize ( void )

Runs the VM finalization processes.

END{} and procs registered by Kernel.#at_exit are executed here. See the Ruby language spec for more details.

Note: This function is allowed to raise an exception if an error occurred.

Definition at line 168 of file eval.c.

◆ ruby_incpush()

void ruby_incpush ( const char * path )

Appends the given path to the end of the load path.

Precondition: ruby_init_loadpath() must be done beforehand.

Parameters

[in] path The path you want to push to the load path.

Definition at line 511 of file ruby.c.

◆ ruby_init_loadpath()

void ruby_init_loadpath ( void )

Sets up $LOAD_PATH.

Definition at line 670 of file ruby.c.

◆ ruby_init_stack()

void ruby_init_stack ( void * addr )

Set stack bottom of Ruby implementation.

You must call this function before any heap allocation by Ruby implementation. Or GC will break living objects.

Parameters

[in] addr A pointer somewhere on the stack, near its bottom.

Definition at line 4315 of file vm.c.

◆ ruby_process_options()

void* ruby_process_options	(	int	argc,
		char **	argv
	)

Identical to ruby_options(), except it raises ruby-level exceptions on failure.

Parameters

[in]	argc	Process main's `argc`.
[in]	argv	Process main's `argv`.

Returns: An opaque "node" pointer.

Definition at line 3151 of file ruby.c.

Referenced by ruby_options().

◆ ruby_prog_init()

void ruby_prog_init ( void )

Defines built-in variables.

Definition at line 3104 of file ruby.c.

Referenced by ruby_setup().

◆ ruby_script()

void ruby_script ( const char * name )

Sets the current script name to this value.

This is similar to $0 = name in Ruby level but also affects Method#location and others.

Parameters

[in] name File name to set.

Definition at line 3023 of file ruby.c.

◆ ruby_set_argv()

void ruby_set_argv	(	int	argc,
		char **	argv
	)

Sets argv that ruby understands.

Your program might have its own command line parameters etc. Handle them as you wish, and pass remaining parts of argv here.

Parameters

[in]	argc	Number of elements of `argv`.
[in]	argv	Command line arguments.

Definition at line 3136 of file ruby.c.

◆ ruby_set_script_name()

void ruby_set_script_name ( VALUE name )

Identical to ruby_script(), except it takes the name as a Ruby String instance.

Parameters

[in] name File name to set.

Identical to ruby_script(), except it takes the name as a Ruby String instance.

Same as ruby_script() but accepts a VALUE.

Definition at line 3035 of file ruby.c.

◆ ruby_setup()

int ruby_setup ( void )

Initializes the VM and builtin libraries.

Return values

0	Initialization succeeded.
otherwise	An error occurred.

Definition at line 66 of file eval.c.

Referenced by ruby_init().

◆ ruby_sig_finalize()

void ruby_sig_finalize ( void )

Clear signal handlers.

Ruby installs its own signal handler (apart from those which user scripts set). This is to clear that. Must be called when the ruby part terminates, before switching to your program's own logic.

Definition at line 1442 of file signal.c.

◆ ruby_stack_check()

int ruby_stack_check ( void )

Checks for stack overflow.

Return values

true	NG machine stack is about to overflow.
false	OK there still is a room in the stack.

Definition at line 2158 of file gc.c.

◆ ruby_stack_length()

size_t ruby_stack_length ( VALUE ** topnotch )

Queries what Ruby thinks is the machine stack.

Ruby manages a region of memory. It calls that area the "machine stack". By calling this function, in spite of its name, you can obtain both one end of the stack and its length at once. Which means you can know the entire region.

Parameters

[out] topnotch On return the pointer points to the upmost address of the macihne stack that Ruby knows.

Returns: Length of the machine stack that Ruby knows.

Definition at line 2118 of file gc.c.

◆ ruby_stop()

void ruby_stop ( int ex )

Calls ruby_cleanup() and exits the process.

Definition at line 288 of file eval.c.

Referenced by rb_exit().

Modules

Functions

Detailed Description

Function Documentation

◆ ruby_cleanup()

◆ ruby_exec_node()

◆ ruby_finalize()

◆ ruby_incpush()

◆ ruby_init_loadpath()

◆ ruby_init_stack()

◆ ruby_process_options()

◆ ruby_prog_init()

◆ ruby_script()

◆ ruby_set_argv()

◆ ruby_set_script_name()

◆ ruby_setup()

◆ ruby_sig_finalize()

◆ ruby_stack_check()

◆ ruby_stack_length()

◆ ruby_stop()