ldes_probe.h

Go to the documentation of this file.

/*
 * Copyright (c) 2012-2026, QORE Lab, Imperial College London
 * All rights reserved.
 */
#ifndef LINE_SOLVERS_WRAPPERS_LDES_LDES_PROBE_H
#define LINE_SOLVERS_WRAPPERS_LDES_LDES_PROBE_H
 
/**
 * @file
 * @ingroup line_solvers
 * Where the LDES engine is, and whether this machine can run it.
 *
 * Its own header, small enough for SolverAUTO to include: LDES leads several of
 * the reference's rankings, and the chooser needs to know whether the slot has
 * an engine behind it without taking on the client, the result parser and the
 * HTTP transport. This is `lqns_probe.h`'s reason, and the same shape.
 *
 * THE ANSWER IS CACHED for the life of the process: a binary does not appear or
 * vanish mid-run, and the probe stats several directories and reads an ELF
 * header, which SolverAUTO would otherwise repeat on every choice it makes.
 *
 * TWO IMAGES, ONE ENGINE. `common/ldes` is an AOT GraalVM build and
 * `common/ldes.jar` the same engine on a JVM; the AOT image starts faster and
 * lacks the reflective features the JVM has, so the client tries it first and
 * falls through. A binary built for ANOTHER CPU is skipped rather than run --
 * the ELF e_machine says so before exec does -- because the fall-through then
 * still has the jar to reach, while an exec failure would look like an engine
 * failure. When either architecture is unknown the binary is used as a best
 * effort: an unknown is not evidence of a mismatch.
 */
 
#include <cstdlib>
#include <fstream>
#include <string>
#include <vector>
 
#include <sys/stat.h>
#include <sys/utsname.h>
#include <unistd.h>
 
namespace line {
namespace ldes {
 
namespace detail {
 
inline bool is_file(const std::string& p) {
    struct stat st;
    return !p.empty() && ::stat(p.c_str(), &st) == 0 && S_ISREG(st.st_mode);
}
 
inline bool is_exec(const std::string& p) {
    return is_file(p) && ::access(p.c_str(), X_OK) == 0;
}
 
inline std::string env_or_empty(const char* name) {
    const char* v = std::getenv(name);
    return v != nullptr ? std::string(v) : std::string();
}
 
/** The directory holding this executable, or empty when it cannot be read. */
inline std::string exe_dir() {
    char buf[4096];
    const ssize_t n = ::readlink("/proc/self/exe", buf, sizeof(buf) - 1);
    if (n <= 0) return std::string();
    const std::string p(buf, static_cast<std::size_t>(n));
    const std::size_t s = p.find_last_of('/');
    return s == std::string::npos ? std::string() : p.substr(0, s);
}
 
inline std::string cwd_path() {
    char buf[4096];
    return ::getcwd(buf, sizeof(buf)) != nullptr ? std::string(buf) : std::string();
}
 
/**
 * Where `common/` may be, in preference order.
 *
 * The two other clients resolve it from a package path (Python) or from the
 * `jline.jar` entry on the Java classpath (MATLAB); a C++ binary has neither, so
 * it looks where it actually sits -- `common/line-cli` in an install, a build
 * directory otherwise -- and then ascends, trying each ancestor and each
 * ancestor's `common/`. `$LINE_LDES_DIR` overrides all of it, for a caller
 * running an engine from somewhere else entirely.
 */
inline std::vector<std::string> engine_dirs() {
    std::vector<std::string> out;
    // `$LINE_LDES_DIR` is AUTHORITATIVE, not merely first: a caller who named a
    // directory and named a wrong one is told there is no engine, rather than
    // silently served the one beside the binary -- which is `$LINE_JAVA`'s rule
    // in the Python client, and the difference between running the engine you
    // asked for and running a different one.
    const std::string forced = env_or_empty("LINE_LDES_DIR");
    if (!forced.empty()) {
        out.push_back(forced);
        return out;
    }
    const std::string roots[2] = {exe_dir(), cwd_path()};
    for (int r = 0; r < 2; ++r) {
        if (roots[r].empty()) continue;
        std::string dir = roots[r];
        for (int k = 0; k < 7; ++k) {
            out.push_back(dir);
            out.push_back(dir + "/common");
            dir += "/..";
        }
    }
#ifdef LINE_LDES_BUILD_DIR
    // Last: where cmake put the `ldes` target, so a program linking line_mp_api from its own build tree finds it.
    out.push_back(LINE_LDES_BUILD_DIR);
#endif
    return out;
}
 
/** The first candidate directory that holds an engine, or empty. */
inline std::string find_engine_dir_uncached() {
    const std::vector<std::string> cand = engine_dirs();
    for (std::size_t i = 0; i < cand.size(); ++i)
        if (is_file(cand[i] + "/ldes.jar") || is_file(cand[i] + "/ldes")) return cand[i];
    return std::string();
}
 
// ELF e_machine identifiers (header offset 0x12, two bytes).
static const int EM_386_ID = 0x03;
static const int EM_ARM_ID = 0x28;
static const int EM_X86_64_ID = 0x3E;
static const int EM_AARCH64_ID = 0xB7;
 
/** The ELF e_machine of a binary, or 0 when the file is not an ELF. */
inline int elf_machine(const std::string& path) {
    std::ifstream in(path.c_str(), std::ios::binary);
    if (!in) return 0;
    unsigned char h[20];
    in.read(reinterpret_cast<char*>(h), 20);
    if (in.gcount() < 20) return 0;
    if (!(h[0] == 0x7F && h[1] == 'E' && h[2] == 'L' && h[3] == 'F')) return 0;
    return h[5] == 1 ? (h[18] | (h[19] << 8)) : ((h[18] << 8) | h[19]);
}
 
/** The e_machine this host runs, or 0 when the name is not one we map. */
inline int host_elf_machine() {
    struct utsname u;
    if (::uname(&u) != 0) return 0;
    const std::string m(u.machine);
    if (m == "x86_64" || m == "amd64") return EM_X86_64_ID;
    if (m == "aarch64" || m == "arm64") return EM_AARCH64_ID;
    if (m == "i386" || m == "i486" || m == "i586" || m == "i686" || m == "x86") return EM_386_ID;
    if (m.compare(0, 3, "arm") == 0) return EM_ARM_ID;
    return 0;
}
 
/**
 * A runnable native binary in `dir`, or empty.
 *
 * `$LINE_LDES_FORCE_JAR` is the escape hatch for a prebuilt image that is stale
 * against the sources: the flag exists in the Python client for the same reason.
 */
inline std::string native_ldes_path(const std::string& dir) {
    if (dir.empty()) return std::string();
    if (!env_or_empty("LINE_LDES_FORCE_JAR").empty()) return std::string();
    const std::string cand = dir + "/ldes";
    if (!is_exec(cand)) return std::string();
    const int host = host_elf_machine();
    const int bin = elf_machine(cand);
    if (host != 0 && bin != 0 && host != bin) return std::string();
    return cand;
}
 
/** True when a native binary is present but built for another CPU. */
inline bool incompatible_native(const std::string& dir) {
    if (dir.empty()) return false;
    const std::string cand = dir + "/ldes";
    if (!is_file(cand)) return false;
    const int host = host_elf_machine();
    const int bin = elf_machine(cand);
    return host != 0 && bin != 0 && host != bin;
}
 
/**
 * A runnable java launcher, or empty.
 *
 * `$LINE_JAVA` is AUTHORITATIVE when set: a caller who named a JVM and named a
 * wrong one is told so rather than silently served another. Then
 * `$JAVA_HOME/bin/java`, then PATH -- the order the JAR dispatch uses, so one
 * setting serves every wrapper.
 */
inline std::string find_java() {
    const std::string forced = env_or_empty("LINE_JAVA");
    if (!forced.empty()) return is_exec(forced) ? forced : std::string();
    const std::string home = env_or_empty("JAVA_HOME");
    if (!home.empty() && is_exec(home + "/bin/java")) return home + "/bin/java";
    const std::string path = env_or_empty("PATH");
    std::size_t b = 0;
    while (b <= path.size()) {
        const std::size_t e = path.find(':', b);
        const std::string dir = path.substr(b, e == std::string::npos ? std::string::npos : e - b);
        if (!dir.empty() && is_exec(dir + "/java")) return dir + "/java";
        if (e == std::string::npos) break;
        b = e + 1;
    }
    return std::string();
}
 
/**
 * The message for a host with neither a usable image nor a JVM.
 *
 * IT NAMES WHICH OF THE THREE IT IS -- no engine directory at all, an engine
 * built for another CPU with no JVM behind it, or a directory with no jar --
 * because the three want different things done, and a message that blamed the
 * JVM for a missing jar sends the reader to install one they already have.
 */
inline std::string no_backend_message(const std::string& dir) {
    struct utsname u;
    const std::string host =
        ::uname(&u) == 0 ? std::string(u.sysname) + "/" + u.machine : std::string("this host");
    const bool have_java = !find_java().empty();
    std::string why;
    if (dir.empty()) {
        const std::string forced = env_or_empty("LINE_LDES_DIR");
        why = forced.empty()
                  ? "no LDES engine was found beside this executable or under the working "
                    "directory (looking for `ldes` or `ldes.jar` in each ancestor and its "
                    "`common/`)"
                  : "$LINE_LDES_DIR names '" + forced +
                        "', which holds neither `ldes` nor `ldes.jar`";
    } else if (incompatible_native(dir)) {
        why = "the native LDES binary in '" + dir +
              "' was built for a different CPU architecture than this host (" + host + ")" +
              (have_java ? ", and there is no ldes.jar beside it to run instead"
                         : ", and no Java runtime was found to run ldes.jar");
    } else {
        why = "'" + dir + "' holds no runnable engine for this host (" + host + ")" +
              (have_java ? "" : " and no Java runtime was found to run ldes.jar");
    }
    if (dir.empty() || !have_java)
        return "cannot run SolverLDES: " + why +
               ". Build the native engine (`cmake --build <build-dir> --target ldes`) and point "
               "$LINE_LDES_DIR at the directory holding `ldes` when it is not beside the executable; "
               "to run `ldes.jar` instead, install a JRE/JDK 8 or newer and put `java` on PATH, or set "
               "$LINE_JAVA or $JAVA_HOME";
    return "cannot run SolverLDES: " + why +
           ". Point $LINE_LDES_DIR at a directory holding an `ldes` built for this host or an `ldes.jar`";
}
 
}  // namespace detail
 
/** The directory holding the engine, or empty when there is none. */
inline const std::string& ldes_engine_dir() {
    static const std::string dir = detail::find_engine_dir_uncached();
    return dir;
}
 
/** True when this machine can run the engine at all, by either image. */
inline bool ldes_is_available() {
    static const bool ok = !ldes_engine_dir().empty() &&
                           (!detail::native_ldes_path(ldes_engine_dir()).empty() ||
                            (!detail::find_java().empty() &&
                             detail::is_file(ldes_engine_dir() + "/ldes.jar")));
    return ok;
}
 
}  // namespace ldes
}  // namespace line
 
#endif  // LINE_SOLVERS_WRAPPERS_LDES_LDES_PROBE_H