Home /Modules/impl/sleela_synchro.h

sleela_synchro.h

impl/core/sleela_synchro.h · 71 line(s) · c

/* ==========================================================================
 * sleela_synchro.h -- Synchro: honest packet dispatch + latency measurement.
 *
 * The C/C++ re-authoring of the Synchro layer for the direct Sleela engine
 * build. Synchro sends timestamped probes to a destination, matches replies,
 * and reports the MEASURED latency distribution. It makes no delivery-time
 * guarantee (none is physically possible for arbitrary destinations); it
 * measures what actually happened and reports it honestly, including loss.
 *
 * A Synchro probe is a Sleela-owned, bounded resource (a handle into a fixed
 * table), the same discipline used for sockets/files. Handles are VM-local
 * integers, never raw OS descriptors.
 * ========================================================================== */
#ifndef SLEELA_SYNCHRO_H
#define SLEELA_SYNCHRO_H

#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Maximum concurrent Synchro probes owned by one VM. */
#define SL_SYNCHRO_MAX 64
/* Bound on samples retained per probe for the measured distribution. */
#define SL_SYNCHRO_MAX_SAMPLES 4096

/* An opaque Synchro probe. Callers never see its fields; they hold an index. */
typedef struct SLSynchro SLSynchro;

/* Create a probe bound to a destination "host:port" (UDP echo/measurement).
 * Returns a heap probe or NULL on error. The probe owns no thread; it is driven
 * synchronously by dispatch/measure so it composes with the VM thread model. */
SLSynchro* slsynchro_open(const char* host, uint16_t port);

/* One dispatch cycle: send a timestamped probe of `payload_len` bytes and wait
 * up to `timeout_ms` for the echoed reply. Records the measured round-trip when
 * the reply matches, or a loss when it does not. Returns the measured RTT in
 * microseconds (>= 0) on a matched reply, or -1 on loss/timeout. Never blocks
 * longer than timeout_ms. */
int64_t slsynchro_dispatch(SLSynchro* s, size_t payload_len, int timeout_ms);

/* Number of dispatches so far and how many were matched (received). */
int64_t slsynchro_sent(const SLSynchro* s);
int64_t slsynchro_received(const SLSynchro* s);

/* Measured latency statistics in microseconds over retained samples. When no
 * sample has been received these report -1 (mean/min/max) / 0 (loss uses sent).
 * loss_permille is losses per 1000 dispatches (0..1000). */
int64_t slsynchro_mean_us(const SLSynchro* s);
int64_t slsynchro_min_us(const SLSynchro* s);
int64_t slsynchro_max_us(const SLSynchro* s);
/* p in [0,100]; returns the measured percentile RTT in us, or -1 if no data. */
int64_t slsynchro_percentile_us(const SLSynchro* s, int p);
int64_t slsynchro_loss_permille(const SLSynchro* s);

/* A one-line honest report the language surface can print, e.g.
 * "synchro host:port sent=N recv=M loss=..permille mean=..us p95=..us".
 * Writes at most cap-1 bytes + NUL into out; returns bytes written. */
int slsynchro_report(const SLSynchro* s, char* out, size_t cap);

/* Release the probe and its socket. Safe on NULL. */
void slsynchro_close(SLSynchro* s);

#ifdef __cplusplus
}
#endif

#endif /* SLEELA_SYNCHRO_H */