script_state

Introduction

The script_state plugin owns a single, globally living (running across the whole script's life) byte buffer, and exposes its address and size to the script. State based on the buffer can be shared between the main script thread and callbacks by raw pointer — a pattern that predates the language's global / callback global variables and that is safe only when the two sides provably never touch the buffer at the same time. The plugin works hand-in-hand with the blob plugin's RefFromPointer function: with the returned address and size, you can construct a ref-blob view onto the buffer.

Why it exists

DominScript's global variables live in two worlds — global on the main thread, callback global on the dispatcher thread — and the two worlds cannot name each other's variables; state crosses between them by a call (worker.Call), not by a read. This plugin is the older, lower-level alternative: one raw byte buffer that both sides map by pointer. There is no lock on it, so it is correct exactly when you guarantee the ordering: one side waits inside a call while the other touches the buffer, or the callback only ever runs while the main loop is blocked in a plugin call. Two valid patterns, then — the language's own (callback global + worker.Call, where the runtime provides the ordering) is the default; this one is for when the guarantee is yours. The OpenGL demo showed the second until it moved to the first. When in doubt, use map, queue or a Call. The script_state plugin solves this with a plugin-scoped storage: the main thread writes the state into the buffer, and the callback reads/writes the same memory through a ref-blob (using GetPointer + GetSize). Both sides see the same bytes.

Typical pattern with the blob plugin

Usually you describe the state with a struct and allocate the struct's bytes: `script_state.Allocate(structsize(AppState));`. Then in both the main thread and the callback you use `ref blob &S = blob.RefFromPointer(script_state.GetPointer(), script_state.GetSize()); S assign AppState;` for typed access. The plugin owns the buffer; the ref-blob is just a view onto it — the caller must therefore make sure no ref-blob is still in use before Free is called.

Loading the plugin

plugin "builtin:print";
plugin "../plugins/script_state/ScriptStatePlugin";
plugin "../plugins/blob/BlobPlugin";

A typical flow — allocating and accessing script state

struct AppState packet
{
    i32 width;
    i32 height;
    double angle;
}
i32 main()
{
    script_state.Allocate(structsize(AppState));
    {
        ref blob &S = blob.RefFromPointer(script_state.GetPointer(),
        script_state.GetSize());
        S assign AppState;
        S.width = 1280;
        S.height = 720;
        S.angle = 0.0;
    }
// ... in callbacks the same ref blob can be recreated ...
script_state.Free();
return(0);
}

What to know about every function (the basics)

• The plugin owns one global buffer; at most one allocation exists at a time. A new Allocate call DROPS the old buffer (its contents are lost) and allocates a new one.

• Allocate fills the buffer with ZERO bytes: every byte is 0 initially (via calloc). Typed structures thus start in a zeroed state.

• Allocate(0) frees: it does not fail; it just drops the buffer and returns 0 (GetPointer and GetSize also become 0).

• A negative size raises a runtime error.

• GetPointer is an integer: the raw memory address of the buffer (converted to int64). It does NOT return a pointer type; usage goes through blob.RefFromPointer.

• GetSize is the currently allocated size in bytes — 0 when unallocated.

• An error (stopping the script) is caused by a wrong argument count or type, a negative size, and memory exhaustion.

How to read the signatures

size is the desired buffer size in bytes. GetPointer returns an integer memory address (as int64), which blob.RefFromPointer converts back into a ref-blob. The type after the -> arrow is the return type.