42 lines
2.3 KiB
C
42 lines
2.3 KiB
C
// calogExport.h -- calog export library: publish script functions other scripts can call.
|
|
//
|
|
// Registers natives so a script can share a function by name across contexts and engines:
|
|
// calogExport(name, fn) publish a function value under a global name
|
|
// calogUnexport(name) remove it
|
|
// calogCall(name, ...args) call an exported function by name -- works in EVERY engine
|
|
//
|
|
// The natives are calog-prefixed so they never collide with an engine's reserved words
|
|
// (plain `export` is a JavaScript keyword; plain `call` is a my-basic keyword).
|
|
//
|
|
// On engines with a runtime unknown-name hook (Lua, Squirrel, JavaScript, s7), an exported
|
|
// name is ALSO reachable by its BARE name, e.g. `luaExample(1, 2)`; engines that resolve
|
|
// names statically (Wren, Berry, my-basic) use calogCall('luaExample', ...). Resolution is
|
|
// dynamic: a name exported at any time becomes callable immediately, and calogUnexport takes
|
|
// effect at once.
|
|
//
|
|
// An exported function is an ordinary calog function value, so a call runs in the exporter's
|
|
// own context/thread (marshalled like any callable), and a call after the exporter is gone
|
|
// fails cleanly. The registry is process-wide and reference-counted across runtimes.
|
|
//
|
|
// NOTE (bare-name shadowing): on the hook engines, reading an otherwise-undefined global
|
|
// whose name matches an export resolves to that export -- an exported name is visible to
|
|
// every context, so pick export names that will not collide with scripts' feature-detection
|
|
// of undefined globals.
|
|
|
|
#ifndef CALOG_EXPORT_H
|
|
#define CALOG_EXPORT_H
|
|
|
|
#include "calog.h"
|
|
|
|
// Register the export natives on a runtime. Idempotent across runtimes (shared registry).
|
|
int32_t calogExportRegister(CalogT *calog);
|
|
|
|
// Release every exported function (once the last registered runtime unregisters). Unlike the
|
|
// other libraries, call this while the exporting contexts are still ALIVE -- before you close
|
|
// them and before calogDestroy -- because an exported function is a live reference into its
|
|
// owner's interpreter; releasing it after that context is gone would touch freed memory. The
|
|
// static registry bookkeeping itself is intentionally never freed (the natives stay callable
|
|
// until calogDestroy), so this is safe to call and re-register across runtimes.
|
|
void calogExportShutdown(void);
|
|
|
|
#endif
|