Skip to content

Latest commit

 

History

History
984 lines (763 loc) · 38 KB

embedding-guide.md

File metadata and controls

984 lines (763 loc) · 38 KB

Embedding Guide

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_app

Integers live as int64 in the VM. The stack API offers narrow helpers (pushInt8, asInt32, pushFloat32, …) that convert at the C boundary for convenience, but prefer pushInt64/pushUInt64/pushFloat64 and asInt64/asUInt64/asFloat64 in new code.

← Documentation home


Contents

  1. Minimal example
  2. State lifecycle
  3. Configuration
  4. Footprint
  5. Executing scripts
  6. The stack
  7. Exchanging values
  8. Registering native functions
  9. Calling Mobius functions from C
  10. Rooted value handles
  11. Error handling
  12. Output and exit
  13. Files
  14. Sandboxing
  15. Built-in modules
  16. Loading plugins
  17. Type metatables
  18. Multiple interpreters
  19. Concurrency and fibers
  20. Metrics

Minimal example

#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.


State lifecycle

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

Configuration

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.


Footprint

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_capacity is 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_buckets trades 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.


Executing scripts

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).


The stack

All data exchange between C and Mobius goes through a value stack, much like Lua's:

  • Positive indices count from the bottom: 1 is the first element.
  • Negative indices count from the top: -1 is 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)

Push

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);

Read

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 variant

Inspect & manipulate

int 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 index

Exchanging values

Globals

mobius_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)

Tables

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");

Arrays

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 index

Buffers

mobius_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

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.

Enums

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");

Registering native functions

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.

Userdata: calling C++ member functions

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).


Calling Mobius functions from C

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.


Rooted value handles

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 done

mobius_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.


Error handling

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 handler

The 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.


Output and exit

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);

Files

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.mob

A 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.


Sandboxing

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");

Instruction budgets

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.


Built-in modules

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: math is 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 the mobius command;
  • 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.


Loading 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 paths

The 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}))

Type metatables

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 + install

A 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;
}

Multiple interpreters

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);

Concurrency and fibers

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: during mobius_exec_string it runs ready fibers (usually the main script fiber) until the script finishes, and the same during a mobius_call_ref from outside any running script, whose function runs as the main fiber and may spawn and wait. With max_worker_threads = 0 it 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 use fiber_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 a spawned function run on a worker fiber's smaller stack.
  • spawn acquires a fiber from the pool and schedules it on a worker.
  • Reference counts are atomic and shared containers use locks.
  • Different MobiusState instances 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.

Waiting for I/O in a native function

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.


Metrics

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.