Home /Modules/idea/idea_system.hpp

idea_system.hpp

idea/idea_system.hpp · 163 line(s) · c

/*
 * idea_system.hpp -- Idea System(TM) C++ facade.
 *
 * Idea System(TM) / Idea(TM).  From Author; distributive.
 *
 * A thin, exception-light C++ layer over the C core (idea_system.h).  It gives
 * the VM / embedders an RAII handle (idea::System) and a small driver
 * (idea::SeriesRunner) that advances Time forward across the whole 0..30h
 * stream, so the special native code the Standard SLeeLa VM needs is available
 * from C++ without touching raw handles.  The State IS the System: callers
 * observe only what System::present() reports.
 */
#ifndef IDEA_SYSTEM_HPP
#define IDEA_SYSTEM_HPP

#include "idea_system.h"

#include <functional>
#include <string>
#include <utility>

namespace idea {

/* Mirror the C enums into the namespace for ergonomic C++ use. */
using StateKind = idea_state_kind;
using Status    = idea_status;
using Scheme    = idea_scheme;

/*
 * RAII owner of an idea_system*.  Movable, non-copyable (a System is a unique,
 * signal-distributed thing; you share a reference, you do not clone it).
 */
class System {
public:
    System() : sys_(idea_create()) {}
    ~System() { if (sys_) idea_destroy(sys_); }

    System(System &&other) noexcept : sys_(other.sys_) { other.sys_ = nullptr; }
    System &operator=(System &&other) noexcept {
        if (this != &other) {
            if (sys_) idea_destroy(sys_);
            sys_ = other.sys_;
            other.sys_ = nullptr;
        }
        return *this;
    }
    System(const System &) = delete;
    System &operator=(const System &) = delete;

    bool valid() const { return sys_ != nullptr; }
    idea_system *raw() const { return sys_; }

    /* ---- source / fetcher ---- */
    Status setSourceUrl(const std::string &url) {
        return idea_set_source_url(sys_, url.c_str());
    }
    std::string sourceUrl() const { return idea_source_url(sys_); }

    /*
     * Register a C++ fetcher.  The std::function is kept alive by this System
     * and trampolined through the C ABI.  Returns the bytes written, or a
     * negative Status, exactly like idea_fetch_fn.
     */
    using Fetcher = std::function<long(const std::string &url, char *buf, size_t cap)>;
    Status setFetcher(Fetcher fetcher) {
        fetcher_ = std::move(fetcher);
        return idea_set_fetcher(sys_, &System::trampoline, this);
    }

    /* ---- signal ---- */
    Status receiveSignal()                 { return idea_receive_signal(sys_); }
    Status feedHex(const std::string &hex) { return idea_feed_hex(sys_, hex.c_str()); }
    size_t signalLen() const               { return idea_signal_len(sys_); }

    /* ---- payload (what the Author's hex encodes) ---- */
    bool payloadValid() const   { return idea_payload_valid(sys_) != 0; }
    int  payloadVersion() const { return idea_payload_version(sys_); }
    bool isAuthored() const     { return idea_is_authored(sys_) != 0; }

    /* ---- series / time ---- */
    Status buildSeries()                   { return idea_build_series(sys_); }
    Status tick(long deltaSeconds)         { return idea_tick(sys_, deltaSeconds); }

    /* ---- presentation ---- */
    StateKind presentState() const         { return idea_present_state(sys_); }
    long      elapsedSeconds() const       { return idea_elapsed_seconds(sys_); }
    double    progress() const             { return idea_progress(sys_); }
    int       decisionsTaken() const       { return idea_decisions_taken(sys_); }
    int       seriesDepth() const          { return idea_series_depth(sys_); }
    bool      isCapable(const std::string &cap) const {
        return idea_is_capable(sys_, cap.c_str()) != 0;
    }
    std::string present() const {
        char buf[512];
        long n = idea_present(sys_, buf, sizeof(buf));
        return n > 0 ? std::string(buf, static_cast<size_t>(n)) : std::string();
    }

    /* ---- organization ---- */
    Status setScheme(Scheme s)             { return idea_set_scheme(sys_, s); }
    Scheme scheme() const                  { return idea_scheme_of(sys_); }
    Status addObjective(const std::string &o) { return idea_add_objective(sys_, o.c_str()); }
    int    objectiveCount() const          { return idea_objective_count(sys_); }

    /* ---- Canvas / Hz ---- */
    static double presentHz()   { return IDEA_CANVAS_PRESENT_HZ; }
    static double simHz()       { return IDEA_CANVAS_SIM_HZ; }
    static double simTimestep() { return idea_sim_timestep(); }
    static int    fixedSteps(double dt, double &acc) { return idea_fixed_steps(dt, &acc); }

    /* ---- names ---- */
    static std::string name(StateKind k) { return idea_state_name(k); }
    static std::string name(Status s)    { return idea_status_name(s); }
    static std::string name(Scheme s)    { return idea_scheme_name(s); }

private:
    static long trampoline(const char *url, char *buf, size_t cap, void *user) {
        auto *self = static_cast<System *>(user);
        if (!self || !self->fetcher_) return IDEA_INPUT_UNAVAILABLE;
        return self->fetcher_(url ? url : "", buf, cap);
    }

    idea_system *sys_;
    Fetcher      fetcher_;
};

/*
 * Drives a System forward through the entire Series.  Time is ultimate and
 * company to the Series: run() steps by a fixed cadence until Finality, and
 * reports each presented State to an optional observer.  It is consistent in
 * Time even when the System seems to loop/retry.
 */
class SeriesRunner {
public:
    using Observer = std::function<void(const System &)>;

    explicit SeriesRunner(System &sys, long stepSeconds = 3600)
        : sys_(sys), step_(stepSeconds > 0 ? stepSeconds : 1) {}

    /* Run to Finality, calling observer after each forward step.  Returns the
     * number of steps taken.  Guards against a runaway loop with a hard cap
     * derived from the 30h design goal. */
    int run(const Observer &observer = nullptr) {
        int steps = 0;
        const int cap = (IDEA_MAX_SECONDS / static_cast<int>(step_)) + 2;
        while (steps < cap) {
            Status st = sys_.tick(step_);
            if (observer) observer(sys_);
            ++steps;
            if (st == IDEA_EXHAUSTED) break;
        }
        return steps;
    }

private:
    System &sys_;
    long     step_;
};

} /* namespace idea */

#endif /* IDEA_SYSTEM_HPP */