§tiro

§Namespaces

Name
tiro::detail

§Classes

	Name
class	tiro::api_error Represents an error thrown by the tiro c library.
class	tiro::array Refers to an array value.
class	tiro::async_frame Represents the call frame of a asynchronous function call.
class	tiro::async_token A token that can be used to resume a yielding coroutine.
class	tiro::bad_handle_cast Thrown when an invalid cast is attempted.
class	tiro::bad_handle_check Thrown when a debug mode handle check failed.
class	tiro::boolean Refers to a boolean value (true or false).
class	tiro::compiled_module Represents a compiled bytecode module.
class	tiro::compiler Translates a set of source files into a module.
struct	tiro::compiler_message Represents a diagnostic message emitted by the compiler.
struct	tiro::compiler_settings An instance of this type can be passed to the compiler to configure it.
class	tiro::coroutine Refers to a coroutine.
class	tiro::error Base class for all errors thrown by this library.
class	tiro::error_adapter Error adapter class for the tiroerror_t* argument expected by most tiro* functions.
class	tiro::exception Refers to an exception.
class	tiro::float_ Refers to a float value.
class	tiro::function Refers to a function value.
class	tiro::generic_error Generic error with a simple message.
class	tiro::handle A handle represents a reference to an object.
class	tiro::integer Refers to an integer value.
class	tiro::module Refers to a module.
class	tiro::native Refers to a native object.
class	tiro::native_type
class	tiro::null Refers to a null value.
class	tiro::record Refers to a record value.
class	tiro::record_schema Refers to a record schema.
class	tiro::result Refers to a result value.
class	tiro::resumable_frame Represents the call frame of a resumable function call.
class	tiro::string Refers to a string value.
class	tiro::sync_frame Represents the call frame of a synchronous function call.
class	tiro::tuple Refers to a tuple value.
class	tiro::type Refers to a type.
struct	tiro::version Represents a library version.
class	tiro::vm
struct	tiro::vm_settings Settings to control the construction of a virtual machine.

§Types

	Name
enum class int	severity { warning = TIRO_SEVERITY_WARNING, error = TIRO_SEVERITY_ERROR} Defines the possible values for the severity of diagnostic compiler messages.
enum class int	api_errc { ok = TIRO_OK, bad_state = TIRO_ERROR_BAD_STATE, bad_arg = TIRO_ERROR_BAD_ARG, bad_source = TIRO_ERROR_BAD_SOURCE, bad_type = TIRO_ERROR_BAD_TYPE, bad_key = TIRO_ERROR_BAD_KEY, module_exists = TIRO_ERROR_MODULE_EXISTS, module_not_found = TIRO_ERROR_MODULE_NOT_FOUND, export_not_found = TIRO_ERROR_EXPORT_NOT_FOUND, out_of_bounds = TIRO_ERROR_OUT_OF_BOUNDS, alloc = TIRO_ERROR_ALLOC, internal = TIRO_ERROR_INTERNAL} Defines all possible error codes.
enum class int	value_kind { null = TIROKIND_NULL, boolean = TIRO_KIND_BOOLEAN, integer = TIRO_KIND_INTEGER, float = TIRO_KIND_FLOAT, string = TIRO_KIND_STRING, function = TIRO_KIND_FUNCTION, tuple = TIRO_KIND_TUPLE, record = TIRO_KIND_RECORD, record_schema = TIRO_KIND_RECORD_SCHEMA, array = TIRO_KIND_ARRAY, result = TIRO_KIND_RESULT, exception = TIRO_KIND_EXCEPTION, coroutine = TIRO_KIND_COROUTINE, module = TIRO_KIND_MODULE, type = TIRO_KIND_TYPE, native = TIRO_KIND_NATIVE, internal = TIRO_KIND_INTERNAL, invalid = TIRO_KIND_INVALID} Represents the kind of a value.

§Functions

	Name
const char *	to_string(severity s) Returns the string representation of the given severity value.
const char *	name(api_errc e) Returns the name of the given error code.
const char *	message(api_errc e) Returns the human readable message associated with the error code.
template <auto Function> function	make_sync_function(vm & v, const string & name, size_t argc, const handle & closure) Constructs a new function object with the given name that will invoke the native function when called.
template <auto Function> function	make_async_function(vm & v, const string & name, size_t argc, const handle & closure) Constructs a new function object with the given name that will invoke the native function when called.
template <auto Function> function	make_resumable_function(vm & v, const string & name, size_t argc, size_t locals, const handle & closure) Creates a new resumable function with the given parameters.
const char *	to_string(value_kind k) Returns the string representation of the given value kind.
handle	make_copy(vm & v, tiro_handle_t value) Constructs a new handle as a copy of the given value.
bool	same(vm & v, const handle & a, const handle & b) Returns true if and only if `a` and `b` refer to the same value.
null	make_null(vm & v) Constructs a new handle, initialized to null.
boolean	make_boolean(vm & v, bool value) Constructs a new boolean value.
integer	make_integer(vm & v, int64_t value) Constructs a new integer value.
float_	make_float(vm & v, double value) Constructs a new float value.
string	make_string(vm & v, std::string_view value) Constructs a new string value.
tuple	make_tuple(vm & v, size_t size) Constructs a new tuple value with the given size.
record_schema	make_record_schema(vm & v, const array & keys) Creates a new record schema from the given array of keys.
record	make_record(vm & v, const record_schema & schema) Constructs a new record with the property names specified by the given schema.
array	make_array(vm & v, size_t initial_capacity =0) Constructs a new array with the given initial capacity. The array will be empty.
result	make_success(vm & v, const handle & value) Creates a new successful result with the given value.
result	make_error(vm & v, const handle & err) Creates a new error result with the given error value.
coroutine	make_coroutine(vm & v, const function & func, const handle & arguments) Constructs a new coroutine value.
coroutine	make_coroutine(vm & v, const function & func) Constructs a new coroutine value.
module	make_module(vm & v, std::string_view name, const std::vector< std::pair< std::string, handle >> & exports) Creates a new module with the given name and exports.
handle	get_export(const vm & v, std::string_view module_name, std::string_view export_name) Attempts to find an exported value called `export_name` in the module `module_name`.
void	load_module(const vm & v, const module & m) Attempts to load the given module into the virtual machine.
template <typename Callback > void	run_async(vm & v, const function & func, Callback && cb) Schedules execution of `func` in a new coroutine without any arguments.
template <typename Callback > void	run_async(vm & v, const function & func, const handle & args, Callback && cb) Schedules execution of `func` in a new coroutine, with the provided arguments.
constexpr version	compile_time_version() Returns the compile time version of the tiro library, i.e.
version	runtime_version() Returns the runtime version of the tiro library, i.e.

§Types Documentation

§enum severity

Enumerator	Value	Description
warning	TIRO_SEVERITY_WARNING
error	TIRO_SEVERITY_ERROR

Defines the possible values for the severity of diagnostic compiler messages.

§enum api_errc

Enumerator	Value	Description
ok	TIRO_OK	Success.
bad_state	TIRO_ERROR_BAD_STATE	Instance is not in the correct state.
bad_arg	TIRO_ERROR_BAD_ARG	Invalid argument.
bad_source	TIRO_ERROR_BAD_SOURCE	Invalid source code.
bad_type	TIRO_ERROR_BAD_TYPE	Operation not supported on type.
bad_key	TIRO_ERROR_BAD_KEY	Key does not exist on object.
module_exists	TIRO_ERROR_MODULE_EXISTS	Module name defined more than once.
module_not_found	TIRO_ERROR_MODULE_NOT_FOUND	Requested module does not exist.
export_not_found	TIRO_ERROR_EXPORT_NOT_FOUND	Requested export does not exist.
out_of_bounds	TIRO_ERROR_OUT_OF_BOUNDS	Argument was out of bounds.
alloc	TIRO_ERROR_ALLOC	Allocation failure.
internal	TIRO_ERROR_INTERNAL	Internal error.

Defines all possible error codes.

§enum value_kind

Enumerator	Value	Description
null	TIRO_KIND_NULL	Value is null.
boolean	TIRO_KIND_BOOLEAN	Value is true or false.
integer	TIRO_KIND_INTEGER	Value is an integer.
float_	TIRO_KIND_FLOAT	Value is a floating point number.
string	TIRO_KIND_STRING	Value is a string.
function	TIRO_KIND_FUNCTION	Value is a function.
tuple	TIRO_KIND_TUPLE	Value is a tuple.
record	TIRO_KIND_RECORD	Value is a record.
record_schema	TIRO_KIND_RECORD_SCHEMA	Value is a record schema.
array	TIRO_KIND_ARRAY	Value is an array.
result	TIRO_KIND_RESULT	Value is a result.
exception	TIRO_KIND_EXCEPTION	Value is an exception.
coroutine	TIRO_KIND_COROUTINE	Value is a coroutine.
module	TIRO_KIND_MODULE	Value is a module.
type	TIRO_KIND_TYPE	Value is a type.
native	TIRO_KIND_NATIVE	Value is a native object.
internal	TIRO_KIND_INTERNAL	Value is some other, internal type.
invalid	TIRO_KIND_INVALID	Invalid value (e.g. null handle)

Represents the kind of a value.

§Functions Documentation

§function to_string

inline const char * to_string(
    severity s
)

Returns the string representation of the given severity value.

The returned string is allocated in static storage.

§function name

inline const char * name(
    api_errc e
)

Returns the name of the given error code.

The returned string is allocated in static storage.

§function message

inline const char * message(
    api_errc e
)

Returns the human readable message associated with the error code.

The returned string is allocated in static storage.

§function make_sync_function

template <auto Function>
function make_sync_function(
    vm & v,
    const string & name,
    size_t argc,
    const handle & closure
)

Constructs a new function object with the given name that will invoke the native function when called.

argc is the number of arguments required for calling Function. closure may be an arbitrary value that will be passed to the function on every invocation.

Synchronous functions are appropriate for simple, nonblocking operations. Use asynchronous functions for long running operations (such as network I/O) instead.

Function will receive two arguments when invoked:

A reference to the vm (vm&).
A reference to the call frame ([sync_frame](/docs/api/classes/classtiro_1_1sync__frame)&). Use this reference to access call arguments. Both references may only be used during the function call. The function should return its return value as a handle.

§function make_async_function

template <auto Function>
function make_async_function(
    vm & v,
    const string & name,
    size_t argc,
    const handle & closure
)

Constructs a new function object with the given name that will invoke the native function when called.

argc is the number of arguments required for calling Function. closure may be an arbitrary value that will be passed to the function on every invocation.

Function will receive two arguments when invoked:

A reference to the vm (vm&).
A call frame value ([async_frame](/docs/api/classes/classtiro_1_1async__frame)). Use this value to access call arguments and to set the return value.

§function make_resumable_function

template <auto Function>
function make_resumable_function(
    vm & v,
    const string & name,
    size_t argc,
    size_t locals,
    const handle & closure
)

Creates a new resumable function with the given parameters.

§function to_string

inline const char * to_string(
    value_kind k
)

Returns the string representation of the given value kind.

The returned string is allocated in static storage.

§function make_copy

inline handle make_copy(
    vm & v,
    tiro_handle_t value
)

Constructs a new handle as a copy of the given value.

§function same

inline bool same(
    vm & v,
    const handle & a,
    const handle & b
)

Returns true if and only if a and b refer to the same value.

§function make_null

inline null make_null(
    vm & v
)

Constructs a new handle, initialized to null.

§function make_boolean

inline boolean make_boolean(
    vm & v,
    bool value
)

Constructs a new boolean value.

§function make_integer

inline integer make_integer(
    vm & v,
    int64_t value
)

Constructs a new integer value.

§function make_float

inline float_ make_float(
    vm & v,
    double value
)

Constructs a new float value.

§function make_string

inline string make_string(
    vm & v,
    std::string_view value
)

Constructs a new string value.

§function make_tuple

inline tuple make_tuple(
    vm & v,
    size_t size
)

Constructs a new tuple value with the given size.

All elements of that tuple will be initialized to null.

§function make_record_schema

inline record_schema make_record_schema(
    vm & v,
    const array & keys
)

Creates a new record schema from the given array of keys.

All keys must be strings.

§function make_record

inline record make_record(
    vm & v,
    const record_schema & schema
)

Constructs a new record with the property names specified by the given schema.

All values of the record will be initialized to null.

§function make_array

inline array make_array(
    vm & v,
    size_t initial_capacity =0
)

Constructs a new array with the given initial capacity. The array will be empty.

§function make_success

inline result make_success(
    vm & v,
    const handle & value
)

Creates a new successful result with the given value.

§function make_error

inline result make_error(
    vm & v,
    const handle & err
)

Creates a new error result with the given error value.

§function make_coroutine

inline coroutine make_coroutine(
    vm & v,
    const function & func,
    const handle & arguments
)

Constructs a new coroutine value.

The coroutine will call the given function with the provided arguments, once it has been started.

§function make_coroutine

inline coroutine make_coroutine(
    vm & v,
    const function & func
)

Constructs a new coroutine value.

The coroutine will call the given function without any arguments, once it has been started.

§function make_module

inline module make_module(
    vm & v,
    std::string_view name,
    const std::vector< std::pair< std::string, handle >> & exports
)

Creates a new module with the given name and exports.

§function get_export

inline handle get_export(
    const vm & v,
    std::string_view module_name,
    std::string_view export_name
)

Attempts to find an exported value called export_name in the module module_name.

§function load_module

inline void load_module(
    const vm & v,
    const module & m
)

Attempts to load the given module into the virtual machine.

§function run_async

template <typename Callback >
inline void run_async(
    vm & v,
    const function & func,
    Callback && cb
)

Schedules execution of func in a new coroutine without any arguments.

The callback cb will be called once func has completed its execution. Note that func will not be executed from within this function (the next call to [vm.run_ready()](/docs/api/classes/classtiro_1_1vm#function-run-ready) will do that). TODO: Extract the result() from the coroutine and pass it directly to the callback.

§function run_async

template <typename Callback >
inline void run_async(
    vm & v,
    const function & func,
    const handle & args,
    Callback && cb
)

Schedules execution of func in a new coroutine, with the provided arguments.

§function compile_time_version

inline constexpr version compile_time_version()

Returns the compile time version of the tiro library, i.e.

the version the application was built against.

§function runtime_version

inline version runtime_version()

Returns the runtime version of the tiro library, i.e.

the version the application is currently running against.

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