winzik/docker/ext/cryo/cryo_host.h

57 lines
2.9 KiB
C

/*
* Host interface for the WebAssembly backend.
*
* In WASM there is no fork(), execve() or signals. Everything that touches
* processes is delegated to the JavaScript host: cryo_host.c implements these
* functions with EM_JS, which call `Module.cryoHost.<name>(...)` when the page
* installed a host (package @cryo/wasm-host: attachCryoHost(php, opts)), and
* answer "no host" (-1 / nothing) otherwise. No wasm import is added, so a
* php.wasm with ext-cryo still instantiates on a page that knows nothing of Cryo.
*/
#ifndef CRYO_HOST_H
#define CRYO_HOST_H
#ifdef CRYO_BACKEND_WASM
#include <stdint.h>
/*
* A real symbol of cryo_host.o. EM_JS functions are imports, not definitions: in a static libphp.a nothing
* else would make the linker take this object, and every cryo_host_* call ended in "missing function".
* cryo_sandbox_minit() calls it.
*/
int cryo_host_link_anchor(void);
/* 1 when the page installed Module.cryoHost */
int32_t cryo_host_present(void);
/* Destroy this PHP instance and start a new one that thaws `path`. */
void cryo_host_restart(const char *path, uint32_t path_len);
/* New instance with a copy of linear memory (replaces fork). Returns instance id, -1 without host. */
int32_t cryo_host_clone(uint32_t mode);
/* New blank instance in a Worker (replaces posix_spawn). opts = JSON ({"timeout": seconds, ...}). */
int32_t cryo_host_spawn(const uint8_t *opts, uint32_t len);
/*
* Message channel between instances. Nothing ever blocks (the browser runs PHP frame by frame): recv
* returns at most `cap` bytes of what already arrived (the host keeps the rest for the next call and only
* queues whole frames), -1 when nothing is there yet, -2 when the instance is gone and nothing is left.
* timeout_ms is informative. send queues bytes; the host posts each frame once it is complete.
* Inside a sandbox (the child), id 0 is the parent.
*/
int32_t cryo_host_send(int32_t id, const uint8_t *buf, uint32_t len);
int32_t cryo_host_recv(int32_t id, uint8_t *buf, uint32_t cap, int32_t timeout_ms);
void cryo_host_kill(int32_t id);
/* -1 while the instance runs (or starts), its exit code once it ended (124 timeout, 134 trap, 137 killed). */
int32_t cryo_host_status(int32_t id);
/* Last error text of an ended instance (trap message, stderr tail): bytes written, 0 when none. */
int32_t cryo_host_error(int32_t id, uint8_t *buf, uint32_t cap);
/*
* Child side: a request starts (ms > 0) or ends (ms = 0). After ms milliseconds the parent's host ends the
* instance and hands its PHP the given frame (the prebuilt timeout answer), as SIGALRM does on POSIX.
*/
void cryo_host_arm(uint32_t ms, const uint8_t *frame, uint32_t len);
/* Metrics and events to JS (kind: 1 metrics JSON, 2 event JSON, 3 metric line). */
void cryo_host_emit(uint32_t kind, const uint8_t *buf, uint32_t len);
/* Clock (ms) and wake-ups (replaces SIGALRM). */
double cryo_host_now(void);
void cryo_host_timer(uint32_t ms);
#endif /* CRYO_BACKEND_WASM */
#endif