This guide explains how to embed the Mobius interpreter in a C or C++ application: managing interpreter state, executing scripts, exchanging values through the stack, registering native functions, and handling errors.
Headers:
<mobius/mobius.h>— core embedding API (lifecycle, config, execution, errors, metrics)<mobius/mobius_plugin.h>— the stack API, native functions, value types, refs
Link against libmobius-core. From the repository root after buildy -r
(or the top directory of a release archive), the headers are in include/ and
the library is in bin/:
g++ -Iinclude -o my_app my_app.cpp -Lbin -lmobius-core
LD_LIBRARY_PATH=bin ./my_appIntegers live as
int64in the VM. The stack API offers narrow helpers (pushInt8,asInt32,pushFloat32, …) that convert at the C boundary for convenience, but preferpushInt64/pushUInt64/pushFloat64andasInt64/asUInt64/asFloat64in new code.
- Minimal example
- State lifecycle
- Configuration
- Footprint
- Executing scripts
- The stack
- Exchanging values
- Registering native functions
- Calling Mobius functions from C
- Rooted value handles
- Error handling
- Output and exit
- Files
- Sandboxing
- Built-in modules
- Loading plugins
- Type metatables
- Multiple interpreters
- Concurrency and fibers
- Metrics
#include <mobius/mobius.h>
int main(void) {
MobiusState* state = mobius_new_state(NULL); // NULL = default config
mobius_init_stdlib(state);
mobius_exec_string(state, "print(\"Hello from Mobius!\")");
mobius_free_state(state);
return 0;
}Always call mobius_init_stdlib() after mobius_new_state() — without it,
scripts have no print, typeof, or any built-in functions.
Every program runs inside a MobiusState, an opaque handle that owns the
interpreter, its globals, its stack, and all allocated objects.
MobiusState* state = mobius_new_state(NULL);
MobiusConfig config = mobius_default_config();
config.debug_mode = true;
MobiusState* state = mobius_new_state(&config); // or with config
mobius_init_stdlib(state); // returns MOBIUS_OK on success
// ... use the interpreter ...
mobius_free_state(state); // destroy and free everything| Function | Description |
|---|---|
mobius_default_config() |
A MobiusConfig filled with sensible defaults |
mobius_new_state(config) |
Create an interpreter (NULL for defaults) |
mobius_init_stdlib(state) |
Load the standard library |
mobius_free_state(state) |
Destroy the interpreter |
Get the defaults, change what you need, and pass a pointer to
mobius_new_state(). Configuration is immutable after the state is created.
MobiusConfig config = mobius_default_config();
config.max_worker_threads = 8;
MobiusState* state = mobius_new_state(&config);| Field | Type | Default | Description |
|---|---|---|---|
initial_stack_size |
size_t |
256 |
Reserved; not used. The register file grows as needed. |
max_stack_size |
size_t |
65536 |
Reserved; not enforced. Script recursion is limited by max_call_depth. |
max_call_depth |
size_t |
200000 |
Max nesting of script function calls; deeper recursion raises a catchable "Stack overflow" error (0 = no limit) |
strict_mode |
bool |
false |
Enforce type annotations at runtime |
warn_on_conversion |
bool |
false |
Warn on implicit conversions |
debug_mode |
bool |
false |
Extra debug output |
override_behavior |
MobiusOverrideBehavior |
MOBIUS_OVERRIDE_ERROR |
Global/function name-conflict policy |
fiber_stack_size |
size_t |
524288 (512 KiB) |
C stack size for pooled worker fibers (spawned work) |
main_fiber_stack_size |
size_t |
8388608 (8 MiB) |
C stack size for the top-level script fiber, which hosts the whole script and its deep native calls; 0 falls back to fiber_stack_size |
initial_fiber_pool_size |
size_t |
16 |
Fibers pre-allocated on first spawn |
max_fiber_pool_size |
size_t |
256 |
Hard cap on pooled fibers |
max_worker_threads |
int |
hardware_concurrency() / 2 - 1 (≥ 1) |
Extra worker threads; 0 = single-threaded cooperative. The calling thread always participates, so total workers = this value + 1. |
string_pool_buckets |
size_t |
65536 |
Initial string-intern hash buckets (rounded to a power of two; grows as needed). 0 = default. See Footprint. |
global_slot_capacity |
size_t |
16384 |
Preallocated global-variable slots. Also the hard cap — exceeding it is a runtime error, so include headroom for stdlib registrations. 0 = default. |
MobiusOverrideBehavior is one of MOBIUS_OVERRIDE_ERROR (default),
MOBIUS_OVERRIDE_WARN, or MOBIUS_OVERRIDE_QUIET.
Numbers below are from a Linux x86-64 release build; exact figures vary by platform and compiler, but the shape holds.
Disk. The core library — VM, compiler, fiber runtime, garbage collector,
and the entire no-import standard library — is a single shared object of
about 1.1 MB stripped. The optional CLI adds ~100 KB. Bundled modules
(json, http, sqlite, …) are separate shared objects loaded only on
import; ship just the ones you use (json ≈ 55 KB, crypto ≈ 59 KB,
http ≈ 151 KB stripped).
Memory. A minimal host — create a state, register the stdlib, run a small script — peaks around 6.3 MB resident with the default configuration. Decomposed:
| Stage | Peak RSS |
|---|---|
| Bare C process (libc/libstdc++ baseline) | ~1.4 MB |
+ mobius_new_state + mobius_init_stdlib |
~5.7 MB |
| + first script executed | ~6.3 MB |
State creation dominates, and most of it is two deliberately speed-sized
preallocations you can shrink through MobiusConfig:
MobiusConfig cfg = mobius_default_config();
cfg.string_pool_buckets = 1024; /* default 65536 — grows as needed */
cfg.global_slot_capacity = 512; /* default 16384 — hard cap, see below */
cfg.initial_fiber_pool_size = 2; /* default 16 */
MobiusState* state = mobius_new_state(&cfg);The tuned configuration above measures ~5.4 MB peak on the same host.
The remainder is code pages and thread/fiber stacks; fiber stacks are
virtual memory sized by fiber_stack_size / main_fiber_stack_size, of
which only touched pages become resident.
Two cautions:
global_slot_capacityis a hard cap as well as a preallocation. The standard library registers ~60 globals; leave headroom for your own. An undersized cap fails scripts with "Global slot capacity exceeded" rather than crashing.- Shrinking
string_pool_bucketstrades interning speed for memory; the pool grows automatically under load, so start small only when memory is the constraint.
Startup — state creation through first script execution — is under 10 ms.
int rc = mobius_exec_string(state, "var x = 42\nprint(x)");
int rc = mobius_exec_file(state, "scripts/init.mob");Both return MOBIUS_OK (0) on success; on failure they return an error code and
invoke the registered error handler.
| Constant | Value | Meaning |
|---|---|---|
MOBIUS_OK |
0 | Success |
MOBIUS_ERROR_SYNTAX |
1 | Parse / syntax error |
MOBIUS_ERROR_RUNTIME |
2 | Runtime error |
MOBIUS_ERROR_TYPE |
3 | Type mismatch |
MOBIUS_ERROR_ARGUMENT |
4 | Wrong number of arguments |
MOBIUS_ERROR_MEMORY |
5 | Memory allocation failure |
MOBIUS_ERROR_FILE |
6 | File I/O error |
MOBIUS_ERROR_PLUGIN |
7 | Plugin loading error |
mobius_start_repl(state) runs the interactive REPL (blocks until exit).
All data exchange between C and Mobius goes through a value stack, much like Lua's:
- Positive indices count from the bottom:
1is the first element. - Negative indices count from the top:
-1is the top. - Push functions add to the top; pop removes from the top.
Index: 1 2 3 ← positive (from bottom)
Stack: [ 10 | "hi" | true ]
Index: -3 -2 -1 ← negative (from top)
mobius_stack_pushNil(state);
mobius_stack_pushBool(state, true);
mobius_stack_pushInt64(state, 42);
mobius_stack_pushUInt64(state, 1000000ULL);
mobius_stack_pushFloat64(state, 3.14);
mobius_stack_pushString(state, "hello");
mobius_stack_pushStringLength(state, data, len); // non-NUL-terminated
mobius_stack_pushNewTable(state, capacity_hint);
mobius_stack_pushNewArray(state, capacity_hint);
mobius_stack_pushNewBuffer(state, size);Permissive getters (as prefix) auto-convert; strict getters (get prefix)
respect the strict_types pragma and error on mismatch:
double d = mobius_stack_asFloat64(state, -1);
int64_t i = mobius_stack_asInt64(state, -1);
const char* s = mobius_stack_asString(state, -1);
bool b = mobius_stack_asBool(state, -1);
size_t len;
const char* raw = mobius_stack_getStringData(state, -1, &len); // bytes + length
int64_t strict = mobius_stack_getInt64(state, -1); // strict variantint n = mobius_stack_size(state);
MobiusValueType t = mobius_stack_type(state, -1);
mobius_stack_isNumber(state, -1); // also isInteger/isFloat/isString/isBool/
mobius_stack_isNil(state, -1); // isNil/isTable/isArray/isFunction/
mobius_stack_isBuffer(state, -1); // isUserdata/isBuffer
mobius_stack_pop(state, 2); // pop 2 values
mobius_stack_copy(state, -1); // duplicate the value at an indexmobius_stack_pushString(state, "Mobius 0.1.0");
mobius_stack_setGlobal(state, "APP_VERSION"); // pops the value into a global
mobius_stack_getGlobal(state, "result"); // pushes the global (nil if absent)
if (mobius_stack_isNumber(state, -1)) {
double v = mobius_stack_asFloat64(state, -1);
}
mobius_stack_pop(state, 1);
mobius_set_global_readonly(state, "APP_VERSION", true); // scripts can't reassign
mobius_remove_global(state, "APP_VERSION"); // truly remove (not nil)mobius_stack_pushNewTable(state, 4);
mobius_stack_pushString(state, "Alice");
mobius_stack_setTableField(state, -2, "name"); // pops value into table[key]
mobius_stack_getTableField(state, -1, "name"); // pushes table[key]
const char* name = mobius_stack_asString(state, -1);
mobius_stack_pop(state, 1);
size_t count = mobius_stack_getTableSize(state, -1);
mobius_stack_getTableKeys(state, -1); // pushes an array of keys
mobius_stack_pop(state, 1);
mobius_stack_setGlobal(state, "player");mobius_stack_pushNewArray(state, 8);
mobius_stack_pushString(state, "first");
mobius_stack_setArrayElement(state, -2, 0); // pops value into array[0]
mobius_stack_getArrayElement(state, -1, 0); // pushes array[0]
size_t len = mobius_stack_getArrayLength(state, -1);
mobius_stack_pushInt64(state, 99);
mobius_stack_arrayPush(state, -2); // append top to the array
mobius_stack_arrayPop(state, -1); // pop the array's last element
mobius_stack_arrayInsert(state, arr_idx, index); // insert top at index
mobius_stack_arrayRemove(state, arr_idx, index); // remove element at indexmobius_stack_pushNewBuffer(state, 1024); // owned, zeroed
mobius_stack_pushBufferCopy(state, data, size); // copy of external bytes
// Wrap external memory without copying; release() is called when the
// buffer is collected. Pass readonly = true to forbid writes from scripts.
mobius_stack_pushBufferExternal(state, ptr, size, release_fn, userdata, false);
size_t size;
void* p = mobius_stack_getBufferData(state, -1, &size); // raw pointer
size_t n = mobius_stack_getBufferSize(state, -1);
bool fixed = mobius_stack_bufferIsFixed(state, -1);
bool ro = mobius_stack_bufferIsReadonly(state, -1);Userdata passes an arbitrary C pointer into scripts; attach a destructor for cleanup when the value is collected.
typedef struct { float x, y, z; } Vec3;
void vec3_destroy(void* p) { free(p); }
Vec3* v = malloc(sizeof(Vec3));
mobius_stack_pushUserdata(state, v, vec3_destroy, "Vec3", sizeof(Vec3));
mobius_stack_setGlobal(state, "position");
mobius_stack_getGlobal(state, "position");
const char* type_name = NULL;
Vec3* pos = (Vec3*)mobius_stack_getUserdata(state, -1, &type_name);
mobius_stack_pop(state, 1);To give a userdata type methods callable from scripts, register a userdata type metatable.
Build an enum, or take one a script declared, and push its values: by member name, or by number, which also makes values no member has (a combination of flag members, an error code the enum doesn't list). Each pushes the value above the enum, which stays on the stack. Values are 32-bit.
mobius_stack_pushNewEnum(state, "Mod");
mobius_stack_enumAddMember(state, -1, "SHIFT", 1);
mobius_stack_enumAddMember(state, -1, "CONTROL", 2);
mobius_stack_getEnumMember(state, -1, "SHIFT"); // Mod.SHIFT
mobius_stack_pop(state, 1);
mobius_stack_getEnumValue(state, -1, 1 | 2); // SHIFT and CONTROL
mobius_stack_setGlobal(state, "both");
mobius_stack_setGlobal(state, "Mod");A native function has the signature:
int my_function(MobiusState* state, int arg_count, void* userdata);userdata is the pointer you registered the function with (below); built-in
and plugin functions get NULL.
Arguments are on the stack (last argument at -1). Read them, pop what you
consume, push return values, and return the count pushed (>= 0). On error,
return mobius_error() (always negative).
#include <mobius/mobius_plugin.h>
int native_square(MobiusState* state, int arg_count, void* userdata) {
if (arg_count != 1)
return mobius_error(state, "square() expects 1 argument");
if (!mobius_stack_isNumber(state, -1))
return mobius_error(state, "square() expects a number");
double v = mobius_stack_asFloat64(state, -1);
mobius_stack_pop(state, 1);
mobius_stack_pushFloat64(state, v * v);
return 1; // one return value
}
// ... after mobius_init_stdlib():
mobius_register_function(state, "square", native_square, NULL);print(square(9)) // 81
Return multiple values by pushing several and returning the count; return
nothing by returning 0.
The last argument of mobius_register_function is passed to the function as
its userdata on every call (it may be NULL). Use it to reach an object,
for example a C++ member function through a static trampoline:
class World {
public:
int spawnEnemy(MobiusState* state, int argc); // reads args, pushes results
};
static int SpawnEnemy(MobiusState* state, int argc, void* userdata) {
return static_cast<World*>(userdata)->spawnEnemy(state, argc);
}
mobius_register_function(state, "spawn_enemy", SpawnEnemy, &world);One C function can serve many registrations this way; a language binding
uses a single dispatcher and passes a handle to each callback as the
userdata. mobius_stack_pushFunction(state, fn, userdata) pushes such a
function as a value, to store in a table or module. Functions with
different userdata are different values (==, table keys).
A registered function never moves to another thread while it runs. If it
calls back into a script, that script may sleep or do I/O (the thread
blocks), but waiting for another fiber there (await, fiber.all,
fiber.any, channel send/recv) raises "cannot wait for another fiber
inside a host function". This keeps the frames of C++ code (and of runtimes
such as .NET) on the thread they started on.
On Windows, registered functions and the host's callbacks (output, errors, files, exit, userdata destructors, external buffer releases) run on the worker thread's own stack, not a fiber's: the fiber switches to the thread's own context for the call and back afterwards. .NET does not support managed code on Win32 fiber stacks. On Linux and macOS they run on the fiber's stack.
A registered function is a read-only global, like the built-in functions: scripts can't reassign it, and functions running in spawned fibers can call it. Registering the same name again replaces it. It may run on any worker thread (see Concurrency and fibers).
mobius_pcall calls a function already set up on the stack (push the function,
then its arguments):
mobius_stack_getGlobal(state, "greet"); // push the function
mobius_stack_pushString(state, "World"); // push 1 argument
int nresults = mobius_pcall(state, /*nargs=*/1, /*nresults=*/1);
if (nresults >= 0) {
const char* msg = mobius_stack_asString(state, -1);
mobius_stack_pop(state, 1);
}mobius_pcall returns the number of results on success (≥ 0) or a negative
error code.
A MobiusValueRef keeps a value alive across calls without holding a stack
slot — useful for storing callbacks or objects in your host structures.
MobiusValueRef ref = mobius_ref_value(state, -1); // root the value at -1
// ... later ...
mobius_push_ref(state, ref); // push it back onto the stack
mobius_unref_value(state, ref); // release when donemobius_call_ref(state, fn_ref, arg_refs, nargs, nresults) calls a rooted
function with rooted arguments, pushing the results onto the current stack —
handy for invoking stored callbacks from arbitrary C code.
By default, errors are written to the state's error output (stderr, or the
output handler) with line/column info. Only errors that
will not be caught are reported: an error raised while a try block is active
in the running script unwinds to its catch without calling the handler. An
error that escapes a spawned fiber is reported once: by the code that awaits the
fiber, if it doesn't catch it, or, if nothing ever awaits the fiber, when its
future is dropped. Install a callback to intercept them:
void my_error_handler(MobiusState* state, const MobiusError* error, void* userdata) {
FILE* log = (FILE*)userdata;
fprintf(log, "[ERROR %d] %s:%d:%d: %s\n",
error->code, error->filename ? error->filename : "?",
error->line, error->column, error->message);
if (error->suggestion) fprintf(log, " hint: %s\n", error->suggestion);
if (error->function_name) fprintf(log, " in: %s\n", error->function_name);
if (error->traceback) fprintf(log, " %s\n", error->traceback);
}
mobius_set_error_handler(state, my_error_handler, logfile); // returns previous handlerThe MobiusError fields are code, message, suggestion (may be NULL),
filename (may be NULL), line, column, function_name (may be NULL) and
traceback (may be NULL). filename and line are where the error happened:
the failing instruction, or the script's call of the native function that
raised it. traceback lists the script calls that led there, innermost first,
one per line (called from script.mob:4 in g): the call of a function that
threw, or the statement that ran a metamethod. It is NULL when the error is in
the outermost call (the script's top level, or the function the host called).
All pointers are valid only for the duration of the callback — copy them if
you need to keep them.
After handling an error, call mobius_clear_error(state) so execution can
continue. From inside a native function, report errors with
mobius_error(state, "message") and return its result. The error's file and
line are those of the script's call of the native function.
Everything the interpreter writes goes through one output handler per state:
print output on MOBIUS_STDOUT (one call per print, newline included, so
lines from different fibers never interleave), and the default error
handler's messages and warnings on MOBIUS_STDERR. Without a handler they go
to the process's stdout and stderr. A game typically routes them to its
console or log:
void on_output(MobiusState* state, int stream, const char* data, size_t length,
void* userdata) {
game_log(stream == MOBIUS_STDERR ? LOG_ERROR : LOG_INFO, data, length);
}
mobius_set_output_handler(state, on_output, NULL);data is not NUL-terminated and is valid only during the call. The handler
may run on any worker thread, concurrently with itself.
A script's exit(code) calls the state's exit handler; what exiting means is
up to the host (the mobius command ends the process). When the handler
returns, the script continues after the exit call. Without a handler,
exit only writes a warning.
void on_exit(MobiusState* state, int code, void* userdata) {
request_mod_unload((Mod*)userdata, code);
}
mobius_set_exit_handler(state, on_exit, mod);Scripts reach files through readfile, readlines, writefile,
appendfile, file_exists, load(path) and import of .mob modules. A
host can serve all of them itself, for example from the game's archives or
a per-mod save directory:
int pak_read(MobiusState* state, const char* path, MobiusFileRequest* request,
void* userdata) {
PakFile* f = pak_open((Pak*)userdata, path);
if (!f) {
mobius_file_set_error(request, "no such file");
return 1; // anything but MOBIUS_OK is a failure
}
mobius_file_set_data(request, f->data, f->size); // copied
pak_close(f);
return MOBIUS_OK;
}
int pak_exists(MobiusState* state, const char* path, void* userdata) {
return pak_contains((Pak*)userdata, path);
}
MobiusFileSystem fs = { pak_read, NULL /* write */, pak_exists };
mobius_set_file_system(state, &fs, pak);
mobius_add_plugin_directory(state, "scripts"); // import "util" finds scripts/util.mobA NULL callback makes that operation unavailable (here, writing fails
with "file access is not available"). Paths arrive exactly as the script
wrote them; the host decides what they mean. The callbacks may run on any
worker thread, concurrently. With a file system set, import looks for
NAME.mob next to the importing script and in the plugin directories,
through exists and read; native plugins are not loaded. The host's own
mobius_exec_file also reads through it.
To run scripts the host doesn't fully trust (mods), sandbox the state before running them:
MobiusState* state = mobius_new_state(NULL);
mobius_init_stdlib(state);
mobius_sandbox(state, 0); // nothing built in allowed
mobius_allow_module(state, "math"); // mods may import "math"
mobius_set_output_handler(state, on_output, NULL);
mobius_set_file_system(state, &mod_fs, mod);In a sandbox, native plugins are never loaded, built-in
modules only once the host allows each one, and
everything a script could use to reach outside goes to the host's handlers. Where the host
installed none, the built-in behavior is used only if allow includes its
flag:
| Capability | Script functions | Host handler | Flag for the built-in | Neither |
|---|---|---|---|---|
| Output | print, error and warning text |
mobius_set_output_handler |
MOBIUS_CAP_OUTPUT |
discarded |
| Files | readfile, readlines, writefile, appendfile, file_exists, load, import of .mob files |
mobius_set_file_system |
MOBIUS_CAP_FILES |
catchable "file access is not available" error |
| Exit | exit |
mobius_set_exit_handler |
(none) | a warning |
Modules the host registers with mobius_register_module, and fiber, can
always be imported. A built-in module can be imported once the host allows
it with mobius_allow_module; until then, importing it raises a catchable
error, "Module 'math' is not allowed in this sandbox", wherever the import
runs (the script, a module it imports, a spawned fiber). In a sandbox, a
module name with a .. segment or an absolute path is rejected. Calling
mobius_sandbox again changes allow; allowed modules stay allowed.
Registered modules are the way to hand a sandboxed script the game's API
as import "game":
mobius_stack_pushNewTable(state, 8);
// ... set fields: functions, constants
mobius_register_module(state, "game");The sandbox limits what a script can reach, not how long it runs. To stop
runaway scripts (while (true) {}) and give scripts a budget, set a count
hook:
static const char* over_budget(MobiusState* state, void* userdata) {
return "over budget"; // NULL would let the script go on
}
mobius_set_count_hook(state, over_budget, 10000, NULL);The hook runs after every count instructions a script executes
without waiting: every bytecode instruction the interpreter runs
(mobius --debug script.mob lists a script's), by the code words it takes.
Most take one; a fused instruction (the compiler fuses some common pairs,
such as a global's lookup and its call) takes one per instruction it fuses,
and arithmetic with a 64-bit constant takes three. A call of a native or
host function is the one call instruction that invoked it, however long the
function runs; a script function it calls back counts its own instructions.
The interpreter doesn't count instruction by instruction. It counts where
control flow changes: at each jump taken (a loop's jump back, a test that
skips an instruction, the integer for loop), each call of a script
function, each return and each caught error, it adds the instructions run
since the last such point -- exact for the straight-line code between
them -- and calls the hook if the count is exceeded. So the hook may come a
few instructions late, by at most one straight-line run of instructions;
every loop and every call goes through such a point, so no script runs on
unchecked.
When the hook returns a message, the script fails with the runtime error
instruction limit: <message> at the instruction it reached. The error
unwinds the whole script to the host, past any try/catch in the script,
and reaches the error handler and the return code as usual. Returning
NULL lets the script go on for another count; a hook can, for example,
check a clock and stop only scripts that ran too long.
Each fiber counts for itself, and its count starts again at zero when the
host starts a script (mobius_exec_string and friends, or mobius_call_ref
outside any running script), when a spawned fiber starts, and each time a
fiber waits (yield, await, fiber.sleep, channels, I/O; not waiting
for an atomic block's lock). So with a hook that always stops, count is
a budget for each call from the host (give or take a straight-line run):
mobius_set_count_hook(state, over_budget, 10000, NULL);
for (each tick) {
if (mobius_call_ref(state, on_tick, NULL, 0, 0) < 0) {
// the script failed, or ran more than 10000 instructions
}
}and, for a script that runs as a fiber, a budget between two waits. A script called back from a host function counts on the fiber that called the host function, without starting again.
The setting applies to scripts the host starts afterwards. A fiber spawned
by a script keeps its parent's hook, count and userdata, so a script can't
escape its budget by spawning. mobius_set_count_hook(state, NULL, 0, NULL)
removes the hook for scripts started afterwards. Like other host callbacks,
the hook may run on any worker thread, concurrently for different fibers;
it must not run scripts.
Counting costs about 1% on benchmarks/benchmark_comprehensive.mob
whether or not a hook is set, more in code that is mostly calls of tiny
functions (recursive Fibonacci: about 7%). Memory limits are separate.
Mobius follows Lua's model for its standard modules:
- Built-in modules are small standard modules with no dependencies and
no effects outside the script. They are compiled into the core library,
so they need no files:
mathis one. - Every module with dependencies or outside effects (
json,os,io,socket,http,sqlite, ...) is a native plugin: a shared library loaded on first import (Loading plugins).
There is one build of the core, with every built-in module in it. The host chooses at run time which of them scripts may import:
- without a sandbox, every built-in module can be imported, like
import "math"in themobiuscommand; - in a sandbox, none can until the host allows each by name:
mobius_sandbox(state, 0);
if (mobius_allow_module(state, "math") != MOBIUS_OK) {
// not a built-in module
}mobius_allow_module may be called before or after mobius_sandbox, and
lasts for the state. It returns MOBIUS_ERROR_ARGUMENT for a name that is
not a built-in module, a plugin's name included (plugins never load in a
sandbox); "fiber" is always importable, so allowing it does nothing.
A built-in module's name is taken: import "math" gives the built-in
module even if a math plugin (say, from an older Mobius installation) or
a math.mob is on the search path, and those are never loaded. A module
the host registers with mobius_register_module under the same name
replaces it, as the host's own choice.
math is the only built-in module so far. Other modules with no
dependencies or outside effects (json, regex, ...) move into the core
the same way, one at a time, when something needs them in a sandbox; until
then they are plugins.
Plugins are shared libraries (.so/.dll) that export mobius_plugin_info().
See the Plugin Guide for how to write them.
Plugin search directories are per-state; add them after creating the state:
mobius_add_plugin_directory(state, "./modules");
mobius_add_plugin_directory(state, "/usr/lib/mobius/modules");
mobius_clear_plugin_directories(state); // reset all search pathsThe interpreter scans these directories when a script runs import "name",
loading the matching module lazily (a built-in
module is never looked up there):
import "json"
print(json.stringify({hp: 3}))
A type metatable attaches methods to all values of a type. When a script
uses obj:method(...), the VM looks the method up in the metatable for obj's
type. This is how the built-in array, table, buffer, and channel methods work.
mobius_init_stdlib() installs the standard metatables; you can extend them or
add metatables for other types.
// Read the current array metatable (pushes nil if none set)
mobius_push_type_metatable(state, MOBIUS_VAL_ARRAY);
// Add a method to it, then re-install
mobius_register_function(state, "__temp_sum", native_array_sum, NULL);
mobius_stack_getGlobal(state, "__temp_sum");
mobius_stack_setTableField(state, -2, "sum");
mobius_remove_global(state, "__temp_sum");
mobius_set_type_metatable(state, MOBIUS_VAL_ARRAY);For userdata, register methods by type name so different userdata types can have different prototypes:
mobius_push_userdata_type_metatable(state, "Vec3"); // or nil
mobius_set_userdata_type_metatable(state, "Vec3"); // pop + installA userdata type metatable resolves obj.field / obj:method() like a regular
table: it checks the metatable directly, then follows __index — which may be a
function (called as __index(obj, key)) or a table (a prototype chain,
followed recursively, exactly as with setmetatable). Lookups that miss the
type metatable fall through to the generic MOBIUS_VAL_USERDATA metatable. So
you can give userdata full prototype-style inheritance:
var Base = { kind: func(self) { return "base" } }
var Proto = { describe: func(self) { return "proto" } }
setmetatable(Proto, { __index: Base }) // Proto inherits from Base
// (register Proto as the userdata type metatable from C)
// obj:describe() resolves in Proto; obj:kind() chains through to Base.
A method's receiver (self) arrives as the first argument on the native stack:
int native_array_sum(MobiusState* state, int arg_count, void* userdata) {
if (!mobius_stack_isArray(state, 1))
return mobius_error(state, "sum() expects an array receiver");
size_t len = mobius_stack_getArrayLength(state, 1);
double total = 0;
for (size_t i = 0; i < len; i++) {
mobius_stack_getArrayElement(state, 1, i);
total += mobius_stack_asFloat64(state, -1);
mobius_stack_pop(state, 1);
}
mobius_stack_pushFloat64(state, total);
return 1;
}Each MobiusState is fully independent — its own globals, stack, plugin paths,
and fiber pool — so you can run several concurrently:
MobiusState* a = mobius_new_state(NULL);
MobiusState* b = mobius_new_state(NULL);
mobius_init_stdlib(a);
mobius_init_stdlib(b);
mobius_stack_pushInt64(a, 100); mobius_stack_setGlobal(a, "value");
mobius_stack_pushInt64(b, 200); mobius_stack_setGlobal(b, "value");
mobius_exec_string(a, "print(value)"); // 100
mobius_exec_string(b, "print(value)"); // 200
mobius_free_state(a);
mobius_free_state(b);Scripts use spawn, await, yield, shared, and atomic to run fibers
concurrently within a single state (see Concurrency).
Each state owns a fiber pool and worker threads, configured via MobiusConfig:
MobiusConfig config = mobius_default_config();
config.max_worker_threads = 8;
config.initial_fiber_pool_size = 32;
config.max_fiber_pool_size = 2048;
config.fiber_stack_size = 256 * 1024;
MobiusState* state = mobius_new_state(&config);Threading model:
- Each state maintains a pool of worker threads (
max_worker_threads); the calling thread also participates as a worker: duringmobius_exec_stringit runs ready fibers (usually the main script fiber) until the script finishes, and the same during amobius_call_reffrom outside any running script, whose function runs as the main fiber and may spawn and wait. Withmax_worker_threads = 0it is the only worker, and fibers the script spawned but never awaited continue during the next call into the state. - The top-level script runs on a dedicated main fiber with its own,
larger stack (
main_fiber_stack_size, default 8 MiB). Pooled worker fibers usefiber_stack_size(default 512 KiB). Because native calls the script makes directly run on the main fiber's stack, the main fiber is sized to behave like a normal thread stack — size it for the deepest native call chain you expect (e.g. graphics drivers). Native calls made from inside aspawned function run on a worker fiber's smaller stack. spawnacquires a fiber from the pool and schedules it on a worker.- Reference counts are atomic and shared containers use locks.
- Different
MobiusStateinstances share no mutable state and run independently. - Native functions may be invoked from any worker thread — make them thread-safe if they touch shared C/C++ state.
A native function that waits on a descriptor should not block in read() or
poll(): that holds a worker thread for the whole wait. Use
mobius_io_wait instead (Linux):
MobiusIoWait w = { fd, MOBIUS_IO_READ };
int r = mobius_io_wait(state, &w, 1, timeout_ms); /* -1: no timeout */
if (r == MOBIUS_IO_CANCELLED) return mobius_error(state, "CancellationError: fiber was cancelled");
if (r == MOBIUS_IO_TIMEOUT) { /* ... */ }
/* r >= 0: index of a ready descriptor; read it (retry if it would still block) */Inside a fiber the fiber is parked and its worker runs other fibers. A single
reactor thread watches the descriptors with epoll and wakes the fiber when
one is ready, when the timeout passes, or when fiber.cancel cancels it.
Outside a fiber, the call blocks in poll(). Pass several descriptors to wait
for whichever is ready first, or none to sleep. Before closing a descriptor
another fiber may be waiting on, call mobius_io_wake_fd(fd): the waiter
returns MOBIUS_IO_CLOSED.
mobius_get_metrics copies a snapshot into a caller-provided struct (it returns
void):
MobiusMetrics m;
mobius_get_metrics(state, &m);
printf("fibers spawned: %zu\n", m.total_fibers_spawned);
printf("jobs executed: %zu\n", m.total_jobs_executed);
printf("peak fibers: %zu\n", m.peak_fibers);
printf("exec time (ns): %llu\n", (unsigned long long)m.total_execution_time_ns);
mobius_reset_metrics(state);MobiusMetrics includes VM high-water marks (peak_call_depth,
peak_registers, peak_upvalues, peak_try_depth), state marks
(peak_globals, peak_interned_strings), fiber/thread stats
(peak_fibers, peak_worker_threads, total_fibers_spawned,
total_jobs_executed, peak_fiber_stack_bytes, avg_fiber_stack_bytes), and
total_execution_time_ns.
Next: Plugin Guide · Packaging.