§tiro/vm.h

Functions and type definitions for working with the tiro virtual machine.

§Classes

§Types

§Functions

§Types Documentation

§typedef tiro_vm_settings_t

typedef struct tiro_vm_settings tiro_vm_settings_t;

The tiro_vm_settings structure can be provided to tiro_vm_new as a configuration parameter.

Use tiro_vm_settings_init to initialize this struct to default values.

§Functions Documentation

§function tiro_vm_settings_init

void tiro_vm_settings_init(
    tiro_vm_settings_t * settings
)

Initializes the given tiro settings object with default values.

§function tiro_vm_new

tiro_vm_t tiro_vm_new(
    const tiro_vm_settings_t * settings,
    tiro_error_t * err
)

Allocates a new virtual machine instance.

Reads settings from the given settings objects, if it is not NULL. Otherwise uses default values.

Returns NULL on allocation failure.

§function tiro_vm_free

void tiro_vm_free(
    tiro_vm_t vm
)

Free a virtual machine.

Must be called exactly once for every vm created with tiro_vm_new.

Does nothing if vm is NULL.

§function tiro_vm_userdata

void * tiro_vm_userdata(
    tiro_vm_t vm
)

Returns the userdata pointer that was passed in the settings struct during vm construction.

§function tiro_vm_page_size

size_t tiro_vm_page_size(
    tiro_vm_t vm
)

Returns the vm's page size (in bytes).

§function tiro_vm_max_heap_size

size_t tiro_vm_max_heap_size(
    tiro_vm_t vm
)

Returns the vm's maximum heap size (in bytes).

§function tiro_vm_load_std

void tiro_vm_load_std(
    tiro_vm_t vm,
    tiro_error_t * err
)

Load the default modules provided by the runtime.

TODO: Configuration?

§function tiro_vm_load_bytecode

void tiro_vm_load_bytecode(
    tiro_vm_t vm,
    tiro_module_t module,
    tiro_error_t * err
)

Loads the compiled module into the virtual machine.

Note: this function does not take ownership of the module parameter.

§function tiro_vm_load_module

void tiro_vm_load_module(
    tiro_vm_t vm,
    tiro_handle_t module,
    tiro_error_t * err
)

Loads the given module object into the virtual machine.

Returns TIRO_ERROR_MODULE_EXISTS if a module with the same name already exists. Returns TIRO_ERROR_BAD_TYPE if the argument is not actually a module.

§function tiro_vm_get_export

void tiro_vm_get_export(
    tiro_vm_t vm,
    tiro_string_t module_name,
    tiro_string_t export_name,
    tiro_handle_t result,
    tiro_error_t * err
)

Attempts to find the exported value with the given name in the specified module.

The found value will be stored in the result handle, which must not be NULL.

Returns TIRO_ERROR_MODULE_NOT_FOUND if the specified module was not loaded. Returns TIRO_ERROR_EXPORT_NOT_FOUND if the module does not contain an exported member with that name.

§function tiro_vm_run_ready

void tiro_vm_run_ready(
    tiro_vm_t vm,
    tiro_error_t * err
)

Runs all ready coroutines.

Returns (and does not block) when all coroutines are either waiting or done.

§function tiro_vm_has_ready

bool tiro_vm_has_ready(
    tiro_vm_t vm
)

Returns true if the virtual machine has at least one coroutine ready for execution, false otherwise.

§function tiro_global_new

tiro_handle_t tiro_global_new(
    tiro_vm_t vm,
    tiro_error_t * err
)

Allocates a new global handle.

Global handles point to a single rooted object slot that can hold an arbitrary value. Slots are always initialized to null.

When a global handle is no longer required, it should be freed by calling tiro_global_free.

Returns NULL on allocation failure.

§function tiro_global_free

void tiro_global_free(
    tiro_vm_t vm,
    tiro_handle_t global
)

Frees a global handle allocated with tiro_global_new.

Note: remaining globals are automatically freed when a vm is freed.

Updated on 2022-02-27 at 21:17:13 +0100