C Level API

ruby_vm_t *ruby_vm_new(int argc, char *argv[])

Create VM with option specified by argc, argv. argc, argv is treated as arguments which passed by main().

This functiuon returns new virttual machine pointer of ruby_vm_t. If errors are occurred, zero will be returned.

int ruby_vm_run(ruby_vm_t *vm)

Kick and start VM in current thread. This function blocks current execution while that VM is running.

This function returns zero.

int ruby_vm_start(ruby_vm_t *vm)

Start VM in the other thread. VM will run concurrently in other thread. In other words, created VM run in parallel if machine has multi core processors or such a parallel computation units.

int ruby_vm_join(ruby_vm_t *vm)

Wait VM termination. This function is used to synchronise with VM execution.

The model of this function is pthread_join() in POSIX Thread library.

int ruby_vm_destruct(ruby_vm_t *vm)

Destruct and release VM resources. This function returns 0.

int ruby_vm_init_add_argv(ruby_vm_t *vm, const char *arg)

Add an extra argument which is treated by ARGV in Ruby level.

This function returns zero if succeed. This function should be called before ruby_vm_run() or ruby_vm_start(). Calling it after that, maybe ignored and return non-zero value.

int ruby_vm_init_add_library(ruby_vm_t *vm, const char *lib)

Add a library which should be loaded at start up ("-r lib").

This function returns zero if succeed. This function should be called before ruby_vm_run() or ruby_vm_start(). Calling it after that, maybe ignored and return non-zero value.

int ruby_vm_init_add_library_path(ruby_vm_t *vm, const char *path)

Add a library laod path ("-I lib/").

This function returns zero if succeed. This function should be called before ruby_vm_run() or ruby_vm_start(). Calling it after that, maybe ignored and return non-zero value.

int ruby_vm_init_add_expression(ruby_vm_t *vm, const char *expr)

Add an expression which should be evaluated ("-e expr"). You can specify several expression with this function and expressions are evaluated sequentially.

This function returns zero if succeed. This function should be called before ruby_vm_run() or ruby_vm_start(). Calling it after that, maybe ignored and return non-zero value.

int ruby_vm_init_script(ruby_vm_t *vm, const char *script)

Specify running script which should be loaded and evaluated at startup time. If you call this function several time, last specification is remained.

This function returns zero if succeed. This function should be called before ruby_vm_run() or ruby_vm_start(). Calling it after that, maybe ignored and return non-zero value.

int ruby_vm_init_verbose(ruby_vm_t *vm, int verbose_p)

Specify verbose option ("-v"). Non-zero means specify "-v" and zero means run without "-v".

This function returns zero if succeed. This function should be called before ruby_vm_run() or ruby_vm_start(). Calling it after that, maybe ignored and return non-zero value.

(Should we allow this function to call after starting the VM?)

int ruby_vm_init_debug(ruby_vm_t *vm, int debug)

Specify debug option ("-d"). Non-zero means specify "-d" and zero means run without "-d".

This function returns zero if succeed. This function should be called before ruby_vm_run() or ruby_vm_start(). Calling it after that, maybe ignored and return non-zero value.

(Should we allow this function to call after starting the VM?)

int ruby_vm_init_warn(ruby_vm_t *vm, int warn)

Specify warning level ("-w or -W[level]").

The "warn" parameter specify warning level.

• 0: silent
• 1: medium
• 2: verbose ( -w)

This function returns zero if succeed. This function should be called before ruby_vm_run() or ruby_vm_start(). Calling it after that, maybe ignored and return non-zero value.

(Should we allow this function to call after starting the VM?)

int ruby_vm_init_add_initializer(ruby_vm_t *vm, void (*initializer)(void))

Register initialize function "initializer". "initializer" function will be called at startup time.

This function returns zero if succeed. This function should be called before ruby_vm_run() or ruby_vm_start(). Calling it after that, maybe ignored and return non-zero value.

:int ruby_vm_init_stdin(ruby_vm_t *vm, int fd)

Specify file descriptor (fd) of stdin. No smae specify mechanism are available before MVM extension.

This function returns zero if succeed. This function should be called before ruby_vm_run() or ruby_vm_start(). Calling it after that, maybe ignored and return non-zero value.

int ruby_vm_init_stdout(ruby_vm_t *vm, int fd)

Specify file descriptor (fd) of stdout. No smae specify mechanism are available before MVM extension.

This function returns zero if succeed. This function should be called before ruby_vm_run() or ruby_vm_start(). Calling it after that, maybe ignored and return non-zero value.

int ruby_vm_init_stderr(ruby_vm_t *vm, int fd)

Specify file descriptor (fd) of stderr. No smae specify mechanism are available before MVM extension.

This function returns zero if succeed. This function should be called before ruby_vm_run() or ruby_vm_start(). Calling it after that, maybe ignored and return non-zero value.

Note: VM starting process

Following shows VM startup process.

1. make VM instance with ruby_vm_new()
2. initialize created VM with ruby_vm_init_*()
3. kick VM by ruby_vm_run() or ruby_vm_start()
1. run core initializer.
2. run special initializer specified by ruby_vm_init_add_initializer().
3. load libraries specified by "-r".
4. evaluate strings by "-e".
5. evaluate script file.
4. terminate VM and release their resources.

Note: API satisfaction

Some initializers are lacked for example Encoding related options. However, we can specify any arguments which are accepted by current Ruby interpreter can recognize by specifying argument on ruby_vm_new().

void ruby_vm_foreach(int (*func)(ruby_vm_t *, void *), void *param)

Iterate all VMs with function "func" with parameter "param". If "func" returns 0, iteration will be stoped.

Not yet.