jit_policy.h

/*
** JIT compilation policy for the extensible SQL parser.
**
** Decides when to JIT compile a snapshot based on runtime metrics.
** The policy tracks per-snapshot usage statistics and triggers
** background JIT compilation when the expected benefit (faster action
** table lookups) exceeds the compilation cost.
**
** Thread safety: JITMetrics use atomic counters so multiple parser
** threads can update them concurrently. The background compilation
** thread is managed internally and publishes the JIT context to the
** snapshot via an atomic pointer store.
*/
#ifndef JIT_POLICY_H
#define JIT_POLICY_H
 
#include <stdint.h>
#include <stdbool.h>
#include <stdatomic.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* Forward declaration */
typedef struct ParserSnapshot ParserSnapshot;
 
/* ------------------------------------------------------------------ */
/*  JIT metrics                                                        */
/* ------------------------------------------------------------------ */
 
typedef struct JITMetrics {
    atomic_uint_fast64_t parse_count;         
    atomic_uint_fast64_t total_parse_time_ns; 
    atomic_uint_fast64_t action_lookup_count; 
    atomic_uint_fast64_t total_tokens_parsed; 
    atomic_int           is_jitted;           
    atomic_int           jit_in_progress;     
} JITMetrics;
 
/* ------------------------------------------------------------------ */
/*  Policy configuration                                               */
/* ------------------------------------------------------------------ */
 
typedef struct JITPolicyConfig {
    uint64_t min_parse_count;
 
    uint64_t min_total_parse_time_ns;
 
    uint64_t min_avg_lookups_per_parse;
 
    bool background_compile;
 
    uint32_t min_grammar_states;
 
    uint32_t min_avg_tokens_per_parse;
 
    bool enabled;
 
    bool tokenizer_jit_enabled;
} JITPolicyConfig;
 
/* ------------------------------------------------------------------ */
/*  Policy API                                                         */
/* ------------------------------------------------------------------ */
 
/*
** Return the default policy configuration.
** Defaults:
**   min_parse_count           = 200
**   min_total_parse_time_ns   = 10,000,000  (10 ms cumulative)
**   min_avg_lookups_per_parse = 100
**   background_compile        = true
**   min_grammar_states        = 500
**   min_avg_tokens_per_parse  = 200
**   enabled                   = true
**   tokenizer_jit_enabled     = true
*/
JITPolicyConfig jit_policy_default_config(void);
 
/*
** Initialize a JITMetrics struct to zero. Must be called before
** the metrics are used.
*/
void jit_metrics_init(JITMetrics *m);
 
/*
** Record the completion of a parse session.
** Updates parse_count, total_parse_time_ns, and action_lookup_count.
** Thread-safe (uses atomic operations).
*/
void jit_metrics_record_parse(JITMetrics *m,
                              uint64_t parse_time_ns,
                              uint64_t action_lookups);
 
/*
** Record the number of tokens processed in a parse session.
** Thread-safe (uses atomic operations).
*/
void jit_metrics_record_tokens(JITMetrics *m, uint64_t token_count);
 
/*
** Evaluate whether a snapshot should be JIT compiled based on its
** current metrics and the given policy configuration.
**
** Returns true if the metrics exceed all thresholds and the snapshot
** is not already JIT compiled or in the process of being compiled.
*/
bool jit_should_compile(const JITMetrics *m, const JITPolicyConfig *config);
 
/*
** Possibly trigger JIT compilation for a snapshot.
**
** Checks the metrics against the policy; if compilation is warranted:
**   - If config->background_compile is true, spawns a detached thread
**     that compiles and atomically publishes the JIT context.
**   - If config->background_compile is false, compiles synchronously.
**
** Returns:
**   0 -- compilation triggered (or already done)
**   1 -- metrics do not yet warrant compilation
**  -1 -- error (JIT unavailable, snapshot NULL, etc.)
**
** Thread-safe: uses the jit_in_progress flag to prevent concurrent
** compilation attempts on the same snapshot.
*/
int jit_maybe_compile(ParserSnapshot *snap,
                      JITMetrics *m,
                      const JITPolicyConfig *config);
 
/*
** Shut down the JIT policy subsystem.
** Waits for any in-flight background compilations to finish.
** Call once at application shutdown.
*/
void jit_policy_shutdown(void);
 
#ifdef __cplusplus
}
#endif
 
#endif /* JIT_POLICY_H */