Runtime API reference

wren::api+x86_64 +linux

api: async runtime and standard library for Wren

This module implements an async runtime and provides a basic "standard" library for Wren.

To use it, initialize your VM with default_config (or a derivative thereof), or directly make use of load_module, bind_foreign_method, and bind_foreign_class.

The user must use destroy prior to calling wren::destroy to ensure that resources held by the API implementation are released.

Index

Types

type config;

// Undocumented types:
type runtime;
type scheduler;

Constants

def RETURN_SLOT: int = 2;

// Undocumented constants:
def WREN_STDLIB_DIR: str = "/usr/local/src/wren/stdlib";
def WREN_THIRDPARTY_DIR: str = "/usr/local/src/wren/third-party";

Globals

let default_config;

Functions

fn bind_foreign_class(vm: *wren::vm, module: str, class_name: str) wren::foreign_class_methods;
fn bind_foreign_method(vm: *wren::vm, module: str, class_name: str, is_static: bool, signature: str) nullable *wren::foreign_method_fn;
fn destroy(rt: *runtime) void;
fn getuser(rt: *runtime) nullable *opaque;
fn interpret(rt: *runtime, module: str, source: str) (void | wren::error);
fn io_bind_class(vm: *wren::vm, class_name: str) wren::foreign_class_methods;
fn io_bind_method(vm: *wren::vm, class_name: str, is_static: bool, signature: str) nullable *wren::foreign_method_fn;
fn load_module(vm: *wren::vm, name: str) (str | errors::noentry);
fn new(loop: *ev::loop, args: []str, conf: nullable *config = null, user: nullable *opaque = null) (*runtime | nomem | errors::error);
fn os_bind_method(vm: *wren::vm, class_name: str, is_static: bool, signature: str) nullable *wren::foreign_method_fn;
fn run(rt: *runtime) (void | errors::error | wren::error);
fn scheduler_bind_method(vm: *wren::vm, class_name: str, is_static: bool, signature: str) nullable *wren::foreign_method_fn;
fn scheduler_error(vm: *wren::vm, fiber: wren::handle, error: str) void;
fn scheduler_resume(vm: *wren::vm, fiber: wren::handle) void;
fn scheduler_return(vm: *wren::vm, fiber: wren::handle) void;
fn setuser(rt: *runtime, user: nullable *opaque) void;
fn time_bind_method(vm: *wren::vm, class_name: str, is_static: bool, signature: str) nullable *wren::foreign_method_fn;
fn vm(rt: *runtime) *wren::vm;

Types

type config[permalink]

type config = struct {
	wren::config,
	// Paths to search for modules in for imports
	path: []str,
};

wren::api:: configuration.

type runtime[permalink]

Show undocumented member

type runtime = struct {
	loop: *ev::loop,
	args: []str,
	conf: *config,
	user: nullable *opaque,
	vm: *wren::vm,
	err: (wren::error | void),
	sched: scheduler,
};

type scheduler[permalink]

Show undocumented member

type scheduler = struct {
	class: wren::handle,
	resume1: wren::handle,
	resume2: wren::handle,
	resumeError: wren::handle,
};

Constants

def RETURN_SLOT[permalink]

def RETURN_SLOT: int = 2;

Place the argument to be passed to a suspended fiber into this slot with wren::set et al prior to calling scheduler_return.

def WREN_STDLIB_DIR[permalink]

Show undocumented member

def WREN_STDLIB_DIR: str = "/usr/local/src/wren/stdlib";

def WREN_THIRDPARTY_DIR[permalink]

Show undocumented member

def WREN_THIRDPARTY_DIR: str = "/usr/local/src/wren/third-party";

Globals

let default_config[permalink]

let default_config;

Default configuration for wren::api::.

Functions

fn bind_foreign_class[permalink]

fn bind_foreign_class(vm: *wren::vm, module: str, class_name: str) wren::foreign_class_methods;

Implements wren::bind_foreign_class_fn to bind API classes.

fn bind_foreign_method[permalink]

fn bind_foreign_method(vm: *wren::vm, module: str, class_name: str, is_static: bool, signature: str) nullable *wren::foreign_method_fn;

Implements wren::bind_foreign_method_fn to bind API functions.

fn destroy[permalink]

fn destroy(rt: *runtime) void;

Frees resources associated with a runtime.

fn getuser[permalink]

fn getuser(rt: *runtime) nullable *opaque;

Gets the user data pointer associated with a runtime.

fn interpret[permalink]

fn interpret(rt: *runtime, module: str, source: str) (void | wren::error);

Runs arbitrary Wren code on a runtime.

fn io_bind_class[permalink]

fn io_bind_class(vm: *wren::vm, class_name: str) wren::foreign_class_methods;

Binds the "io" module's foreign class interface to the VM.

fn io_bind_method[permalink]

fn io_bind_method(vm: *wren::vm, class_name: str, is_static: bool, signature: str) nullable *wren::foreign_method_fn;

Binds the "io" module's foreign methods to the VM.

fn load_module[permalink]

fn load_module(vm: *wren::vm, name: str) (str | errors::noentry);

Implements wren::load_module_fn to load API modules.

fn new[permalink]

fn new(loop: *ev::loop, args: []str, conf: nullable *config = null, user: nullable *opaque = null) (*runtime | nomem | errors::error);

Initializes a new wren::api:: runtime with the given argument vector (for Process.args. The slice is borrowed from the caller for the lifetime of the VM). Pass the return value to destroy to free resources associated with the runtime when finished.

fn os_bind_method[permalink]

fn os_bind_method(vm: *wren::vm, class_name: str, is_static: bool, signature: str) nullable *wren::foreign_method_fn;

Binds the "os" module's foreign methods to the VM.

fn run[permalink]

fn run(rt: *runtime) (void | errors::error | wren::error);

Runs the Wren runtime until all fibers are completed. This is a thin shim over ev::run.

fn scheduler_bind_method[permalink]

fn scheduler_bind_method(vm: *wren::vm, class_name: str, is_static: bool, signature: str) nullable *wren::foreign_method_fn;

Binds the "scheduler" module's foreign methods to the VM.

fn scheduler_error[permalink]

fn scheduler_error(vm: *wren::vm, fiber: wren::handle, error: str) void;

Resumes a suspended fiber with an error.

fn scheduler_resume[permalink]

fn scheduler_resume(vm: *wren::vm, fiber: wren::handle) void;

Resumes a suspended fiber. Releases the fiber handle.

fn scheduler_return[permalink]

fn scheduler_return(vm: *wren::vm, fiber: wren::handle) void;

Resumes a suspended fiber, passing a value to the resumed fiber via RETURN_SLOT.

fn setuser[permalink]

fn setuser(rt: *runtime, user: nullable *opaque) void;

Sets the user data pointer associated with a runtime.

fn time_bind_method[permalink]

fn time_bind_method(vm: *wren::vm, class_name: str, is_static: bool, signature: str) nullable *wren::foreign_method_fn;

Binds the "time" module's foreign methods to the VM.

fn vm[permalink]

fn vm(rt: *runtime) *wren::vm;

Returns the wren::vm associated with a runtime.

The returned VM's lifetime is bound to the runtime object. Note that wren::api:: utilizes the user data field of the VM object, which is therefore not available to users of wren::api:: -- see setuser and getuser instead.