45 lines
2.7 KiB
C
45 lines
2.7 KiB
C
// calogTask.h -- calog task library: launch and manage other calog script contexts.
|
|
//
|
|
// Registers inline natives that let a script of any engine spawn and manage other scripts:
|
|
// taskSpawn(engine, code) -> handle run a code string on a named engine (fire-and-forget)
|
|
// taskLoad(baseName) -> handle launch a script FILE (engine chosen by extension)
|
|
// taskEval(handle, code) feed more code into a running task (runs on its thread)
|
|
// taskClose(handle) stop a task (cooperative shutdown; see below)
|
|
// taskSelf() -> id the calling script's own context id
|
|
// taskCount() -> n number of tasks this library currently holds open
|
|
//
|
|
// Tasks are FIRE-AND-FORGET: a spawned context runs on its own thread and returns nothing to
|
|
// the caller; results come back through host natives you register (calog's usual pattern). A
|
|
// task is a persistent interpreter -- taskEval feeds it more code over time until taskClose.
|
|
//
|
|
// OWNERSHIP: a task is owned by the context that spawned/loaded it, and ONLY that owner may
|
|
// taskEval or taskClose it (others get an error). This is enforced, not just documented: it
|
|
// makes taskClose -- which blocks joining the task's thread -- unable to self-join (a task
|
|
// cannot hold its own handle) or dead-lock a mutual close. A task whose owner is torn down
|
|
// without closing it becomes an orphan, reclaimed when the runtime is destroyed.
|
|
//
|
|
// taskClose is COOPERATIVE (it is the "kill"): it queues a shutdown and waits for the task's
|
|
// thread to exit. A task blocked calling back into the host (a host-thread native) has that
|
|
// call interrupted; a task busy in a pure computation is not force-cancelled (that would
|
|
// corrupt interpreter state), so a task spinning in an infinite loop cannot be force-killed.
|
|
// (A task that, during its shutdown, synchronously invokes a callable owned by the closing
|
|
// context can still dead-lock, since the closer is blocked in the join -- avoid that.)
|
|
// Engines are addressed by name for
|
|
// those compiled in (CALOG_WITH_LUA / _JS / _SQUIRREL / _MYBASIC / _BERRY / _S7 / _WREN);
|
|
// taskLoad additionally needs the engines registered with calogRegisterEngine at setup.
|
|
|
|
#ifndef CALOG_TASK_H
|
|
#define CALOG_TASK_H
|
|
|
|
#include "calog.h"
|
|
|
|
// Register the task natives on a runtime. Idempotent across runtimes (they share a
|
|
// process-wide task registry; each spawn goes into the caller's own runtime). Returns
|
|
// calogOkE or an error.
|
|
int32_t calogTaskRegister(CalogT *calog);
|
|
|
|
// Free the process-wide task registry. Call it AFTER the runtime is torn down
|
|
// (calogDestroy), which is what actually closes any still-open task contexts.
|
|
void calogTaskShutdown(void);
|
|
|
|
#endif
|