Native plugins › 08 Concurrency and operations

Concurrency and operations

Write plugins that block safely, use platform primitives, and avoid the classic mistakes.

1. Blocking is allowed

While a native is running, the VM removes the thread from the collector's stop-the-world set. A native may therefore block — on I/O, on a mutex, or in loth_sleep_ms — without stalling the GC:

#include "loth_plat.h"

static void nd_pause(NativeCtx* ctx) {
    loth_sleep_ms((uint32_t)n_as_int(n_arg(ctx, 0), n_arg_type(ctx, 0)));
}

The trade-off is the root contract: while the native blocks or works, the GC may collect anything it cannot see. Values in the handle need gc_scan; values in C locals need vm_push_root.

2. Platform primitives

loth_plat.h is the portability layer. Plugins may use it directly:

Do not mix platforms: the same layer is used by the VM, so a plugin compiled against it behaves the same way on every supported system.

3. Thread safety of a plugin

• Each native object has its own handle. Two threads calling methods on the same object run concurrently unless the language synchronizes them; guard the handle yourself with a mutex if the object is shared.
• Library-level state (C globals) is process-wide and shared by every VM in the process. Keep it immutable or lock it.
• gc_scan and finalize run on the collector thread. They must not assume a particular caller.
• Native methods can create language threads through the standard library, or host threads through loth_thread_create plus the attach API from the embedding track.

4. Watchdog

The VM counts bytecode steps per thread. A host can cap them with vm_set_max_steps(vm, n); the CLI uses the LOTH_MAX_STEPS environment variable. When a thread exceeds its budget it panics with a step report. Native time is not counted, so a plugin that loops forever in C is not interrupted — check your own loops.

5. Pitfalls

6. Where to go next

• Embedding the VM — the other half of C integration.