ProvSQL C/C++ API
Adding support for provenance and uncertainty management to PostgreSQL databases
Loading...
Searching...
No Matches
MMappedCircuit.h File Reference

Persistent, mmap-backed storage for the full provenance circuit. More...

#include <cmath>
#include <cstddef>
#include <cstdint>
#include <cstring>
#include <exception>
#include <string>
#include <vector>
#include "GenericCircuit.h"
#include "FormulaRegions.h"
#include "MMappedUUIDHashTable.h"
#include "MMappedVector.hpp"
#include "provsql_utils.h"
Include dependency graph for MMappedCircuit.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  GateInformation
 Per-gate metadata stored in the gates MMappedVector. More...
class  MMappedCircuit
 Persistent mmap-backed representation of the provenance circuit. More...
struct  MMappedCircuit::Check
 What provsql.check_store() reports about a store. More...
struct  MMappedCircuit::Counts
 The size of a store, in the three units that matter. More...
class  CircuitBudgetExceeded
 Thrown by MMappedCircuit::createGenericCircuit when the circuit it builds takes the process past the memory budget it was given (provsql.max_memory, what the statement has not used of it). More...
class  CircuitCancelled
 Thrown by MMappedCircuit::createGenericCircuit when the statement that asked for the circuit is cancelled (provsql_store_cancel_requested). More...

Variables

constexpr unsigned long PROVSQL_CIRCUIT_OVER_BUDGET = ~0UL
 The size the worker answers a 'g' / 'j' request with, in place of a circuit, when building it went past the budget the request carried.
constexpr unsigned long PROVSQL_CIRCUIT_CANCELLED = ~0UL - 1
 The size the worker answers a 'g' / 'j' request with, in place of a circuit, when the requesting statement was cancelled.

Detailed Description

Persistent, mmap-backed storage for the full provenance circuit.

MMappedCircuit is the authoritative store for all provenance circuit data that must survive transaction boundaries and be accessible across multiple PostgreSQL backends. It composes three MMappedVector instances plus one MMappedUUIDHashTable:

Component Contents
mapping UUID → gate index (hash table)
gates GateInformation records, one per gate
wires Flattened child-UUID lists for all gates
extra Variable-length string data (e.g. provenance labels)

All four backing files live in the database's directory inside the PostgreSQL data directory, and are opened/created by the ProvSQL background worker on the first message for that database.

The free-function createGenericCircuit() traverses the mmap data starting from a given root UUID to construct an in-memory GenericCircuit for evaluation.

Warning
ON-DISK ABI: the layouts of GateInformation, of the gate_type enum (defined in provsql_utils.h), of pg_uuid_t, and of MMappedUUIDHashTable's slot structure are all serialised verbatim into the four provsql_*.mmap backing files. ProvSQL supports in-place extension upgrades (ALTER EXTENSION provsql UPDATE) only because these layouts have been stable since ProvSQL 1.0.0. Any change that adds, removes, reorders, or resizes a field – or that renumbers a gate_type enumerator – silently breaks every existing installation's on-disk mmap files. If such a change is necessary, bump an explicit format-version header in the mmap files, write a migration path, and call it out in a release note.

Definition in file MMappedCircuit.h.

Variable Documentation

◆ PROVSQL_CIRCUIT_CANCELLED

unsigned long PROVSQL_CIRCUIT_CANCELLED = ~0UL - 1
constexpr

The size the worker answers a 'g' / 'j' request with, in place of a circuit, when the requesting statement was cancelled.

Definition at line 526 of file MMappedCircuit.h.

◆ PROVSQL_CIRCUIT_OVER_BUDGET

unsigned long PROVSQL_CIRCUIT_OVER_BUDGET = ~0UL
constexpr

The size the worker answers a 'g' / 'j' request with, in place of a circuit, when building it went past the budget the request carried.

Definition at line 510 of file MMappedCircuit.h.