MMappedCircuit.h File Reference

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

#include <cstdint>
#include <string>
#include <vector>
#include "GenericCircuit.h"
#include "MMappedTableInfo.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...

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 PostgreSQL data directory and are opened/created by the ProvSQL background worker at startup.

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.