sym_engines.h File Reference

Resolves the symbolic backend to use, and owns the container that serves it. More...

#include <cctype>
#include <cstddef>
#include <cstdlib>
#include <cstring>
#include <ctime>
#include <iostream>
#include <memory>
#include <mutex>
#include <string>
#include <vector>
#include <netinet/in.h>
#include <sys/socket.h>
#include <unistd.h>
#include "line/api/sym/sage_rest_engine.h"
#include "line/api/sym/sym_engine.h"
#include "line/io/docker_image.h"
#include "line/util/error.h"
#include "line/util/subprocess.h"

Include dependency graph for sym_engines.h:

Go to the source code of this file.

Namespaces
namespace	line
namespace	line::sym

Functions
std::vector< std::string >	line::sym::sym_docker_image_candidates ()
	Fallback tags, tried in order after SYM_DOCKER_IMAGE.
std::vector< int >	line::sym::sym_probe_ports ()
	Ports probed for an already running service, in order.
void	line::sym::sym_stop_container ()
	Stops the container started by this process, if any.
std::string	line::sym::sym_find_image ()
std::shared_ptr< SymEngine >	line::sym::sym_resolve (const std::string &requested="auto")
	Resolves an engine.

Variables
const char *const	line::sym::SYM_DOCKER_IMAGE = "imperialqore/line-sage-rest:latest"
	Image serving the symbolic REST API.
const char *const	line::sym::SYM_URL_ENV = "LINE_SAGE_URL"
	Environment variable naming a service to use.
constexpr int	line::sym::SYM_STARTUP_TIMEOUT_SECONDS = 120
	Seconds to wait for a container to report healthy.

Detailed Description

Resolves the symbolic backend to use, and owns the container that serves it.

Port of jline.api.sym.SymEngines. Resolution order, the same in MATLAB (SAGE.m), the JAR and Python (line_solver.api.sym):

1. an explicit URL, from solver options or the requested argument;
2. the LINE_SAGE_URL environment variable;
3. a line-sage-rest service already listening on a conventional port;
4. a container started here from a locally present image;
5. nothing, in which case the caller keeps whatever native algebra it has, or reports that no backend is configured.

STEP 3 VERIFIES IDENTITY THROUGH /api/v1/info rather than trusting the port: every imperialqore line-*-rest service listens on 8080 by convention, so a health probe alone would happily accept the LQNS service and then fail on the first symbolic request with an unrecognizable error.

The container started in step 4 is reused for the life of the process and stopped by an atexit handler. It is bound to an ephemeral host port, so several processes, or a process alongside a hand-started service, do not collide. An atexit handler does NOT run on a signal or on _exit, so a container may outlive a killed process; docker ps shows it under the name line-sage-rest-<port> and it was started with –rm, so stopping it removes it.

A PULL HAPPENS ONLY ON EXPLICIT OPT-IN, i.e. the "sage" keyword or a named image. Bare "auto"/"true"/"" keep the native backend unless the image is already local, so leaving the symbolic option on auto never triggers a multi-gigabyte download, and the pull itself is refused when the Docker storage location is short of space (see line/io/docker_image.h).

DIVERGENCE FROM THE JAR: an https:// URL is refused by name rather than used, because this port's HTTP client has no TLS (see line/util/http.h). Refusing loudly is the point – reporting "no backend" for a service that is up and merely unreachable over plaintext would send the caller looking in the wrong place.

Definition in file sym_engines.h.