winzik/docker/ext/cryo/php_cryo.h
David Nurdin 1e0a9fad24 Cryo save points freeze the whole program, whatever the game (no code of it): JumPHP\Cryo\ProcessFreeze
- "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]>
2026-11-15 11:18:43 +01:00

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