provsql_mmap.h File Reference

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

#include "limits.h"
#include "postgres.h"
#include "provsql_utils.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(provsql_shared_state->pipebmr, &var, sizeof(type))-sizeof(type)>=0)
	Read one value of type from the background-to-main pipe.
#define	READB(var, type)   (read(provsql_shared_state->pipembr, &var, sizeof(type))-sizeof(type)>=0)
	Read one value of type from the main-to-background pipe.
#define	WRITEB(pvar, type)   (write(provsql_shared_state->pipembw, pvar, sizeof(type))!=-1)
	Write one value of type to the main-to-background pipe.
#define	WRITEM(pvar, type)   (write(provsql_shared_state->pipebmw, pvar, sizeof(type))!=-1)
	Write one value of type to the background-to-main pipe.
#define	STARTWRITEM()   (bufferpos=0)
	Reset the shared write buffer for a new batched write.
#define	ADDWRITEM(pvar, type)   (memcpy(buffer+bufferpos, pvar, sizeof(type)), bufferpos+=sizeof(type))
	Append one value of type to the shared write buffer.
#define	SENDWRITEM()   (write(provsql_shared_state->pipebmw, buffer, bufferpos)!=-1)
	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.

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
	)		(memcpy(buffer+bufferpos, pvar, sizeof(type)), bufferpos+=sizeof(type))

Append one value of type to the shared write buffer.

Definition at line 88 of file provsql_mmap.h.

READB

#define READB	(		var,
			type
	)		(read(provsql_shared_state->pipembr, &var, sizeof(type))-sizeof(type)>=0)

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

Definition at line 79 of file provsql_mmap.h.

READM

#define READM	(		var,
			type
	)		(read(provsql_shared_state->pipebmr, &var, sizeof(type))-sizeof(type)>=0)

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

Definition at line 77 of file provsql_mmap.h.

SENDWRITEM

#define SENDWRITEM

(

)

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

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

Definition at line 90 of file provsql_mmap.h.

STARTWRITEM

#define STARTWRITEM

(

)

(bufferpos=0)

Reset the shared write buffer for a new batched write.

Definition at line 86 of file provsql_mmap.h.

WRITEB

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

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

Definition at line 81 of file provsql_mmap.h.

WRITEM

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

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

Definition at line 83 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 43 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 38 of file MMappedCircuit.cpp.

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 148 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

)

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.

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 62 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 44 of file provsql_mmap.c.

bufferpos

unsigned bufferpos

extern

Current write position within buffer.

Definition at line 45 of file provsql_mmap.c.