ProvSQL C/C++ API
Adding support for provenance and uncertainty management to PostgreSQL databases
Loading...
Searching...
No Matches
provsql_interrupt.h
Go to the documentation of this file.
1/**
2 * @file provsql_interrupt.h
3 * @brief Cancellation of the long C++ evaluation loops.
4 *
5 * A query cancel or a @c statement_timeout reaches the backend as a SIGINT.
6 * While an evaluation runs, the entry point installs
7 * @c provsql_sigint_handler, which sets @c provsql_interrupted (and PG's own
8 * cancel flags); the loops poll it with @c provsql_poll_interrupt and throw,
9 * unwinding the C++ stack (and freeing what it holds) instead of a
10 * @c longjmp through it. The entry point restores the previous handler,
11 * then lets @c CHECK_FOR_INTERRUPTS raise PG's native cancel (57014).
12 *
13 * An entry point does so as
14 * @code
15 * try {
16 * provsql_interrupt_scope interrupt_scope;
17 * ...
18 * } catch (const std::exception &e) {
19 * provsql_cancel_if_interrupted();
20 * provsql_error("...: %s", e.what());
21 * }
22 * @endcode
23 * the scope restoring the handler as the @c try is left.
24 *
25 * The same polls enforce @c provsql.max_memory: every few thousand of them,
26 * and at least every few tens of milliseconds (a loop may take few, costly
27 * steps), the backend's resident memory is compared with what it was at the
28 * first evaluation of the statement, and past the budget the evaluation
29 * stops with an error, as it does on a cancel.
30 * The handler is defined in @c provsql_interrupt.cpp.
31 */
32#ifndef PROVSQL_INTERRUPT_H
33#define PROVSQL_INTERRUPT_H
34
35#include "Circuit.h"
36
37extern "C" {
38/** Set by @c provsql_sigint_handler: this backend received a cancel. */
39extern bool provsql_interrupted;
40
41/**
42 * @brief Whether a @c provsql_interrupt_scope is alive: within a ProvSQL
43 * evaluation, where an error raised by @c longjmp would skip C++
44 * frames.
45 */
46bool provsql_in_evaluation(void);
47
48/**
49 * @brief SIGINT handler setting @c provsql_interrupted, and PG's cancel
50 * flags as PG's own @c StatementCancelHandler does.
51 */
53
54/**
55 * @brief SIGTERM handler setting @c provsql_interrupted, then running
56 * PG's own (@c die), so that a terminated backend stops its
57 * evaluation as a cancelled one does.
58 */
60
61/**
62 * @brief Raise PG's cancel if the evaluation stopped for one; nothing
63 * otherwise. Called in a @c catch, once the scope is gone.
64 */
66
67/** @c provsql.max_memory, in MB (0: no limit). */
68extern int provsql_max_memory;
69
70/** Polls since the last check of the memory budget. */
71extern unsigned provsql_poll_count;
72
73/**
74 * @brief Throw if the evaluations of the statement have made the backend's
75 * resident memory grow by more than @c provsql.max_memory.
76 */
77void provsql_check_memory(void);
78
79/**
80 * @brief Throw if @p extra more bytes would take the evaluations of the
81 * statement past @c provsql.max_memory: before a large copy, such
82 * as that of a result into a PostgreSQL value.
83 */
84void provsql_check_memory_for(size_t extra);
85
86/**
87 * @brief Whether the last check of the memory budget is old enough for
88 * another, whatever the number of polls since.
89 */
91
92/**
93 * @brief Throw if a text value of @p bytes is past what PostgreSQL can
94 * hold in a value (1 GB), with @p message as error: a rendering of
95 * a circuit, which writes out a sub-circuit shared by several gates
96 * at each of them, can grow exponentially with the circuit.
97 */
98void provsql_check_result_size(size_t bytes, const char *message);
99
100/** @brief Whether the evaluation stopped at a resource limit
101 * (@c provsql_limit_exceeded), not yet raised: a @c catch that would
102 * otherwise carry on must let it through. */
103bool provsql_limit_pending(void);
104
105/** @brief The size of the largest text value PostgreSQL holds, in bytes. */
106size_t provsql_max_result_size(void);
107
108/**
109 * @brief How much the backend's resident memory has grown since the first
110 * evaluation of the statement, in bytes (0 before it). An external
111 * tool's memory is counted against the same budget, added to this.
112 */
113size_t provsql_memory_used(void);
114
115/**
116 * @brief Stop the evaluation at a resource limit (@c provsql.max_memory,
117 * @c provsql.max_worlds): throws, like a cancel, after recording the
118 * limit, which @c provsql_cancel_if_interrupted then raises as a
119 * @c program_limit_exceeded error (54000) with @p tag on its DETAIL
120 * line and @p hint as its HINT, instead of an internal error.
121 */
122void provsql_limit_exceeded(const char *tag, const char *message,
123 const char *hint);
124}
125
126/**
127 * @brief The SIGINT handler installed for the lifetime of the object, the
128 * previous one restored as it ends (a C++ exception included).
129 */
131{
132 void (*prev_)(int); ///< The SIGINT handler to restore
133 void (*prev_term_)(int); ///< The SIGTERM handler to restore
134
135public:
140};
141
142
143/** @brief Throw where an evaluation is to stop, its query cancelled. */
145{
147 throw CircuitException("Interrupted");
148 if (provsql_max_memory > 0 &&
149 ((++provsql_poll_count & 4095) == 0 || provsql_memory_check_due()))
151}
152
153#endif /* PROVSQL_INTERRUPT_H */
Generic directed-acyclic-graph circuit template and gate identifier.
Exception type thrown by circuit operations on invalid input.
Definition Circuit.h:382
provsql_interrupt_scope & operator=(const provsql_interrupt_scope &)=delete
void(* prev_term_)(int)
The SIGTERM handler to restore.
void(* prev_)(int)
The SIGINT handler to restore.
provsql_interrupt_scope(const provsql_interrupt_scope &)=delete
bool provsql_interrupted
Set by provsql_sigint_handler: this backend received a cancel.
Definition provsql.c:111
int provsql_max_memory
Memory, in MB, that the evaluations of a statement may add to the backend's resident set,...
Definition provsql.c:131
unsigned provsql_poll_count
Polls since the last check of the memory budget.
void provsql_check_result_size(size_t bytes, const char *message)
Throw if a text value of bytes is past what PostgreSQL can hold in a value (1 GB),...
bool provsql_memory_check_due(void)
Whether the last check of the memory budget is old enough for another, whatever the number of polls s...
void provsql_sigint_handler(int)
SIGINT handler setting provsql_interrupted, and PG's cancel flags as PG's own StatementCancelHandler ...
bool provsql_limit_pending(void)
Whether the evaluation stopped at a resource limit (provsql_limit_exceeded), not yet raised: a catch ...
void provsql_cancel_if_interrupted(void)
Raise PG's cancel if the evaluation stopped for one; nothing otherwise.
void provsql_limit_exceeded(const char *tag, const char *message, const char *hint)
Stop the evaluation at a resource limit (provsql.max_memory, provsql.max_worlds): throws,...
void provsql_check_memory_for(size_t extra)
Throw if extra more bytes would take the evaluations of the statement past provsql....
size_t provsql_memory_used(void)
How much the backend's resident memory has grown since the first evaluation of the statement,...
size_t provsql_max_result_size(void)
The size of the largest text value PostgreSQL holds, in bytes.
void provsql_poll_interrupt()
Throw where an evaluation is to stop, its query cancelled.
void provsql_sigterm_handler(int)
SIGTERM handler setting provsql_interrupted, then running PG's own (die), so that a terminated backen...
bool provsql_in_evaluation(void)
Whether a provsql_interrupt_scope is alive: within a ProvSQL evaluation, where an error raised by lon...
void provsql_check_memory(void)
Throw if the evaluations of the statement have made the backend's resident memory grow by more than p...