ProvSQL C/C++ API
Adding support for provenance and uncertainty management to PostgreSQL databases
Loading...
Searching...
No Matches
external_tool.h
Go to the documentation of this file.
1/**
2 * @file external_tool.h
3 * @brief Helpers for invoking external command-line tools.
4 *
5 * @c run_external_tool() runs a shell command line with the
6 * @c provsql.tool_search_path GUC, if set, prepended to @c $PATH for the
7 * duration of the call (the server's pre-existing @c PATH is restored
8 * afterwards). The command runs in its own process group so that a
9 * statement_timeout / pg_cancel_backend can stop it: on a pending cancel
10 * the whole group is @c SIGKILLed. Used by the d-DNNF compilers (d4, c2d,
11 * minic2d, dsharp), the model counters, and the graph-easy DOT renderer.
12 *
13 * @c find_external_tool() walks the same locations and reports whether a
14 * given binary is present and executable, so callers can fail with an
15 * actionable error before composing a command line.
16 *
17 * @c format_external_tool_status() decodes a @c system() return value
18 * into a human-readable message that distinguishes "tool not found"
19 * (shell exit 127), "tool not executable" (126), "killed by signal", and
20 * "ran and exited nonzero".
21 *
22 * A tool can be given a time limit with an @c ExternalToolTimeLimit scope:
23 * past it, the group is killed in the same way and @c run_external_tool
24 * throws @c ExternalToolTimeout.
25 *
26 * In the standalone @c tdkc build (when @c TDKC is defined) the GUC layer is
27 * unavailable; the helpers degenerate to a plain @c std::system() call and
28 * a no-op @c find_external_tool.
29 */
30#ifndef PROVSQL_EXTERNAL_TOOL_H
31#define PROVSQL_EXTERNAL_TOOL_H
32
33#include <string>
34
35#include "Circuit.h"
36
37#ifdef TDKC
38#include <cstdlib>
39inline int run_external_tool(const std::string &cmdline) {
40 return std::system(cmdline.c_str());
41}
42inline std::string find_external_tool(const std::string &) {
43 // No GUC layer in tdkc; assume present and let system() handle missing.
44 return "/dev/null";
45}
46inline std::string format_external_tool_status(int, const std::string &tool) {
47 return "Error executing " + tool;
48}
49#else
50/**
51 * @brief Run a shell command line in its own process group, optionally
52 * extending @c PATH, interruptible by query cancel / statement_timeout.
53 *
54 * If @c provsql_tool_search_path is non-empty, it is prepended (with @c :)
55 * to @c $PATH for the duration and restored afterwards. The command runs
56 * via @c /bin/sh @c -c as a process-group leader; while it runs the parent
57 * polls for a pending cancel/terminate and, if one fires, @c SIGKILLs the
58 * whole group (reaching tools that fork workers) and lets
59 * @c CHECK_FOR_INTERRUPTS raise it.
60 *
61 * @param cmdline Shell command line, passed verbatim to @c /bin/sh -c.
62 * @return A @c wait(2) status (decode with @c WIFEXITED etc., as a
63 * @c system() return), or -1 if @c fork failed.
64 */
65int run_external_tool(const std::string &cmdline);
66
67/**
68 * @brief Raised by @c run_external_tool when it stopped the tool for
69 * running past the time limit of the enclosing
70 * @c ExternalToolTimeLimit scope.
71 */
76
77/**
78 * @brief Scope within which an external tool is given a time limit.
79 *
80 * While an object of this class is alive, @c run_external_tool kills a
81 * tool (its whole process group, as on a cancel) that has run for more
82 * than the given time, and throws @c ExternalToolTimeout. The cost-based
83 * chooser of the probability methods uses it to hold an external compiler
84 * to the cost of the method it was preferred over; a tool run outside any
85 * such scope has no limit other than @c statement_timeout.
86 */
88public:
89 /// @param ms Time limit in milliseconds; 0 or less for no limit.
90 explicit ExternalToolTimeLimit(double ms);
94private:
95 double saved_; ///< Limit of the enclosing scope, restored on exit
96};
97
98/**
99 * @brief Locate an external tool by name.
100 *
101 * Searches @c provsql_tool_search_path (colon-separated), then @c $PATH, for
102 * an executable file matching @p name (via @c access(X_OK)). Returns the
103 * full path on success, or the empty string if nothing matches.
104 *
105 * Names containing a slash are treated as paths and tested directly without
106 * any directory walk.
107 *
108 * @param name Bare executable name (e.g. @c "d4") or a path.
109 * @return Resolved path, or @c "" if @p name is not found.
110 */
111std::string find_external_tool(const std::string &name);
112
113/**
114 * @brief Decode a @c system() return value into a human-readable message.
115 *
116 * @param rv Return value from @c system() (or @c run_external_tool()).
117 * @param tool Tool name, used as the message subject.
118 * @return Empty string when @p rv indicates success; otherwise a
119 * message that distinguishes "not found at runtime"
120 * (shell exit 127), "not executable" (126), "killed by
121 * signal N", "exited with status N", or @c system()
122 * itself failing.
123 */
124std::string format_external_tool_status(int rv, const std::string &tool);
125
126namespace provsql { struct ToolRecord; }
127
128/**
129 * @brief True iff a registry tool can currently be used.
130 *
131 * A @c kcmcp record needs a configured @c endpoint (no live connect probe,
132 * mirroring how a CLI tool only needs its binary on PATH). A @c cli record
133 * needs its @c binary (when set) and every dependency to resolve on the
134 * backend's PATH via @c find_external_tool. This is the single availability
135 * predicate consulted both by the compile/wmc tool selection and by the
136 * @c provsql.tools view.
137 */
138bool toolAvailable(const provsql::ToolRecord &rec);
139#endif
140
141#endif
Generic directed-acyclic-graph circuit template and gate identifier.
CircuitException(const std::string &m)
Construct with a descriptive error message.
Definition Circuit.h:390
ExternalToolTimeLimit(double ms)
double saved_
Limit of the enclosing scope, restored on exit.
ExternalToolTimeLimit(const ExternalToolTimeLimit &)=delete
ExternalToolTimeLimit & operator=(const ExternalToolTimeLimit &)=delete
Raised by run_external_tool when it stopped the tool for running past the time limit of the enclosing...
CircuitException(const std::string &m)
Construct with a descriptive error message.
Definition Circuit.h:390
int run_external_tool(const std::string &cmdline)
Run a shell command line in its own process group, optionally extending PATH, interruptible by query ...
std::string format_external_tool_status(int rv, const std::string &tool)
Decode a system() return value into a human-readable message.
bool toolAvailable(const provsql::ToolRecord &rec)
True iff a registry tool can currently be used.
std::string find_external_tool(const std::string &name)
Locate an external tool by name.
One registered external tool.