api_dispatch_detail.h

Go to the documentation of this file.

/*
 * Copyright (c) 2012-2026, QORE Lab, Imperial College London
 * All rights reserved.
 */
#ifndef LINE_REG_API_DISPATCH_DETAIL_H
#define LINE_REG_API_DISPATCH_DETAIL_H
 
/**
 * @file
 * Internal to the --api dispatcher: what a per-domain translation unit needs
 * to add entries to the table that api_invoke consults.
 *
 * The table is split across translation units (api_dispatch.cpp plus one
 * api_dispatch_<group>.cpp per family of domains) because every entry
 * instantiates its algorithm at five arithmetics, and one file carrying all of
 * them is both the slowest object in the build and a file no two changes can
 * touch at once.
 *
 * REGISTRATION IS EXPLICIT, NOT BY STATIC INITIALIZER. line_mp_api is a static
 * archive, and a translation unit whose only reference is a self-registering
 * global is exactly what the linker drops from one: the table would come up
 * short with nothing to say so. Each group therefore exports two named
 * functions, listed in api_dispatch_registrars() and
 * api_library_only_registrars() below, and the link fails loudly if one is
 * missing.
 */
 
#include <cstdint>
#include <functional>
#include <map>
#include <string>
#include <type_traits>
#include <vector>
 
#include "line/api/qsys/qsys_res.h"
#include "line/reg/api_dispatch.h"
#include "line/reg/api_json.h"
 
namespace line {
namespace reg {
 
using Invoker = std::function<Json(const ArithSpec&, Args&)>;
using DispatchTable = std::map<std::string, Invoker>;
 
/** name -> why the function has no named-JSON-argument form. */
using LibraryOnlyTable = std::map<std::string, std::string>;
 
/**
 * Run an operation at the selected arithmetic. Op is a struct with a static
 * member template run<T>(Args&) returning the results object; the arithmetic
 * gate against the registry has already passed when this is reached, so every
 * branch here is a mode the function genuinely supports.
 */
template <class Op>
Json run_at(const ArithSpec& s, Args& a) {
    switch (s.mode) {
        case Arith::Double: return Op::template run<double>(a);
        case Arith::Exact: return Op::template run<Rational>(a);
        case Arith::Real:
            if (s.digits <= 50) return Op::template run<Real50>(a);
            if (s.digits <= 100) return Op::template run<Real100>(a);
            return Op::template run<Real200>(a);
    }
    throw InputError("unreachable arithmetic selection");
}
 
/**
 * Wrap an Op whose registry entry lists Double and Real but NOT Exact.
 *
 * `run_at` instantiates all three backends because the mode is a runtime value,
 * so an Op that calls exp, log or sqrt would not COMPILE at Rational even
 * though it can never be REACHED there -- `api_invoke` refuses the mode against
 * the registry before dispatching. The if-constexpr makes that same fact known
 * to the compiler. The throw is the arm the gate has already excluded, kept as
 * a real refusal rather than a placeholder so that a registry entry mistakenly
 * widened to Exact reports the reason instead of returning a wrong number.
 */
template <class Op>
struct NeedsTranscendental {
    template <class T>
    static Json run(Args& a) {
        if constexpr (num_traits<T>::has_transcendental) {
            return Op::template run<T>(a);
        } else {
            (void)a;
            throw UnsupportedError(ErrorKind{"Arithmetic"},
                "this function evaluates transcendental terms (exp, log, sqrt or a "
                "matrix exponential), which the exact rational field does not contain; "
                "rerun with --arith double or --arith real:<digits>.");
        }
    }
};
 
/**
 * Wrap an Op whose registry entry lists Double ONLY. The port of such a
 * function is not templated on the scalar (it calls a double-only kernel:
 * LAPACK, HiGHS, an ODE integrator, a random stream), so only the double arm
 * may be instantiated. The other arms are refused by the registry gate before
 * dispatch; the throw is the same safety net NeedsTranscendental keeps.
 */
template <class Op>
struct DoubleOnly {
    template <class T>
    static Json run(Args& a) {
        if constexpr (std::is_same<T, double>::value) {
            return Op::run(a);
        } else {
            (void)a;
            throw UnsupportedError(ErrorKind{"Arithmetic"},
                "this function is implemented in double precision only; rerun with "
                "--arith double.");
        }
    }
};
 
/**
 * The seed of a function whose port draws from a caller-owned generator.
 *
 * REQUIRED, NEVER DEFAULTED. The MATLAB reference falls back to the session's
 * global RNG state, which has no JSON form; a silent default seed would make
 * every call that forgot it return the same "random" draw and look like an
 * answer. So the caller names the stream, and the same seed reproduces the
 * same result at the same arithmetic (lossn_mci set the convention).
 */
inline std::uint64_t required_seed(Args& a, const std::string& fn, const char* spelled = "seed") {
    if (!a.has("seed"))
        throw InputError(fn + ": " + spelled + " is required; the port draws from a seeded "
                         "generator and has no session RNG to fall back on");
    return static_cast<std::uint64_t>(a.count("seed"));
}
 
/**
 * MATLAB's `res` struct of the exact queueing-system functions: one key per
 * measure, in the reference's field order, scalars as scalars and row vectors
 * as lists, plus `analyzer`.
 */
template <class T>
Json encode_qsys_res(const qsys::QsysResT<T>& r) {
    Json out = Json::object();
    for (const qsys::QsysResFieldT<T>& f : r.fields) {
        if (f.scalar && f.value.size() == 1) out[f.name] = encode_scalar(f.value[0]);
        else out[f.name] = encode_vector(f.value);
    }
    out["analyzer"] = r.analyzer;
    return out;
}
 
/** The 'tPoints', 'percentiles' and 'nmax' options those functions share. */
inline qsys::QsysResOptions read_qsys_res_options(Args& a, bool with_nmax = true) {
    qsys::QsysResOptions o;
    if (a.has("tPoints")) o.tPoints = a.vector<double>("tPoints");
    if (a.has("percentiles")) o.percentiles = a.vector<double>("percentiles");
    if (with_nmax && a.has("nmax")) o.nmax = static_cast<long>(a.count("nmax"));
    return o;
}
 
template <class Op>
Invoker make() {
    return [](const ArithSpec& s, Args& a) { return run_at<Op>(s, a); };
}
 
// One pair per group translation unit. Adding a group means a line here AND an
// entry in each of the two lists below.
#define LINE_API_GROUP(g)                                   \
    void register_api_##g(DispatchTable& t);                \
    void register_library_only_##g(LibraryOnlyTable& t);
 
LINE_API_GROUP(pfqn_a)
LINE_API_GROUP(pfqn_b)
LINE_API_GROUP(mam)
LINE_API_GROUP(trace)
LINE_API_GROUP(misc)
LINE_API_GROUP(qsys)
LINE_API_GROUP(mc)
#undef LINE_API_GROUP
 
inline const std::vector<void (*)(DispatchTable&)>& api_dispatch_registrars() {
    static const std::vector<void (*)(DispatchTable&)> v = {
        &register_api_pfqn_a, &register_api_pfqn_b, &register_api_mam,
        &register_api_trace,  &register_api_misc,   &register_api_qsys,
        &register_api_mc,
    };
    return v;
}
 
inline const std::vector<void (*)(LibraryOnlyTable&)>& api_library_only_registrars() {
    static const std::vector<void (*)(LibraryOnlyTable&)> v = {
        &register_library_only_pfqn_a, &register_library_only_pfqn_b,
        &register_library_only_mam,    &register_library_only_trace,
        &register_library_only_misc,   &register_library_only_qsys,
        &register_library_only_mc,
    };
    return v;
}
 
}  // namespace reg
}  // namespace line
 
#endif  // LINE_REG_API_DISPATCH_DETAIL_H