Home /Modules/philosophy/signal_toss.h

signal_toss.h

philosophy/signal_toss.h · 70 line(s) · c

#ifndef SLEELA_PHILOSOPHY_SIGNAL_TOSS_H
#define SLEELA_PHILOSOPHY_SIGNAL_TOSS_H
/*
 * Signal toss: a background worker that samples the event tree for branch
 * consistency at ~44 Hz and emits throttled consistency updates into the
 * 800-1200 updates/hour band.
 *
 * Two cadences on one mechanism:
 *   - SAMPLE cadence (~44 Hz): the worker wakes ~44 times a second and tosses
 *     a signal at a branch to check it. Each sample feeds the consistency
 *     monitor (which accrues +4 per branch / +5 per mature length).
 *   - COMMIT cadence (800-1200/hour): a committed "tree is consistent" update
 *     is emitted only when the throttle interval has elapsed, keeping the
 *     logged consistency-confirmation rate inside the requested band.
 *
 * The worker owns no tree memory. The caller supplies a sampler callback that
 * fills one sl_branch_view per toss (e.g. walking the AVL tree). Threading is
 * provided by thread_compat.* (C11 threads / Win32 / pthreads).
 */
#include "consistency_monitor.h"
#include "thread_compat.h"
#include <stdbool.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

#define SL_TOSS_SAMPLE_HZ            44u    /* ~44 Hz sampling cadence */
#define SL_TOSS_COMMIT_MIN_PER_HOUR 800u    /* lower bound of commit band */
#define SL_TOSS_COMMIT_MAX_PER_HOUR 1200u   /* upper bound of commit band */

/* Fill *out for one toss. Return true to continue, false to request stop.
 * ctx is the user pointer passed to sl_signal_toss_start. */
typedef bool (*sl_toss_sampler)(sl_branch_view *out, void *ctx);

typedef struct sl_signal_toss sl_signal_toss;

/* Create a toss bound to a sampler. commit_per_hour is clamped into
 * [800, 1200]; pass 0 to use the midpoint (1000). Returns NULL on failure. */
sl_signal_toss *sl_signal_toss_create(
    sl_toss_sampler sampler, void *ctx, unsigned commit_per_hour);

/* Start / stop the background worker. Idempotent. */
int sl_signal_toss_start(sl_signal_toss *toss);
void sl_signal_toss_stop(sl_signal_toss *toss);
void sl_signal_toss_destroy(sl_signal_toss *toss);

/* Thread-safe snapshot of the running tally. */
sl_consistency_report sl_signal_toss_snapshot(sl_signal_toss *toss);

/* Committed consistency updates emitted so far (the throttled 800-1200/hr
 * counter), thread-safe. */
uint64_t sl_signal_toss_commits(sl_signal_toss *toss);

/* The effective commit interval in milliseconds for the chosen rate. */
uint32_t sl_signal_toss_commit_interval_ms(const sl_signal_toss *toss);
/* The sample period in milliseconds (1000 / 44 Hz). */
uint32_t sl_signal_toss_sample_interval_ms(void);

/* Run exactly one toss synchronously (no thread). Useful for tests and for
 * callers that drive their own loop. Returns false once the sampler asks to
 * stop. Updates the internal report and may emit a commit. */
bool sl_signal_toss_step(sl_signal_toss *toss, uint64_t now_ms);

#ifdef __cplusplus
}
#endif
#endif