Persistent mmap-backed representation of the provenance circuit. More...

#include "MMappedCircuit.h"

Collaboration diagram for MMappedCircuit:

[legend]

Public Member Functions
	MMappedCircuit (Oid db_oid, bool read_only=false)
	Open all four mmap backing files for the given database.
	~MMappedCircuit ()
	Sync all backing files before destruction.
void	createGate (pg_uuid_t token, gate_type type, const std::vector< pg_uuid_t > &children)
	Persist a new gate to the mmap store.
void	setInfos (pg_uuid_t token, unsigned info1, unsigned info2)
	Update the `info1` / `info2` annotations of a gate.
void	setExtra (pg_uuid_t token, const std::string &s)
	Attach a variable-length string annotation to a gate.
bool	setProb (pg_uuid_t token, double prob)
	Set the probability associated with a gate.
void	sync ()
	Flush all backing files to disk with `msync()`.
gate_type	getGateType (pg_uuid_t token) const
	Return the type of the gate identified by `token`.
std::vector< pg_uuid_t >	getChildren (pg_uuid_t token) const
	Return the child UUIDs of the gate identified by `token`.
double	getProb (pg_uuid_t token) const
	Return the probability stored for the gate identified by `token`.
std::pair< unsigned, unsigned >	getInfos (pg_uuid_t token) const
	Return the `info1` / `info2` pair for the gate `token`.
std::string	getExtra (pg_uuid_t token) const
	Return the variable-length string annotation for gate `token`.
unsigned long	getNbGates () const
	Return the total number of gates stored in the circuit.
void	setTableInfo (const ProvenanceTableInfo &info)
	Insert or update the `kind` / `block_key` half of a per-table metadata record, preserving any existing ancestor fields.
void	setTableAncestry (Oid relid, uint16_t ancestor_n, const Oid *ancestors)
	Insert or update the ancestor set of a per-table metadata record, preserving any existing `kind` / `block_key` fields.
void	removeTableInfo (Oid relid)
	Remove a per-table metadata entry (both halves).
void	removeTableAncestry (Oid relid)
	Clear just the ancestor set of a per-table metadata record, preserving `kind` / `block_key`.
bool	getTableInfo (Oid relid, ProvenanceTableInfo &out) const
	Look up the full per-table metadata record (both halves).
GenericCircuit	createGenericCircuit (pg_uuid_t token) const
	Build an in-memory `GenericCircuit` rooted at `token`.
GenericCircuit	createGenericCircuit (const std::vector< pg_uuid_t > &roots) const
	Build an in-memory `GenericCircuit` reachable from any of `roots`.

Static Public Attributes
static constexpr uint64_t	MAGIC_GATES
	8-byte magic constants identifying each mmap file type.
static constexpr uint64_t	MAGIC_WIRES
static constexpr uint64_t	MAGIC_MAPPING
static constexpr uint64_t	MAGIC_EXTRA
static constexpr uint64_t	MAGIC_TABLE_INFO

Private Member Functions
	MMappedCircuit (const std::string &mp, const std::string &gp, const std::string &wp, const std::string &ep, const std::string &tp, bool read_only)
	Delegating constructor that accepts pre-built paths.

Static Private Member Functions
static std::string	makePath (Oid db_oid, const char *filename)
	Build the full path for a mmap file under `$PGDATA/base/<db_oid>/`.

Private Attributes
MMappedUUIDHashTable	mapping
	UUID → gate-index hash table.
MMappedVector< GateInformation >	gates
	Gate metadata array.
MMappedVector< pg_uuid_t >	wires
	Flattened child UUID array.
MMappedVector< char >	extra
	Variable-length string data.
MMappedVector< ProvenanceTableInfo >	tableInfo
	Per-relation TID/BID metadata (safe-query optimisation).

Static Private Attributes
static constexpr const char *	GATES_FILENAME ="provsql_gates.mmap"
	Backing file for `gates`.
static constexpr const char *	WIRES_FILENAME ="provsql_wires.mmap"
	Backing file for `wires`.
static constexpr const char *	MAPPING_FILENAME ="provsql_mapping.mmap"
	Backing file for `mapping`.
static constexpr const char *	EXTRA_FILENAME ="provsql_extra.mmap"
	Backing file for `extra`.
static constexpr const char *	TABLE_INFO_FILENAME ="provsql_table_info.mmap"
	Backing file for `tableInfo`.

Detailed Description

Persistent mmap-backed representation of the provenance circuit.

MMappedCircuit is the single writer for circuit data; only the background worker should call its mutating methods. Reading methods may be called from any process that has mapped the files read-only.

Definition at line 90 of file MMappedCircuit.h.

Constructor & Destructor Documentation

◆ MMappedCircuit() [1/2]

MMappedCircuit::MMappedCircuit	(	const std::string &	mp,
		const std::string &	gp,
		const std::string &	wp,
		const std::string &	ep,
		const std::string &	tp,
		bool	read_only )

inlineprivate

Delegating constructor that accepts pre-built paths.

Definition at line 108 of file MMappedCircuit.h.

Here is the caller graph for this function:

◆ MMappedCircuit() [2/2]

MMappedCircuit::MMappedCircuit	(	Oid	db_oid,
		bool	read_only = false )

explicit

Open all four mmap backing files for the given database.

Parameters

db_oid	OID of the target database; files go under $PGDATA/base/<db_oid>/.
read_only	If `true`, all files are mapped read-only.

Definition at line 46 of file MMappedCircuit.cpp.

Here is the call graph for this function:

◆ ~MMappedCircuit()

MMappedCircuit::~MMappedCircuit ( )

inline

Sync all backing files before destruction.

Definition at line 144 of file MMappedCircuit.h.

Here is the call graph for this function:

Member Function Documentation

◆ createGate()

void MMappedCircuit::createGate	(	pg_uuid_t	token,
		gate_type	type,
		const std::vector< pg_uuid_t > &	children )

Persist a new gate to the mmap store.

Allocates a GateInformation record, appends the children to the wires vector, and records the UUID→index mapping. Existing gates with the same token are silently skipped.

Parameters

token	UUID identifying the new gate.
type	Gate type.
children	Ordered list of child gate UUIDs.

Definition at line 67 of file MMappedCircuit.cpp.

Here is the caller graph for this function:

◆ createGenericCircuit() [1/2]

GenericCircuit MMappedCircuit::createGenericCircuit ( const std::vector< pg_uuid_t > & roots ) const

Build an in-memory GenericCircuit reachable from any of roots.

Multi-root variant of createGenericCircuit. Seeds the BFS with every UUID in roots so a shared subgraph reachable from more than one root is represented by a single gate_t (the GenericCircuit::setGate / getGate pair is idempotent on the UUID key). Used by getJointCircuit to load an RV's sub-DAG together with a conditioning gate that sits above it in the persisted DAG.

Parameters

roots UUIDs whose reachable closure to load. Order is irrelevant; identical UUIDs collapse via the std::set deduplication of the work list.

Returns: An in-memory GenericCircuit containing every gate reachable from any root.

Definition at line 655 of file MMappedCircuit.cpp.

Here is the call graph for this function:

◆ createGenericCircuit() [2/2]

GenericCircuit MMappedCircuit::createGenericCircuit ( pg_uuid_t token ) const

Build an in-memory GenericCircuit rooted at token.

Performs a depth-first traversal of the mmap-backed circuit starting from token and copies all reachable gates and wires into a newly constructed GenericCircuit.

Parameters

token UUID of the root gate.

Returns: An in-memory GenericCircuit containing the sub-circuit.

Definition at line 650 of file MMappedCircuit.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getChildren()

std::vector< pg_uuid_t > MMappedCircuit::getChildren ( pg_uuid_t token ) const

Return the child UUIDs of the gate identified by token.

Parameters

token UUID of the gate.

Returns: Ordered vector of child UUIDs.

Definition at line 118 of file MMappedCircuit.cpp.

Here is the caller graph for this function:

◆ getExtra()

std::string MMappedCircuit::getExtra ( pg_uuid_t token ) const

Return the variable-length string annotation for gate token.

Parameters

token UUID of the gate.

Returns: The stored string, or empty if none.

Definition at line 183 of file MMappedCircuit.cpp.

Here is the caller graph for this function:

◆ getGateType()

gate_type MMappedCircuit::getGateType ( pg_uuid_t token ) const

Return the type of the gate identified by token.

Parameters

token UUID of the gate.

Returns: The gate's type, or gate_input if not found (lazy default).

Definition at line 109 of file MMappedCircuit.cpp.

Here is the caller graph for this function:

◆ getInfos()

std::pair< unsigned, unsigned > MMappedCircuit::getInfos ( pg_uuid_t token ) const

Return the info1 / info2 pair for the gate token.

Parameters

token UUID of the gate.

Returns: Pair {info1, info2}, or {0,0} if not found.

Definition at line 172 of file MMappedCircuit.cpp.

Here is the caller graph for this function:

◆ getNbGates()

unsigned long MMappedCircuit::getNbGates ( ) const

inline

Return the total number of gates stored in the circuit.

Returns: Total gate count.

Definition at line 229 of file MMappedCircuit.h.

Here is the caller graph for this function:

◆ getProb()

double MMappedCircuit::getProb ( pg_uuid_t token ) const

Return the probability stored for the gate identified by token.

Parameters

token UUID of the gate.

Returns: The probability, or 1.0 if the gate is not found.

Definition at line 142 of file MMappedCircuit.cpp.

Here is the caller graph for this function:

◆ getTableInfo()

bool MMappedCircuit::getTableInfo	(	Oid	relid,
		ProvenanceTableInfo &	out ) const

Look up the full per-table metadata record (both halves).

Parameters

relid	pg_class OID of the relation to look up.
out	On success, filled with the stored record.

Returns: true if a record was found, false otherwise.

Definition at line 626 of file MMappedCircuit.cpp.

Here is the caller graph for this function:

◆ makePath()

std::string MMappedCircuit::makePath	(	Oid	db_oid,
		const char *	filename )

staticprivate

Build the full path for a mmap file under $PGDATA/base/<db_oid>/.

Definition at line 41 of file MMappedCircuit.cpp.

Here is the caller graph for this function:

◆ removeTableAncestry()

void MMappedCircuit::removeTableAncestry ( Oid relid )

Clear just the ancestor set of a per-table metadata record, preserving kind / block_key.

No-op when relid has no existing record. Useful when a derived relation's source list changes (e.g. a CTAS is re-run) without disturbing its kind classification.

Definition at line 613 of file MMappedCircuit.cpp.

Here is the caller graph for this function:

◆ removeTableInfo()

void MMappedCircuit::removeTableInfo ( Oid relid )

Remove a per-table metadata entry (both halves).

No-op when relid is not present. Removal is done by tombstoning the matching entry with relid == InvalidOid; the next setTableInfo over the same relid reuses the slot.

Parameters

relid pg_class OID of the relation whose entry to remove.

Definition at line 600 of file MMappedCircuit.cpp.

Here is the caller graph for this function:

◆ setExtra()

void MMappedCircuit::setExtra	(	pg_uuid_t	token,
		const std::string &	s )

Attach a variable-length string annotation to a gate.

Parameters

token	UUID of the gate.
s	String to store.

Definition at line 161 of file MMappedCircuit.cpp.

Here is the caller graph for this function:

◆ setInfos()

void MMappedCircuit::setInfos	(	pg_uuid_t	token,
		unsigned	info1,
		unsigned	info2 )

Update the info1 / info2 annotations of a gate.

Parameters

token	UUID of the gate to update.
info1	New value for `info1`.
info2	New value for `info2`.

Definition at line 152 of file MMappedCircuit.cpp.

Here is the caller graph for this function:

◆ setProb()

bool MMappedCircuit::setProb	(	pg_uuid_t	token,
		double	prob )

Set the probability associated with a gate.

Parameters

token	UUID of the gate.
prob	Probability value in [0, 1].

Returns: true if the gate was updated; false if the token is a non-input gate. If the token is not yet in the circuit, an input gate is created lazily.

Definition at line 130 of file MMappedCircuit.cpp.

Here is the caller graph for this function:

◆ setTableAncestry()

void MMappedCircuit::setTableAncestry	(	Oid	relid,
		uint16_t	ancestor_n,
		const Oid *	ancestors )

Insert or update the ancestor set of a per-table metadata record, preserving any existing kind / block_key fields.

No-op when relid has no existing record: the safe-query rewriter only consults ancestry for tracked relations, so a caller setting ancestry on an unknown relation has missed a setTableInfo step. Callers in this codebase always set kind first.

Parameters

relid	pg_class OID of the relation to update.
ancestor_n	Number of valid entries in `ancestors` (must be `<=` `PROVSQL_TABLE_INFO_MAX_ANCESTORS`).
ancestors	Sorted, deduplicated base-relation OIDs.

Definition at line 576 of file MMappedCircuit.cpp.

Here is the caller graph for this function:

◆ setTableInfo()

void MMappedCircuit::setTableInfo ( const ProvenanceTableInfo & info )

Insert or update the kind / block_key half of a per-table metadata record, preserving any existing ancestor fields.

If an entry for info.relid already exists, its kind and block_key fields are overwritten in place and its ancestors fields are preserved. Otherwise a fresh record is appended with ancestor_n == 0.

Parameters

info	The record to store; only `kind` / `block_key` are consumed (`ancestor` fields are sourced from the existing entry or zeroed for fresh ones).

Definition at line 550 of file MMappedCircuit.cpp.

Here is the caller graph for this function:

◆ sync()

void MMappedCircuit::sync ( )

Flush all backing files to disk with msync().

Definition at line 522 of file MMappedCircuit.cpp.

Here is the caller graph for this function:

Member Data Documentation

◆ extra

MMappedVector<char> MMappedCircuit::extra

private

Variable-length string data.

Definition at line 95 of file MMappedCircuit.h.

◆ EXTRA_FILENAME

const char* MMappedCircuit::EXTRA_FILENAME ="provsql_extra.mmap"

staticconstexprprivate

Backing file for extra.

Definition at line 101 of file MMappedCircuit.h.

◆ gates

MMappedVector<GateInformation> MMappedCircuit::gates

private

Gate metadata array.

Definition at line 93 of file MMappedCircuit.h.

◆ GATES_FILENAME

const char* MMappedCircuit::GATES_FILENAME ="provsql_gates.mmap"

staticconstexprprivate

Backing file for gates.

Definition at line 98 of file MMappedCircuit.h.

◆ MAGIC_EXTRA

uint64_t MMappedCircuit::MAGIC_EXTRA

staticconstexpr

Initial value:

=
  uint64_t('P')       | uint64_t('v') <<  8 | uint64_t('S') << 16 | uint64_t('E') << 24 |
  uint64_t('x') << 32 | uint64_t('t') << 40 | uint64_t('r') << 48 | uint64_t('a') << 56

Definition at line 129 of file MMappedCircuit.h.

◆ MAGIC_GATES

uint64_t MMappedCircuit::MAGIC_GATES

staticconstexpr

Initial value:

=
  uint64_t('P')       | uint64_t('v') <<  8 | uint64_t('S') << 16 | uint64_t('G') << 24 |
  uint64_t('a') << 32 | uint64_t('t') << 40 | uint64_t('e') << 48 | uint64_t('s') << 56

8-byte magic constants identifying each mmap file type.

Definition at line 120 of file MMappedCircuit.h.

◆ MAGIC_MAPPING

uint64_t MMappedCircuit::MAGIC_MAPPING

staticconstexpr

Initial value:

=
  uint64_t('P')       | uint64_t('v') <<  8 | uint64_t('S') << 16 | uint64_t('M') << 24 |
  uint64_t('a') << 32 | uint64_t('p') << 40 | uint64_t('n') << 48 | uint64_t('g') << 56

Definition at line 126 of file MMappedCircuit.h.

◆ MAGIC_TABLE_INFO

uint64_t MMappedCircuit::MAGIC_TABLE_INFO

staticconstexpr

Initial value:

=
  uint64_t('P')       | uint64_t('v') <<  8 | uint64_t('S') << 16 | uint64_t('T') << 24 |
  uint64_t('b') << 32 | uint64_t('l') << 40 | uint64_t('I') << 48 | uint64_t('n') << 56

Definition at line 132 of file MMappedCircuit.h.

◆ MAGIC_WIRES

uint64_t MMappedCircuit::MAGIC_WIRES

staticconstexpr

Initial value:

=
  uint64_t('P')       | uint64_t('v') <<  8 | uint64_t('S') << 16 | uint64_t('W') << 24 |
  uint64_t('i') << 32 | uint64_t('r') << 40 | uint64_t('e') << 48 | uint64_t('s') << 56

Definition at line 123 of file MMappedCircuit.h.

◆ mapping

MMappedUUIDHashTable MMappedCircuit::mapping

private

UUID → gate-index hash table.

Definition at line 92 of file MMappedCircuit.h.

◆ MAPPING_FILENAME

const char* MMappedCircuit::MAPPING_FILENAME ="provsql_mapping.mmap"

staticconstexprprivate

Backing file for mapping.

Definition at line 100 of file MMappedCircuit.h.

◆ TABLE_INFO_FILENAME

const char* MMappedCircuit::TABLE_INFO_FILENAME ="provsql_table_info.mmap"

staticconstexprprivate

Backing file for tableInfo.

Definition at line 102 of file MMappedCircuit.h.

◆ tableInfo

MMappedVector<ProvenanceTableInfo> MMappedCircuit::tableInfo

private

Per-relation TID/BID metadata (safe-query optimisation).

Definition at line 96 of file MMappedCircuit.h.

◆ wires

MMappedVector<pg_uuid_t> MMappedCircuit::wires

private

Flattened child UUID array.

Definition at line 94 of file MMappedCircuit.h.

◆ WIRES_FILENAME

const char* MMappedCircuit::WIRES_FILENAME ="provsql_wires.mmap"

staticconstexprprivate

Backing file for wires.

Definition at line 99 of file MMappedCircuit.h.

The documentation for this class was generated from the following files:

/home/pierre/git/software/provsql/src/MMappedCircuit.h
/home/pierre/git/software/provsql/src/MMappedCircuit.cpp

Public Member Functions

Static Public Attributes

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ MMappedCircuit() [1/2]

◆ MMappedCircuit() [2/2]

◆ ~MMappedCircuit()

Member Function Documentation

◆ createGate()

◆ createGenericCircuit() [1/2]

◆ createGenericCircuit() [2/2]

◆ getChildren()

◆ getExtra()

◆ getGateType()

◆ getInfos()

◆ getNbGates()

◆ getProb()

◆ getTableInfo()

◆ makePath()

◆ removeTableAncestry()

◆ removeTableInfo()

◆ setExtra()

◆ setInfos()

◆ setProb()

◆ setTableAncestry()

◆ setTableInfo()

◆ sync()

Member Data Documentation

◆ extra

◆ EXTRA_FILENAME

◆ gates

◆ GATES_FILENAME

◆ MAGIC_EXTRA

◆ MAGIC_GATES

◆ MAGIC_MAPPING

◆ MAGIC_TABLE_INFO

◆ MAGIC_WIRES

◆ mapping

◆ MAPPING_FILENAME

◆ TABLE_INFO_FILENAME

◆ tableInfo

◆ wires

◆ WIRES_FILENAME