winzik/docker/ext/cryo/cryo_format.h
2026-11-14 17:21:23 +01:00

147 lines
5.7 KiB
C

/*
* .cryo file format, version 1 (snapshot subset).
*
* "CRYO" u16 format_version u16 flags u32 php_version_id u32 epoch
* then sections: char tag[4] u64 length payload[length]
*
* Integers are little-endian, fixed width in v1 (varints come later).
* Unknown sections must be skipped by readers. Node ids are dense: the
* record at position i of NODE has id i (edges and roots refer to it).
*/
#ifndef CRYO_FORMAT_H
#define CRYO_FORMAT_H
#include <stdint.h>
#define CRYO_MAGIC "CRYO"
#define CRYO_FORMAT_VERSION 1
#define CRYO_NONE 0xFFFFFFFFu
/* Section tags */
#define CRYO_SEC_STRS "STRS" /* u32 count, then { u32 len, bytes } */
#define CRYO_SEC_NODE "NODE" /* cryo_node_rec[] */
#define CRYO_SEC_EDGE "EDGE" /* cryo_edge_rec[] */
#define CRYO_SEC_ROOT "ROOT" /* cryo_root_rec[] */
#define CRYO_SEC_SITE "SITE" /* u32 str per site id */
#define CRYO_SEC_HASH "HASH" /* optional: cryo_hash_rec per node, same order as NODE */
/* Written when allocation tracking is installed (cryo.track_alloc=site|stack): */
#define CRYO_SEC_WRIT "WRIT" /* u32 site id per node: last write site of an object, CRYO_NONE if unknown */
/* Written when cryo.track_alloc=stack: */
#define CRYO_SEC_STKS "STKS" /* u32 count, then { u32 nframes, u32 site[nframes] } per stack id,
frames innermost first (frame 0 = the `new` site), up to 8 */
#define CRYO_SEC_NSTK "NSTK" /* u32 stack id per node, CRYO_NONE if unknown */
/* Reserved for later milestones:
* SRCS STCK RSRC HOOK ALOC PTCH SIGN */
enum cryo_node_type {
CRYO_NODE_ARRAY = 1,
CRYO_NODE_OBJECT = 2,
CRYO_NODE_STRING = 3,
CRYO_NODE_REF = 4,
};
enum cryo_root_kind {
CRYO_ROOT_GLOBAL = 1,
CRYO_ROOT_STATIC_PROP = 2,
CRYO_ROOT_FRAME = 3,
CRYO_ROOT_ORPHAN = 4,
CRYO_ROOT_STATIC_VAR = 5, /* function/method static variable: "f::$v", "C::m::$v" */
};
#pragma pack(push, 1)
typedef struct {
uint32_t id;
uint8_t type;
uint32_t class_str; /* CRYO_NONE if not an object */
uint64_t size; /* self size in bytes (approximate) */
uint32_t handle; /* object handle, CRYO_NONE otherwise */
uint32_t site; /* allocation site id, CRYO_NONE if unknown */
uint32_t epoch; /* birth epoch, CRYO_NONE if unknown */
} cryo_node_rec;
typedef struct {
uint32_t from;
uint32_t to;
uint32_t name_str;
} cryo_edge_rec;
typedef struct {
uint8_t kind;
uint32_t node;
uint32_t name_str;
} cryo_root_rec;
/*
* Content hash (section HASH, optional, used to find duplicates).
* strings: FNV-1a 32 of the bytes, len = byte length
* arrays: FNV-1a 32 of the keys and values when every value is a scalar
* or a string ("flat" array), len = element count
* anything else, or nested arrays: hash = 0 (no hash)
* A real hash of 0 is stored as 1. Files without HASH stay readable.
*/
typedef struct {
uint32_t hash;
uint32_t len;
} cryo_hash_rec;
#pragma pack(pop)
/* ------------------------------------------------------------------------
* .cryom — metric series (cryo_metrics_sample()), version 1.
*
* Append-only binary file, all integers little-endian, fixed width. No
* 64-bit integer is ever needed to read it: every u64 is stored as two u32
* (lo, hi), so a 32-bit PHP reads it with unpack('V') only (value =
* lo + hi * 2**32, as float when above PHP_INT_MAX). Doubles are IEEE 754
* little-endian (unpack('e')).
*
* File header, 32 bytes, written once when the file is created:
* 0 char magic[4] "CRYM"
* 4 u16 version 1
* 6 u16 flags 0
* 8 u32 php_version_id e.g. 80427
* 12 u32 pid process that created the file
* 16 f64 start unix time (seconds) of creation
* 24 u32 interval_ms sampling period at creation
* 28 u32 reserved 0
*
* Then records, each framed as:
* u8 kind, u8 reserved (0), u16 len, payload[len]
* Readers must skip unknown kinds and ignore payload bytes past the fields
* they know (later versions only append fields).
*
* kind 1 SAMPLE (len 144)
* 0 f64 time (unix seconds) 8 u32 seq 12 u32 flags (bit 0 = rss valid)
* 16 u64 memory 24 u64 memory_real
* 32 u64 memory_peak 40 u64 memory_peak_real
* 48 u64 rss 56 u64 objects_alive
* 64 u64 objects_store_size 72 u64 gc_runs
* 80 u64 gc_collected 88 u64 gc_time_ns
* 96 u64 freezes 104 u64 thaws
* 112 u64 restarts 120 u64 last_freeze_us
* 128 u64 last_freeze_bytes 136 u64 bytes_reclaimed
* kind 2 MARK f64 time, u32 seq (of the last sample), label bytes
* kind 3 SNAPSHOT f64 time, u32 seq, path of the .cryo written (auto_snapshot_every)
* kind 4 START f64 time, u32 pid, u32 interval_ms (each cryo_metrics_sample() start,
* appending to an existing file adds a new session)
* ------------------------------------------------------------------------ */
#define CRYOM_MAGIC "CRYM"
#define CRYOM_VERSION 1
#define CRYOM_HEADER_SIZE 32
#define CRYOM_REC_SAMPLE 1
#define CRYOM_REC_MARK 2
#define CRYOM_REC_SNAPSHOT 3
#define CRYOM_REC_START 4
#define CRYOM_SAMPLE_FIELDS 16 /* u64 fields after time/seq/flags */
#define CRYOM_SAMPLE_LEN (16 + 8 * CRYOM_SAMPLE_FIELDS)
#define CRYOM_FLAG_RSS 1u
/* Kinds passed to cryo_host_emit() by the WASM backend (metrics). */
#define CRYO_EMIT_SAMPLE 1 /* one SAMPLE record payload (binary, see above) */
#define CRYO_EMIT_MARK 2 /* label (UTF-8) */
#define CRYO_EMIT_PROMETHEUS 3 /* Prometheus text exposition */
#define CRYO_EMIT_STATSD 4 /* "url\n" then StatsD lines */
#define CRYO_EMIT_OTLP 5 /* "endpoint\n" then OTLP/HTTP JSON body */
#endif