provsql_mmap.h File Reference

Background worker and IPC primitives for mmap-backed circuit storage. More...

#include "limits.h"
#include <unistd.h>
#include "postgres.h"
#include "provsql_utils.h"
#include "provsql_config.h"

Include dependency graph for provsql_mmap.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	READM(var, type)
	Read one value of type from the background-to-main pipe.
#define	READB(var, type)
	Read one value of type from the main-to-background pipe.
#define	WRITEB(pvar, type)
	Write one value of type to the main-to-background pipe.
#define	WRITEM(pvar, type)
	Write one value of type to the background-to-main pipe.
#define	READB_BYTES(ptr, n)
	Read exactly n bytes of a reply from the main-to-background pipe.
#define	READM_BYTES(ptr, n)
	Read exactly n bytes of a request from the background-to-main pipe.
#define	WRITEB_BYTES(ptr, n)
	Write n reply bytes to the main-to-background pipe.
#define	STARTWRITEM()
	Reset the shared write buffer for a new batched write.
#define	ADDWRITEM(pvar, type)
	Append one value of type to the shared write buffer.
#define	SENDWRITEM()
	Flush the shared write buffer to the background-to-main pipe atomically.

Functions
void	provsql_mmap_worker (Datum)
	Entry point for the ProvSQL mmap background worker.
void	RegisterProvSQLMMapWorker (void)
	Register the ProvSQL mmap background worker with PostgreSQL.
void	initialize_provsql_mmap (void)
	Open (or create) the mmap files and initialise the circuit store.
void	destroy_provsql_mmap (void)
	Unmap and close the mmap files.
void	provsql_mmap_main_loop (void)
	Main processing loop of the mmap background worker.
void	provsql_mmap_dispatch (char c, Oid db_oid)
	Handle a single IPC message: read its payload and write its reply.
void	provsql_internal_create_gate (const pg_uuid_t *token, gate_type type, unsigned nb_children, const pg_uuid_t *children_data)
	Create a gate from in-extension C/C++ code (cache + worker IPC).
bool	provsql_internal_set_prob (const pg_uuid_t *token, double prob)
	Set an input gate's probability from in-extension C/C++ code.
void	provsql_internal_set_infos (const pg_uuid_t *token, unsigned info1, unsigned info2)
	Set a gate's info fields from in-extension C/C++ code.
void	provsql_internal_set_extra (const pg_uuid_t *token, const char *str)
	Set a gate's extra string from in-extension C/C++ code.
bool	provsql_read_all (int fd, void *dst, size_t n)
	Read exactly n bytes from fd into dst; false on EOF/error.

Variables
char	buffer [PIPE_BUF]
	Shared write buffer used with STARTWRITEM / ADDWRITEM / SENDWRITEM.
unsigned	bufferpos
	Current write position within buffer.

Detailed Description

Background worker and IPC primitives for mmap-backed circuit storage.

ProvSQL persists the provenance circuit in memory-mapped files so that data survives transaction boundaries and is shared across backend processes. Because multiple backends may create gates concurrently, a dedicated PostgreSQL background worker (provsql_mmap_worker) is the sole writer to those files; normal backends communicate with it through a pair of anonymous pipes described in provsqlSharedState.

This header exposes:

• Functions to register, start, and manage the background worker.
• A set of pipe I/O macros (READM, READB, WRITEB, WRITEM) that wrap read()/write() calls on the inter-process pipes.
• A buffered-write interface (STARTWRITEM, ADDWRITEM, SENDWRITEM) that batches multiple fields into a single write() to stay within the atomic PIPE_BUF guarantee.

Definition in file provsql_mmap.h.

Macro Definition Documentation

ADDWRITEM

#define ADDWRITEM	(		pvar,
			type )

Value:

(memcpy(buffer+bufferpos, pvar, sizeof(type)), bufferpos+=sizeof(type))

Append one value of type to the shared write buffer.

Definition at line 194 of file provsql_mmap.h.

READB

#define READB	(		var,
			type )

Value:

(read(provsql_shared_state->pipembr, &var, sizeof(type))==(ssize_t)sizeof(type))

Read one value of type from the main-to-background pipe.

Definition at line 178 of file provsql_mmap.h.

READB_BYTES

#define READB_BYTES	(		ptr,
			n )

Value:

provsql_read_all(provsql_shared_state->pipembr, (ptr), (n))

Read exactly n bytes of a reply from the main-to-background pipe.

Definition at line 185 of file provsql_mmap.h.

READM

#define READM	(		var,
			type )

Value:

(read(provsql_shared_state->pipebmr, &var, sizeof(type))==(ssize_t)sizeof(type))

Read one value of type from the background-to-main pipe.

Definition at line 176 of file provsql_mmap.h.

READM_BYTES

#define READM_BYTES	(		ptr,
			n )

Value:

provsql_read_all(provsql_shared_state->pipebmr, (ptr), (n))

Read exactly n bytes of a request from the background-to-main pipe.

Definition at line 187 of file provsql_mmap.h.

SENDWRITEM

#define SENDWRITEM

(

)

Value:

(write(provsql_shared_state->pipebmw, buffer, bufferpos)!=-1)

Flush the shared write buffer to the background-to-main pipe atomically.

Definition at line 196 of file provsql_mmap.h.

STARTWRITEM

#define STARTWRITEM

(

)

Value:

(bufferpos=0)

Reset the shared write buffer for a new batched write.

Definition at line 192 of file provsql_mmap.h.

WRITEB

#define WRITEB	(		pvar,
			type )

Value:

(write(provsql_shared_state->pipembw, pvar, sizeof(type))!=-1)

Write one value of type to the main-to-background pipe.

Definition at line 180 of file provsql_mmap.h.

WRITEB_BYTES

#define WRITEB_BYTES	(		ptr,
			n )

Value:

(write(provsql_shared_state->pipembw, (ptr), (n))!=-1)

Write n reply bytes to the main-to-background pipe.

Definition at line 189 of file provsql_mmap.h.

WRITEM

#define WRITEM	(		pvar,
			type )

Value:

(write(provsql_shared_state->pipebmw, pvar, sizeof(type))!=-1)

Write one value of type to the background-to-main pipe.

Definition at line 182 of file provsql_mmap.h.

Function Documentation

destroy_provsql_mmap()

void destroy_provsql_mmap

(

void

)

Unmap and close the mmap files.

Called by the background worker on shutdown to release resources and ensure all dirty pages are synced to disk via msync().

Definition at line 60 of file MMappedCircuit.cpp.

Here is the caller graph for this function:

initialize_provsql_mmap()

void initialize_provsql_mmap

(

void

)

Open (or create) the mmap files and initialise the circuit store.

Called once by the background worker at startup. Creates the four mmap-backed data files if they do not yet exist and maps them into the worker's address space.

Definition at line 55 of file MMappedCircuit.cpp.

Here is the caller graph for this function:

provsql_internal_create_gate()

void provsql_internal_create_gate	(	const pg_uuid_t *	token,
		gate_type	type,
		unsigned	nb_children,
		const pg_uuid_t *	children_data )

Create a gate from in-extension C/C++ code (cache + worker IPC).

Internal entry point behind the SQL-callable create_gate(), without Datum marshalling or gate-type-OID lookups; idempotent on already-mapped tokens.

Parameters

token	UUID of the gate.
type	Gate type.
nb_children	Number of children.
children_data	Child UUIDs (may be NULL when nb_children is 0).

Create a gate from in-extension C/C++ code (cache + worker IPC).

Factored out of the SQL-callable wrapper so in-extension C/C++ code (e.g. the decomposition-aligned reachability materialiser) can create gates without Datum marshalling or gate-type-OID lookups. Same semantics: write-through to the per-session cache, then the C message to the background worker; MMappedCircuit::createGate is idempotent on already-mapped tokens.

Definition at line 214 of file provsql_mmap.c.

Here is the call graph for this function:

Here is the caller graph for this function:

provsql_internal_set_extra()

void provsql_internal_set_extra	(	const pg_uuid_t *	token,
		const char *	str )

Set a gate's extra string from in-extension C/C++ code.

Internal entry point behind the SQL-callable set_extra().

Parameters

token	UUID of the gate.
str	NUL-terminated extra string to attach.

Set a gate's extra string from in-extension C/C++ code.

Definition at line 406 of file provsql_mmap.c.

Here is the call graph for this function:

Here is the caller graph for this function:

provsql_internal_set_infos()

void provsql_internal_set_infos	(	const pg_uuid_t *	token,
		unsigned	info1,
		unsigned	info2 )

Set a gate's info fields from in-extension C/C++ code.

Internal entry point behind the SQL-callable set_infos().

Parameters

token	UUID of the gate.
info1	First (gate-type-specific) info value.
info2	Second info value.

Set a gate's info fields from in-extension C/C++ code.

Definition at line 308 of file provsql_mmap.c.

Here is the call graph for this function:

Here is the caller graph for this function:

provsql_internal_set_prob()

bool provsql_internal_set_prob	(	const pg_uuid_t *	token,
		double	prob )

Set an input gate's probability from in-extension C/C++ code.

Internal entry point behind the SQL-callable set_prob().

Parameters

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

Returns

False if the worker rejected it (the token is not an input gate); true on success.

Set an input gate's probability from in-extension C/C++ code.

Returns whether the worker accepted the probability (false on a non-input gate).

Definition at line 287 of file provsql_mmap.c.

Here is the call graph for this function:

Here is the caller graph for this function:

provsql_mmap_dispatch()

void provsql_mmap_dispatch	(	char	c,
		Oid	db_oid )

Handle a single IPC message: read its payload and write its reply.

The opcode c and database OID db_oid have already been consumed by the caller. Shared by the background-worker main loop (multi-process build) and the synchronous in-process dispatcher.

Definition at line 225 of file MMappedCircuit.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

provsql_mmap_main_loop()

void provsql_mmap_main_loop

(

void

)

Main processing loop of the mmap background worker.

Waits for gate-creation requests from backend processes, processes them by writing to the mmap files, and handles SIGTERM for graceful shutdown.

Definition at line 542 of file MMappedCircuit.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

provsql_mmap_worker()

void provsql_mmap_worker

(

Datum

ignored

)

Entry point for the ProvSQL mmap background worker.

Called by the postmaster when it launches the background worker. Enters the main loop (provsql_mmap_main_loop()) and never returns normally. The single Datum argument is required by the background-worker API but is not used.

Definition at line 89 of file provsql_mmap.c.

Here is the call graph for this function:

provsql_read_all()

bool provsql_read_all	(	int	fd,
		void *	dst,
		size_t	n )

Read exactly n bytes from fd into dst; false on EOF/error.

Definition at line 75 of file provsql_mmap.c.

RegisterProvSQLMMapWorker()

void RegisterProvSQLMMapWorker

(

void

)

Register the ProvSQL mmap background worker with PostgreSQL.

Must be called from the extension's _PG_init() function so that the postmaster starts the worker on the next connection.

Definition at line 102 of file provsql_mmap.c.

Here is the caller graph for this function:

Variable Documentation

buffer

char buffer[PIPE_BUF]

extern

Shared write buffer used with STARTWRITEM / ADDWRITEM / SENDWRITEM.

Definition at line 72 of file provsql_mmap.c.

bufferpos

unsigned bufferpos

extern

Current write position within buffer.

Definition at line 73 of file provsql_mmap.c.