sleela_bestof.h
impl/core/sleela_bestof.h · 165 line(s) · c
/* ==========================================================================
* sleela_bestof.h -- Best-of: configurable route/accuracy selection for
* Synchro measurement and Munction/RMI packet transport.
*
* A "best-of" is a small, transparent selection engine. It holds a bounded set
* of CANDIDATES -- each a bundle of an internet ROUTE (endpoint/URI) plus its
* SETTINGS (timeout, payload size, min-gap), FLAGS (crypto/retry/pacing/dscp/
* replay), an internet QoS ARCHITECTURE (best-effort / DiffServ / IntServ /
* MPLS -- see NETWORK.md), a protocol VERSION, and a COST -- and it is
* configured with WEIGHTS across five axes:
*
* data how much the measured quality (latency/loss/jitter) matters
* decisions how much the advisory QoS certainty (QOS.md) matters
* costs how much the candidate's cost counts against it
* versions how much protocol/packet version fitness matters
* architecture how much the realized QoS architecture fitness matters
*
* Measurements from Synchro (or any honest source) are folded in per candidate
* with bestof_record(). bestof_best() then picks the highest-scoring candidate
* that satisfies the minimum version and the cost budget, and bestof_choice()
* reports exactly which parts of the internet (route, settings, flags, replays)
* were chosen -- so a caller can adjust Synchro accuracy or aim Munction/RMI
* packets down the selected route.
*
* The engine is honest, like the rest of the timing work: it SELECTS and
* REPORTS from measured data; it never fabricates accuracy and never promises a
* delivery guarantee the transport cannot make. A candidate with no
* measurements is unproven and scored as such, never assumed good.
*
* A best-of is a Sleela-owned bounded resource (a handle into a fixed table),
* the same discipline used for sockets/synchro/munction.
* ========================================================================== */
#ifndef SLEELA_BESTOF_H
#define SLEELA_BESTOF_H
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* Max concurrent best-of selectors owned by one VM. */
#define SL_BESTOF_MAX 32
/* Max candidate routes per selector. */
#define SL_BESTOF_CANDIDATES 64
/* Weight axes (bestof_weight). */
#define SL_BESTOF_AXIS_DATA 0 /* measured latency/loss/jitter quality */
#define SL_BESTOF_AXIS_DECISIONS 1 /* advisory QoS carrier certainty */
#define SL_BESTOF_AXIS_COSTS 2 /* cost penalty */
#define SL_BESTOF_AXIS_VERSIONS 3 /* protocol/packet version fitness */
#define SL_BESTOF_AXIS_ARCHITECTURE 4 /* realized QoS-architecture fitness */
/* Candidate flags (bitset). These name the internet "settings/flags" a route
* may carry; they are advisory selection inputs, not transport guarantees. */
#define SL_BESTOF_FLAG_CRYPTO 0x01 /* sealed transport preferred */
#define SL_BESTOF_FLAG_RETRY 0x02 /* retry-on-bump allowed */
#define SL_BESTOF_FLAG_PACING 0x04 /* honor min-gap pacing */
#define SL_BESTOF_FLAG_DSCP 0x08 /* set DSCP/ToS class where supported */
#define SL_BESTOF_FLAG_REPLAY 0x10 /* replay/average multiple probes */
/* Internet QoS architecture a candidate route is served by (see NETWORK.md
* "Internet Architectures"). Best-of stays advisory: naming an architecture
* declares how the route asks the network to treat its packets; whether the
* network honors it is measured, never assumed. Each architecture carries one
* integer parameter (see slbestof_candidate_arch): */
#define SL_BESTOF_ARCH_BESTEFFORT 0 /* no QoS marking; ordinary best-effort */
#define SL_BESTOF_ARCH_DIFFSERV 1 /* DiffServ: hop-by-hop DSCP marking */
/* param = DSCP class (0..63) */
#define SL_BESTOF_ARCH_INTSERV 2 /* IntServ: end-to-end RSVP reservation */
/* param = reserved kbps (0 = none yet) */
#define SL_BESTOF_ARCH_MPLS 3 /* MPLS: label-switched, traffic-engineered */
/* param = MPLS label (0 = unlabeled) */
/* Realization state of a candidate's architecture, reported honestly: a route
* may REQUEST an architecture but the network may not have realized it yet. */
#define SL_BESTOF_ARCH_REQUESTED 0 /* declared, not yet confirmed realized */
#define SL_BESTOF_ARCH_REALIZED 1 /* confirmed: marked/reserved/labeled OK */
#define SL_BESTOF_ARCH_DENIED 2 /* the network declined (e.g. RSVP reject) */
typedef struct SLBestOf SLBestOf;
/* Create a best-of selector. Returns a heap selector or NULL on error.
* Weights default to data=45 decisions=25 costs=10 versions=5 architecture=15;
* min_version=0; cost_budget = INT unbounded (0 == unbounded). */
SLBestOf* slbestof_new(void);
/* Configure a weight axis (0..100 clamped). Returns 0, or -1 on a bad axis. */
int slbestof_weight(SLBestOf* b, int axis, int weight);
/* Set the minimum acceptable protocol version and the cost budget (0 budget =
* unbounded). Candidates below min_version or above the budget are excluded
* from bestof_best(). */
void slbestof_min_version(SLBestOf* b, int min_version);
void slbestof_cost_budget(SLBestOf* b, int cost_budget);
/* Register a candidate route. `name` is a stable label; `route` is the internet
* endpoint/URI. Returns the candidate index (>=0) or -1 if the table is full.
* timeout_ms/payload_len/min_gap_ms/flags/version/cost/replays are the settings
* and flags this route carries. */
int slbestof_add_candidate(SLBestOf* b, const char* name, const char* route,
int timeout_ms, int payload_len, int min_gap_ms,
int flags, int version, int cost, int replays);
/* Declare the internet QoS ARCHITECTURE a candidate route is served by
* (SL_BESTOF_ARCH_*), its architecture parameter (DiffServ: DSCP class 0..63;
* IntServ: reserved kbps; MPLS: label; best-effort: ignored), and the current
* realization state (SL_BESTOF_ARCH_REQUESTED/REALIZED/DENIED). A route that
* only *requests* an architecture earns no architecture bonus; one confirmed
* REALIZED earns the full bonus; a DENIED reservation (e.g. RSVP reject) is a
* penalty. Call after slbestof_add_candidate. Returns 0 or -1 on a bad idx.
* A candidate defaults to best-effort/requested when this is not called, so
* existing callers are unaffected. */
int slbestof_candidate_arch(SLBestOf* b, int idx, int architecture,
int arch_param, int realized);
/* Update just the realization state of a candidate's architecture -- e.g. after
* an RSVP reservation is confirmed or denied, or a DSCP/MPLS path is verified
* by measurement. Returns 0 or -1 on a bad idx. */
int slbestof_arch_realized(SLBestOf* b, int idx, int realized);
/* Per-candidate architecture accessors. */
int slbestof_arch(const SLBestOf* b, int idx); /* SL_BESTOF_ARCH_* */
int slbestof_arch_param(const SLBestOf* b, int idx); /* DSCP/kbps/label */
int slbestof_arch_state(const SLBestOf* b, int idx); /* requested/realized/denied */
/* Fold one honest measurement into candidate `idx`: a measured RTT in
* microseconds (>=0), or -1 to record a loss. Updates the candidate's running
* mean/jitter/loss and its carrier certainty. Returns 0 or -1 on a bad idx. */
int slbestof_record(SLBestOf* b, int idx, int64_t rtt_us);
/* The transparent score for candidate `idx` (higher is better), computed from
* the configured weights and the candidate's measured data. Returns the score,
* or a large-negative sentinel for a bad/excluded candidate. */
int64_t slbestof_score(SLBestOf* b, int idx);
/* The index of the best candidate that satisfies min_version and cost_budget,
* or -1 when none qualifies (e.g. nothing measured yet). */
int slbestof_best(SLBestOf* b);
/* Per-candidate measured accessors (microseconds / permille / [0..1000]). */
int64_t slbestof_mean_us(const SLBestOf* b, int idx);
int64_t slbestof_loss_permille(const SLBestOf* b, int idx);
int64_t slbestof_jitter_us(const SLBestOf* b, int idx);
int slbestof_certainty_permille(const SLBestOf* b, int idx); /* 0..1000 */
/* Write the winning choice as a one-line description of the parts of the
* internet selected: "name route timeout=..ms payload=..B gap=..ms
* flags=[..] version=.. replays=.. score=..". Returns bytes written (0 if no
* winner). This is what a caller applies to Synchro/Munction/RMI. */
int slbestof_choice(SLBestOf* b, char* out, size_t cap);
/* Write a multi-line report of every candidate and its score. Returns length. */
int slbestof_report(SLBestOf* b, char* out, size_t cap);
/* Release the selector. Safe on NULL. */
void slbestof_close(SLBestOf* b);
#ifdef __cplusplus
}
#endif
#endif /* SLEELA_BESTOF_H */