snapshot.h

/*
** Snapshot system core data structures for the extensible SQL parser.
**
** A ParserSnapshot captures the complete state of a parser's tables at a
** point in time. Snapshots use atomic reference counting so they can be
** safely shared across threads: readers acquire a reference before use and
** release it when done. When the last reference is released the snapshot
** and all of its owned memory are freed.
*/
#ifndef SNAPSHOT_H
#define SNAPSHOT_H
 
#include <stdint.h>
#include <stdbool.h>
 
/* Magic + ABI version stamped on every ParserSnapshot constructed
** via snapshot_build_from_tables.  Bumped on any layout-breaking
** change to the struct. */
#define LIME_SNAPSHOT_MAGIC       0x4C494D45U   /* L,I,M,E */
#define LIME_SNAPSHOT_ABI_VERSION 2
 
 
/* Atomic refcount type.
**
** In C this is just <stdatomic.h>'s atomic_uint_fast32_t.  In C++
** the same name is not necessarily available (g++ before C++23
** does not pull in <stdatomic.h>'s typedefs), so we typedef it to
** std::atomic<std::uint_fast32_t> which has the same memory
** layout in practice on every supported platform.  The atomic
** operations themselves only happen in C code in src/snapshot.c
** (compiled as C, sees the C definition); C++ consumers only need
** the field to exist for sizeof / pointer-to-struct purposes. */
#ifdef __cplusplus
#include <atomic>
#include <cstdint>
typedef std::atomic<std::uint_fast32_t> atomic_uint_fast32_t;
#else
#include <stdatomic.h>
#endif
 
/* Forward declarations for Lemon grammar structures.
** The actual definitions live in lemon.c; snapshot consumers only
** need pointers to these types. */
struct symbol;
struct rule;
struct state;
 
/* ------------------------------------------------------------------ */
/*  Host-reduce hook (Letter 30)                                       */
/* ------------------------------------------------------------------ */
 
typedef int (*LimeHostReduceFn)(void *user, int ruleno,
                                const void *rhs_values, const int *rhs_locs,
                                int nrhs, void *lhs_out, int *lhs_loc_out);
 
/* ------------------------------------------------------------------ */
/*  Semantic versioning                                                */
/* ------------------------------------------------------------------ */
 
typedef struct SemVer {
    uint32_t major;   
    uint32_t minor;   
    uint32_t patch;   
    char *prerelease; 
} SemVer;
 
typedef enum VersionOp {
    VERSION_OP_EQ = 0, /* == exact match                    */
    VERSION_OP_GTE,    /* >= greater-than-or-equal          */
    VERSION_OP_LTE,    /* <= less-than-or-equal             */
    VERSION_OP_GT,     /* >  strictly greater               */
    VERSION_OP_LT,     /* <  strictly less                  */
    VERSION_OP_CARET,  /* ^  compatible (same major)        */
    VERSION_OP_TILDE,  /* ~  approximately (same major.minor) */
} VersionOp;
 
typedef struct VersionConstraint {
    VersionOp op;   
    SemVer version; 
} VersionConstraint;
 
/* ------------------------------------------------------------------ */
/*  Module dependency metadata                                         */
/* ------------------------------------------------------------------ */
 
typedef struct ParserDependency {
    char *module_name;              
    uint8_t merkle_root[32];        
    VersionConstraint *constraints; 
    uint32_t nconstraints;          
    bool optional;                  
} ParserDependency;
 
typedef struct ParserModule {
    char *name;     
    SemVer version; 
    ParserDependency *dependencies; 
    uint32_t ndependencies;         
    char **exports;    
    uint32_t nexports; 
    char **imports;    
    uint32_t nimports; 
} ParserModule;
 
/* ------------------------------------------------------------------ */
/*  Snapshot                                                           */
/* ------------------------------------------------------------------ */
 
/*
** A ParserSnapshot holds a frozen copy of every table the generated parser
** needs at runtime. Fields fall into three groups:
**
**   1. Bookkeeping   - version, refcount, timestamps
**   2. Grammar data  - symbols, rules, states (deep copies)
**   3. Action tables  - the compact arrays that drive the parse engine
**   4. Module data   - optional module identity and content hash
*/
typedef struct ParserSnapshot {
    /* ================================================================
    ** CACHELINE 0 (bytes 0..63): hot pointer reads.
    **
    ** Every parse_token call reads from these.  Layout-critical: do
    ** not move fields around within this block without rerunning
    ** bench/bench_parse_fanout (the layout was chosen so all 8
    ** pointers occupy exactly one 64-byte cacheline on x86_64 +
    ** aarch64).  L1 data prefetcher pulls the whole line in as a
    ** unit on the first miss.
    ** ================================================================ */
 
    void *jit_find_shift_fn;
 
    uint16_t *yy_action;       
    uint16_t *yy_lookahead;    
    int32_t  *yy_shift_ofst;   
    int32_t  *yy_reduce_ofst;  
    uint16_t *yy_default;      
    int16_t  *yy_rule_info_lhs;
    int8_t   *yy_rule_info_nrhs;
    /* ================================================================
    ** CACHELINE 1 (bytes 64..127): hot scalars + counts.
    **
    ** Action-table dispatch constants the parse_engine_step hot path
    ** consults to classify action-table entries (shift vs reduce vs
    ** accept) and to bounds-check indices into yy_action / yy_lookahead.
    ** ================================================================ */
 
    uint32_t lookahead_count;  
    uint32_t action_count;     
    uint32_t nrule;            
    uint32_t nstate;           
    uint16_t yy_max_shift;       
    uint16_t yy_min_shiftreduce; 
    uint16_t yy_max_shiftreduce; 
    uint16_t yy_error_action;    
    uint16_t yy_accept_action;   
    uint16_t yy_no_action;       
    uint16_t yy_min_reduce;      
    uint16_t yy_ntoken;          
    uint16_t yy_first_token;
 
    /* Cacheline 1 has 6 bytes of padding here to land yy_fallback on
    ** an 8-byte boundary.  Compiler inserts implicitly. */
 
    uint16_t *yy_fallback;
    uint32_t nfallback;          
    uint32_t reserved_pad;       
    /* ================================================================
    ** CACHELINE 2 (bytes 128..191): refcount + magic.
    **
    ** Refcount is the only WRITTEN field on the parse path (via
    ** atomic_fetch_add/sub in snapshot_acquire/release).  Keep it
    ** away from the read-only hot lines above so threads doing
    ** parse_begin do not invalidate the cachelines other threads
    ** are reading yy_action etc from.
    **
    ** parse_begin_borrowed bypasses the refcount entirely (see
    ** include/parse_context.h); for the borrowed-API path this
    ** cacheline is never touched on the hot path.
    ** ================================================================ */
 
    uint32_t magic;
    uint16_t abi_version;
    uint16_t reserved16; 
    uint64_t version;
 
    atomic_uint_fast32_t refcount;
 
    uint32_t reserved_pad2;      
    /* ================================================================
    ** COLD: setup-time + introspection fields (rarely read after
    ** snapshot construction).
    ** ================================================================ */
 
    /* --- Grammar data (deep-copied, owned by this snapshot) ----------- */
 
    struct symbol **symbols; 
    uint32_t nsymbol;        
    uint32_t nterminal;      
    struct rule *rules; 
    struct state **states; 
    char *grammar_source;
    uint32_t grammar_source_len;
    uint32_t reserved_pad3;
 
    /* --- Module identity (optional, NULL when not part of a module) --- */
 
    uint8_t merkle_root[32]; 
    ParserModule *module;    
    uint64_t create_time_ns;
 
    void *jit_ctx;
 
    /* --- Host-reduce hook (Letter 30) -------------------------------
    ** Optional callback that runs a BASE-grammar reduce action over
    ** this snapshot when the push parser (parse_token) performs a
    ** reduce.  NULL on every snapshot built before this feature and
    ** on any recognition-only snapshot, in which case parse_token
    ** drives the automaton to accept/reject WITHOUT running actions
    ** (the historical behaviour -- fully back-compatible).
    **
    ** `lime -n` wires this to the generated, exported
    ** <Name>HostReduce wrapper, which adapts the engine's value
    ** stack to the static per-rule yy_rule_reduce_fn[] dispatch in
    ** the parser .c.  The signature mirrors LimeReduceFn (extension
    ** reduces), so base and extension reduce paths share one ABI.
    **
    ** COLD field: never read on the shift hot path; consulted only
    ** inside the reduce branch, and only when non-NULL.  Additive
    ** trailing field -- old snapshot readers never touch it, so no
    ** abi_version bump is required (snapshot_build_from_tables
    ** zero-inits it for tables that don't supply one). */
    LimeHostReduceFn host_reduce;
    void *host_reduce_user;
 
    /* --- Token-name table (name -> code lookup) ---------------------
    ** Optional copy of the generated yyTokenName[], indexed by internal
    ** symbol index ([0]="$", terminals then nonterminals).  Lets
    ** lime_snapshot_token_code() map a token NAME to its external code
    ** in THIS snapshot -- needed so a scanner can emit the right code
    ** for an extension keyword after a runtime recompile renumbers the
    ** token set.  NULL when names were not provided (the lookup then
    ** returns -1).  Deep-copied + owned by the snapshot. */
    char **token_names;
    uint32_t token_names_count;
} ParserSnapshot;
 
/*
** Acquire a reference to an existing snapshot.  The caller must eventually
** call snapshot_release() to avoid leaking the snapshot.
**
** Returns the same pointer that was passed in, for convenience:
**     ParserSnapshot *my_ref = snapshot_acquire(shared_snap);
**
** Passing NULL is safe and returns NULL.
*/
ParserSnapshot *snapshot_acquire(ParserSnapshot *snap);
 
/*
** Release a reference previously obtained via snapshot_acquire() or
** create_base_snapshot().  When the last reference is released the
** snapshot and all memory it owns are freed.
**
** Passing NULL is safe and does nothing.
*/
void snapshot_release(ParserSnapshot *snap);
 
/*
** Create a base snapshot from *grammar_file*.
**
** The runtime delegates to a per-grammar <Prefix>BuildSnapshot()
** function emitted by `lime -n grammar.y` (see snapshot_build.h
** and the LimeParserTables struct).  When no such builder is linked
** into the host process this function returns NULL with an
** actionable error message.
**
** Building a snapshot directly from a grammar file at runtime --
** without a pre-compiled <Prefix>BuildSnapshot() symbol -- is
** under construction.  It requires exposing the lime generator's
** LALR(1) Build()/ReportTable() phases as a library callable from
** the runtime; the generator's algorithm is fully implemented in
** lime.c but not yet refactored into a public function.
**
** Returns a snapshot with refcount == 1 on success, or NULL with
** *error pointing to a malloc'd message on failure.
*/
ParserSnapshot *create_base_snapshot(const char *grammar_file, char **error);
 
/* ------------------------------------------------------------------ */
/*  SemVer utilities                                                   */
/* ------------------------------------------------------------------ */
 
/*
** Parse a semantic version string ("1.2.3" or "1.2.3-beta.1") into a
** SemVer struct.  Returns true on success.  On failure *out is zeroed
** and the function returns false.
*/
bool semver_parse(const char *str, SemVer *out);
 
/*
** Compare two semantic versions.  Returns <0, 0, or >0 following the
** same convention as strcmp.  Prerelease versions sort before their
** release counterpart (e.g. 1.0.0-alpha < 1.0.0).
*/
int semver_compare(const SemVer *a, const SemVer *b);
 
/*
** Check whether *ver* satisfies *constraint*.
*/
bool semver_satisfies(const SemVer *ver, const VersionConstraint *constraint);
 
/*
** Free resources owned by a SemVer (just the prerelease string).
** Does not free the SemVer struct itself.
*/
void semver_destroy(SemVer *v);
 
/* ------------------------------------------------------------------ */
/*  Module lifecycle helpers                                           */
/* ------------------------------------------------------------------ */
 
/*
** Deep-free a ParserModule and all memory it owns (name, version,
** dependencies, exports, imports).  Does not free the pointer itself
** unless *mod* was heap-allocated by the caller.
*/
void parser_module_destroy_contents(ParserModule *mod);
 
/*
** Deep-free a ParserDependency's owned memory.
*/
void parser_dependency_destroy_contents(ParserDependency *dep);
 
#endif /* SNAPSHOT_H */