Ruby: CRuby Embedding APIs

Ruby 3.0.5p211 (2022-11-24 revision ba5cf0f7c52d4d35cc6a173c89eda98ceffa2dcf)

Modules | Functions
CRuby Embedding APIs

CRuby interpreter APIs. More...

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

## Functions
void | ruby_init_stack (volatile VALUE *)
int | ruby_setup (void)
| Initializes the VM and builtin libraries. More...
int | ruby_cleanup (volatile int)
| 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)
size_t | ruby_stack_length (VALUE **)
int | ruby_exec_node (void *n)
| Runs the given compiled source. More...
void | ruby_script (const char *name)
| Sets the current script name to this value. More...
void | ruby_set_script_name (VALUE name)
| Sets the current script name to this value. More...
void | ruby_prog_init (void)
| Defines built-in variables. More...
void | ruby_set_argv (int, char **)
void * | ruby_process_options (int, char **)
void | ruby_init_loadpath (void)
void | ruby_incpush (const char *)
void | ruby_sig_finalize (void)

## 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 | ( | volatile int | ex | ) |

Destructs the VM.

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

Parameters

  ex | Default value to the return value.

Returns
  If an error occurred returns a non-zero. If otherwise, returns the given ex.

Note
  This function does not raise any exception.

Definition at line 213 of file eval.c.

Referenced by ruby_stop().

## ◆ ruby_exec_node()

int ruby_exec_node | ( | void * | n | ) |

Runs the given compiled source.

Definition at line 380 of file eval.c.

References ruby_init_stack().

## ◆ 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 195 of file eval.c.

## ◆ ruby_incpush()

void ruby_incpush | ( | const char * | path | ) |

Definition at line 456 of file ruby.c.

References ruby_push_include().

## ◆ ruby_init_loadpath()

void ruby_init_loadpath | ( | void |  | ) |

Definition at line 616 of file ruby.c.

References getenv(), INITIAL_LOAD_PATH_MARK, len, NULL, OBJ_FREEZE_RAW, PREFIX_PATH, rb_ary_push(), rb_ascii8bit_encoding(), rb_cObject, rb_const_set(), rb_enc_path_last_separator(), rb_gc_register_address(), rb_ivar_set(), rb_str_cat_cstr, rb_str_resize(), rb_str_subseq(), rb_strlen_lit, RSTRING_PTR, ruby_archlibdir_path, ruby_exec_prefix, ruby_initial_load_paths, ruby_prefix_path, ruby_push_include(), RUBY_RELATIVE, strlen(), STRNCASECMP, and strrchr().

## ◆ ruby_init_stack()

void ruby_init_stack | ( | volatile VALUE * |  | ) |

Referenced by ruby_exec_node(), ruby_options(), ruby_run_node(), and ruby_setup().

## ◆ ruby_process_options()

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

Definition at line 2595 of file ruby.c.

References argc, argv, load_file_arg::opt, rb_argv0, rb_gc_register_mark_object(), rb_progname, rb_str_new4, ruby_engine, ruby_init_setproctitle(), and ruby_script().

Referenced by ruby_options().

## ◆ ruby_prog_init()

void ruby_prog_init | ( | void |  | ) |

Defines built-in variables.

Definition at line 2542 of file ruby.c.

References rb_argv, rb_define_global_const(), ruby::backward::cxxanyargs::rb_define_hooked_variable(), rb_define_module_function, ruby::backward::cxxanyargs::rb_define_virtual_variable(), rb_gvar_ractor_local(), rb_gvar_readonly_setter, rb_mProcess, and rb_progname.

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.

Definition at line 2458 of file ruby.c.

References name, rb_orig_progname, rb_progname, and rb_vm_set_progname().

Referenced by ruby_process_options().

## ◆ ruby_set_argv()

void ruby_set_argv | ( | int | argc,
|  | char ** | argv
| ) |  |

Definition at line 2574 of file ruby.c.

References argc, argv, OBJ_FREEZE, rb_argv, rb_ary_clear(), and rb_ary_push().

## ◆ ruby_set_script_name()

void ruby_set_script_name | ( | VALUE | name | ) |

Sets the current script name to this value.

Same as ruby_script() but accepts a VALUE.

Definition at line 2471 of file ruby.c.

References name, rb_orig_progname, rb_progname, rb_str_dup(), and rb_vm_set_progname().

Referenced by Init_version().

## ◆ ruby_setup()

int ruby_setup | ( | void |  | ) |

Initializes the VM and builtin libraries.

Return values

  0 | if succeeded.
  non-zero | an error occurred.

Definition at line 70 of file eval.c.

References EC_EXEC_TAG, EC_POP_TAG, EC_PUSH_TAG, Init_BareVM(), Init_heap(), Init_vm_objects(), rb_call_inits(), rb_vm_encoded_insn_data_table_init(), ruby_init_stack(), ruby_prog_init(), and TAG_NONE.

Referenced by ruby_init().

## ◆ ruby_sig_finalize()

void ruby_sig_finalize | ( | void |  | ) |

Definition at line 1496 of file signal.c.

References ruby_signal, sighandler_t, and SIGINT.

## ◆ ruby_stack_check()

int ruby_stack_check | ( | void |  | ) |

Definition at line 5552 of file gc.c.

References stack_check, and STACKFRAME_FOR_CALL_CFUNC.

## ◆ ruby_stack_length()

size_t ruby_stack_length | ( | VALUE ** | p | ) |

Definition at line 5512 of file gc.c.

References SET_STACK_END, STACK_END, STACK_LENGTH, STACK_START, and STACK_UPPER.

## ◆ ruby_stop()

void ruby_stop | ( | int | ex | ) |

Calls ruby_cleanup() and exits the process.

Definition at line 327 of file eval.c.

References ruby_cleanup().

Referenced by rb_exit().