- "Freeze here" stops the game loop, Application::run() freezes every value reachable from the globals and statics (cryo_freeze include globals + statics: the application, engine, scenes, loop and timers, the game's services) and runs the loop again; JUMPHP_CRYO_THAW thaws it in Application::boot() before anything is built, which returns the thawed application: the game goes on exactly where it was - native parts made again at the thaw: window and SDL renderer opened by the new process, textures from their recipe (Sdl::$recipes: file or picture; render targets blank, redrawn), fonts, sounds and the music playing, gamepads (cryo_register_resource + cryo_on_thaw / replaceClass); files signed with a key of the project - the scene save point stays next to it, used when the whole program can not be resumed (code changed, OpenGL) - SceneManager params by class (no WeakMap), the container's compiler and private-method closures out of the freeze - ext-cryo a9c891d (php-cryo): typed properties holding a frozen value (closure, resource, __wakeup object, excluded object) come back; DESKTOP_REV 11 - IDE: each save point says "whole program" / "scene only" (why); docs/ide.md, docs/cryo.md Co-Authored-By: Claude Opus 5.5 <[email protected]>
192 lines
7.6 KiB
C
192 lines
7.6 KiB
C
#ifndef PHP_CRYO_H
|
|
#define PHP_CRYO_H
|
|
|
|
#include "php.h"
|
|
|
|
extern zend_module_entry cryo_module_entry;
|
|
#define phpext_cryo_ptr &cryo_module_entry
|
|
|
|
#define PHP_CRYO_VERSION "0.1.0-dev"
|
|
|
|
#define CRYO_FROZEN 1
|
|
#define CRYO_THAWED 2
|
|
|
|
/* Exceptions and classes (registered in cryo.c / cryo_reader.c) */
|
|
extern zend_class_entry *cryo_ce_exception;
|
|
extern zend_class_entry *cryo_ce_reader;
|
|
|
|
/* --- Allocation-site tracking (cryo_graph.c) ------------------------------
|
|
* v0 keeps this state in plain statics: NTS only. ZTS support will move it
|
|
* into module globals. */
|
|
typedef struct {
|
|
bool installed; /* ZEND_NEW handler installed at MINIT */
|
|
bool enabled; /* recording on/off (cryo_track()) */
|
|
uint32_t epoch; /* incremented by every cryo_snapshot() */
|
|
uint32_t cap; /* capacity of the per-handle arrays */
|
|
uint32_t *site_of; /* handle -> site id + 1 (0 = unknown) */
|
|
uint32_t *epoch_of; /* handle -> epoch at birth */
|
|
zend_class_entry **ce_of;/* handle -> class seen at birth (detects stale slots) */
|
|
HashTable sites; /* "file:line func" -> site id */
|
|
uint32_t next_site;
|
|
} cryo_track_state;
|
|
|
|
extern cryo_track_state cryo_track;
|
|
|
|
void cryo_track_minit(bool install_handler);
|
|
void cryo_track_mshutdown(void);
|
|
|
|
/* Snapshot writer (cryo_graph.c) */
|
|
zend_result cryo_write_snapshot(zend_string *file, HashTable *options);
|
|
|
|
/* Reader (cryo_reader.c) */
|
|
void cryo_reader_minit(void);
|
|
|
|
/* --- Metrics (cryo_metrics.c) ----------------------------------------------
|
|
* Process-wide counters read by cryo_metrics(), the .cryom sampler and the
|
|
* exporters. The freeze/thaw/restart code increments them, e.g.
|
|
* cryo_stats.freezes++; cryo_stats.last_freeze_ms = ms;
|
|
* cryo_stats.last_freeze_bytes = n;
|
|
* They are not reset between requests. */
|
|
typedef struct {
|
|
uint64_t freezes; /* successful cryo_freeze() */
|
|
uint64_t thaws; /* successful cryo_thaw() (this process) */
|
|
uint64_t restarts; /* cryo_restart() */
|
|
double last_freeze_ms; /* duration of the last freeze, milliseconds */
|
|
uint64_t last_freeze_bytes; /* size of the last .cryo written by a freeze */
|
|
uint64_t bytes_reclaimed; /* memory given back by restarts (before - after) */
|
|
} cryo_stats_t;
|
|
|
|
extern cryo_stats_t cryo_stats;
|
|
|
|
void cryo_metrics_minit(void);
|
|
void cryo_metrics_rshutdown(void);
|
|
void cryo_metrics_mshutdown(void);
|
|
/* Take a sample now if a series is active (e.g. right before a freeze). */
|
|
void cryo_metrics_sample_now(void);
|
|
/* WASM: the host timer (cryo_host_timer) fired. Whoever exports
|
|
* cryo_timer_fired() must call this (cryo_metrics.c provides a weak default). */
|
|
void cryo_metrics_timer_fired(void);
|
|
|
|
/* Platform (cryo_platform.c) */
|
|
const char *cryo_platform_name(void);
|
|
|
|
/* Milestone 4 / 5 (cryo_process.c, cryo_freeze.c) */
|
|
PHP_FUNCTION(cryo_freeze);
|
|
PHP_FUNCTION(cryo_thaw);
|
|
PHP_FUNCTION(cryo_restart);
|
|
PHP_FUNCTION(cryo_memory_watch);
|
|
void cryo_freeze_minit(void);
|
|
void cryo_freeze_mshutdown(void);
|
|
void cryo_process_minit(void);
|
|
void cryo_process_rshutdown(void);
|
|
void cryo_process_mshutdown(void);
|
|
void cryo_process_atfork_child(void);
|
|
/* the cryo_memory_watch() in force goes into freeze files and comes back at the thaw */
|
|
void cryo_watch_export(zval *out);
|
|
void cryo_watch_import(zval *in);
|
|
|
|
/* Fork mode (cryo_fork.c) */
|
|
PHP_FUNCTION(cryo_fork_pool);
|
|
PHP_FUNCTION(cryo_fork);
|
|
PHP_FUNCTION(cryo_fork_send);
|
|
PHP_FUNCTION(cryo_fork_recv);
|
|
PHP_FUNCTION(cryo_thaw_fork);
|
|
PHP_FUNCTION(cryo_fork_job_done);
|
|
PHP_FUNCTION(cryo_fork_info);
|
|
void cryo_fork_minit(void);
|
|
void cryo_fork_rshutdown(void);
|
|
/* Fork checkpoint, used by cryo_freeze(..., ['mode' => 'fork', 'fork' => variant]).
|
|
* variant: "child" (NULL / empty = child), "parent" or "template".
|
|
* Returns CRYO_FROZEN in the process that goes on, CRYO_THAWED in a process
|
|
* that resumes from the checkpoint; 0 with an exception set on failure. */
|
|
zend_long cryo_fork_checkpoint(zend_string *variant, HashTable *opts);
|
|
/* Runs the cryo_on_thaw hooks (cryo_freeze.c); called in every forked child. */
|
|
void cryo_hooks_run_thaw(void);
|
|
|
|
/* Exceptions (cryo.c) */
|
|
extern zend_class_entry *cryo_ce_freeze_exception;
|
|
extern zend_class_entry *cryo_ce_thaw_exception;
|
|
extern zend_class_entry *cryo_ce_signature_exception;
|
|
|
|
/* Values the serializer cannot carry (cryo_walk.c) */
|
|
extern zend_class_entry *cryo_ce_frozen, *cryo_ce_pending, *cryo_ce_aware, *cryo_ce_transient;
|
|
extern HashTable cryo_resource_handlers;
|
|
enum { CRYO_RES_DESCRIPTOR = 0, CRYO_RES_NULL = 1, CRYO_RES_FAIL = 2 };
|
|
typedef struct {
|
|
HashTable seen, done;
|
|
struct { zval *slot; zval old; } *swaps;
|
|
uint32_t nswaps, capswaps;
|
|
int on_resource;
|
|
bool strict;
|
|
HashTable *exclude;
|
|
zval typed; /* [object, class, property, marker]: markers taken out of typed properties (cryo_walk.c) */
|
|
} cryo_walk;
|
|
typedef struct {
|
|
zend_op_array *main;
|
|
HashTable seen, done;
|
|
uint32_t pending;
|
|
} cryo_thaw_ctx;
|
|
void cryo_walk_init(cryo_walk *w, HashTable *opts);
|
|
void cryo_walk_freeze(cryo_walk *w, zval *root);
|
|
void cryo_walk_undo(cryo_walk *w);
|
|
bool cryo_walk_var_excluded(cryo_walk *w, zend_string *name);
|
|
void cryo_thaw_ctx_init(cryo_thaw_ctx *t, zend_op_array *main);
|
|
void cryo_walk_thaw(cryo_thaw_ctx *t, zval *root, const char *root_path);
|
|
void cryo_walk_typed_restore(zval *data);
|
|
void cryo_thaw_ctx_free(cryo_thaw_ctx *t);
|
|
zend_result cryo_stream_describe(zval *zv, zval *desc);
|
|
void cryo_stream_reopen(zval *desc, zval *out);
|
|
void cryo_walk_minit(void);
|
|
void cryo_walk_rinit(void);
|
|
void cryo_walk_rshutdown(void);
|
|
PHP_FUNCTION(cryo_register_resource);
|
|
|
|
/* Freeze core (cryo_freeze.c), used by cryo_process.c / cryo_fork.c */
|
|
void cryo_freeze_deferred(zend_execute_data *ex); /* restart asked from an interrupt callback */
|
|
bool cryo_restart_requested(void);
|
|
void cryo_torture_tick(zend_execute_data *ex);
|
|
zend_result cryo_generator_describe(zend_object *obj, zval *data);
|
|
zend_result cryo_generator_rebuild(zval *data, zval *out);
|
|
void cryo_hooks_run_thaw(void);
|
|
zend_result cryo_exec_self(const char *thaw_file); /* cryo_process.c */
|
|
extern bool cryo_watch_in_callback; /* cryo_process.c */
|
|
PHP_FUNCTION(cryo_on_freeze);
|
|
PHP_FUNCTION(cryo_on_thaw);
|
|
PHP_FUNCTION(cryo_is_thawed);
|
|
PHP_FUNCTION(cryo_thaw_count);
|
|
PHP_FUNCTION(cryo_origin);
|
|
PHP_FUNCTION(cryo_info);
|
|
PHP_FUNCTION(cryo_verify);
|
|
void cryo_freeze_rinit(void);
|
|
void cryo_freeze_rshutdown(void);
|
|
extern zend_class_entry *cryo_ce_thaw_context;
|
|
/* Engine (cryo_engine.c) */
|
|
extern zend_class_entry *cryo_ce_engine;
|
|
void cryo_engine_minit(void);
|
|
void cryo_engine_mshutdown(void);
|
|
void cryo_engine_rshutdown(void);
|
|
bool cryo_engine_enabled(void);
|
|
uint32_t cryo_engine_change_count(void);
|
|
/* Journal of the active changes as an array of entries (closures exported as
|
|
* file + start/end lines + scope + bound variables), and its replay. Used by
|
|
* cryo_freeze()/cryo_thaw() (PTCH section) and by the sandbox engine proxy.
|
|
* replay returns the number of entries applied (exception on failure). */
|
|
void cryo_engine_journal_export(zval *out);
|
|
zend_long cryo_engine_journal_replay(zval *in);
|
|
zend_long cryo_engine_apply_entry(zval *entry);
|
|
bool cryo_closure_export(zval *closure, zval *out);
|
|
bool cryo_closure_import(zval *desc, zval *out);
|
|
|
|
/* Sandbox (cryo_sandbox.c) */
|
|
void cryo_sandbox_minit(void);
|
|
void cryo_sandbox_rshutdown(void);
|
|
|
|
/* XChaCha20-Poly1305 without libsodium (cryo_crypto.c) */
|
|
void cryo_xchacha_encrypt(uint8_t *c, const uint8_t *m, size_t mlen, const uint8_t nonce[24], const uint8_t key[32]);
|
|
int cryo_xchacha_decrypt(uint8_t *m, const uint8_t *c, size_t clen, const uint8_t nonce[24], const uint8_t key[32]);
|
|
|
|
/* Helpers */
|
|
bool cryo_jit_active(void);
|
|
ZEND_COLD void cryo_throw_not_implemented(const char *what, int milestone);
|
|
|
|
#endif
|