ngen::serialization::FileBackend Class Reference

#include <file_backend.hpp>

Inheritance diagram for ngen::serialization::FileBackend:

Collaboration diagram for ngen::serialization::FileBackend:

Classes
class	Index
class	Reader
class	Writer

Public Member Functions
	~FileBackend () override
auto	writer (std::chrono::system_clock::time_point epoch, Durability durability) -> expected< std::unique_ptr< RecordBackend::Writer >, BackendError > override
	Construct a Writer for one checkpoint event.
auto	reader (IdPredicate read_scope={}) -> expected< std::unique_ptr< RecordBackend::Reader >, BackendError > override
	Construct a Reader scoped to records whose id satisfies in_scope.
auto	finalize () -> expected< void, std::vector< BackendError > > override
	Lifecycle hook for cross-event cleanup: close process-level open handles, drain async queues, surface deferred errors.
const std::string &	path () const noexcept
	Path the backend was constructed against.
template<typename F >
auto	with_writer (std::chrono::system_clock::time_point epoch, Durability durability, F &&fn) -> expected< void, BackendError >
	Run fn inside a scoped Writer; calls commit() automatically on success.
template<typename F >
auto	with_reader (IdPredicate in_scope, F &&fn) -> expected< void, BackendError >
	Run fn inside a scoped Reader; calls close() automatically on success.

Static Public Member Functions
static auto	create (std::string path, IdPredicate index_scope={}) -> std::shared_ptr< FileBackend >
	Get-or-create a shared_ptr-managed FileBackend at path.

Private Member Functions
	FileBackend (std::string path, IdPredicate initial_scope)
void	register_scope_ (IdPredicate scope)
auto	build_index_locked_ () -> expected< void, BackendError >
auto	ensure_write_fd_locked_ () -> expected< void, BackendError >

Private Attributes
const std::string	path_
IdPredicate	index_scope_
bool	index_built_ = false
std::shared_ptr< const Index >	index_
int	fd_ = -1
std::mutex	io_mutex_
bool	dirty_ = false
std::vector< BackendError >	deferred_errors_

Static Private Attributes
static std::mutex	registry_mutex_
static std::unordered_map< std::string, std::weak_ptr< FileBackend > >	registry_

Constructor & Destructor Documentation

~FileBackend()

ngen::serialization::FileBackend::~FileBackend ( )

override

References fd_.

FileBackend()

ngen::serialization::FileBackend::FileBackend ( std::string path, IdPredicate initial_scope )

private

Member Function Documentation

build_index_locked_()

auto ngen::serialization::FileBackend::build_index_locked_ ( ) -> expected<void, BackendError>

private

create()

auto ngen::serialization::FileBackend::create ( std::string path, IdPredicate index_scope = {} ) -> std::shared_ptr<FileBackend>

staticnodiscard

Get-or-create a shared_ptr-managed FileBackend at path.

index_scope is registered as this caller's contribution to the eventual index scope — see the class- level "Two-layer scope filtering" section for how scopes compose across callers. Pass {} to mean "no opinion."

Does no I/O; the index is built on the first reader() request, and any disk-side error surfaces there. A missing file is not an error — it yields an empty index.

Referenced by models::bmi::protocols::NgenDeserializationProtocol::initialize(), and models::bmi::protocols::NgenSerializationProtocol::initialize().

ensure_write_fd_locked_()

auto ngen::serialization::FileBackend::ensure_write_fd_locked_ ( ) -> expected<void, BackendError>

private

finalize()

auto ngen::serialization::FileBackend::finalize ( ) -> expected< void, std::vector< BackendError > >

nodiscardoverridevirtual

Lifecycle hook for cross-event cleanup: close process-level open handles, drain async queues, surface deferred errors.

Engine calls this at MPI synchronization points or before shutdown.

Error arm carries the vector of every BackendError accumulated since the last finalize() call — typically those deferred under Durability::relaxed from earlier write()/commit() calls, or any errors that surfaced during finalize itself. Each entry keeps its own structured Kind and message, so callers can branch per-error:

if (auto r = backend->finalize(); !r) {
    for (const auto& e : r.error()) {
        switch (e.kind) {
            case BackendError::Kind::IOError:   ...
            case BackendError::Kind::Corrupted: ...
            case BackendError::Kind::NotFound:  ...
        }
    }
}

An empty deferred-error set is success — the success arm is returned, not an error arm with an empty vector.

Implements ngen::serialization::RecordBackend.

path()

const std::string & ngen::serialization::FileBackend::path ( ) const

inlinenoexcept

Path the backend was constructed against.

References path_.

Referenced by ngen::serialization::FileBackend::Index::build(), and ngen::serialization::FileBackend::Index::insert_or_replace().

reader()

auto ngen::serialization::FileBackend::reader ( IdPredicate in_scope = {} ) -> expected< std::unique_ptr< RecordBackend::Reader >, BackendError >

nodiscardoverridevirtual

Construct a Reader scoped to records whose id satisfies in_scope.

The predicate is both a hint and an enforced scope — out-of-scope ids return Kind::NotFound. An empty predicate means "no scope" — the Reader will find any record.

Implements ngen::serialization::RecordBackend.

register_scope_()

void ngen::serialization::FileBackend::register_scope_ ( IdPredicate scope )

private

References index_scope_.

with_reader()

template<typename F >

auto ngen::serialization::RecordBackend::with_reader ( IdPredicate in_scope, F && fn ) -> expected<void, BackendError>

inlinenodiscardinherited

Run fn inside a scoped Reader; calls close() automatically on success.

Exceptions from fn unwind through the Reader destructor and re-throw to the caller.

Template Parameters

F	invocable as void(Reader&).

References ngen::serialization::RecordBackend::reader().

with_writer()

template<typename F >

auto ngen::serialization::RecordBackend::with_writer ( std::chrono::system_clock::time_point epoch, Durability durability, F && fn ) -> expected<void, BackendError>

inlinenodiscardinherited

Run fn inside a scoped Writer; calls commit() automatically on success.

Exceptions from fn unwind through the Writer destructor and re-throw to the caller.

Template Parameters

F	invocable as void(Writer&).

References ngen::serialization::RecordBackend::writer().

writer()

auto ngen::serialization::FileBackend::writer ( std::chrono::system_clock::time_point epoch, Durability durability ) -> expected< std::unique_ptr< RecordBackend::Writer >, BackendError >

nodiscardoverridevirtual

Construct a Writer for one checkpoint event.

Backends MUST return the error arm when a previous Writer is still alive on the same instance (single-in-flight rule). Callers should prefer with_writer below, which makes the rule a syntactic property of the call site.

Implements ngen::serialization::RecordBackend.

References ngen::serialization::strict.

Member Data Documentation

deferred_errors_

std::vector<BackendError> ngen::serialization::FileBackend::deferred_errors_

private

dirty_

bool ngen::serialization::FileBackend::dirty_ = false

private

fd_

int ngen::serialization::FileBackend::fd_ = -1

private

Referenced by ~FileBackend().

index_

std::shared_ptr<const Index> ngen::serialization::FileBackend::index_

private

index_built_

bool ngen::serialization::FileBackend::index_built_ = false

private

index_scope_

IdPredicate ngen::serialization::FileBackend::index_scope_

private

Referenced by register_scope_().

io_mutex_

std::mutex ngen::serialization::FileBackend::io_mutex_

mutableprivate

path_

const std::string ngen::serialization::FileBackend::path_

private

Referenced by path().

registry_

std::unordered_map< std::string, std::weak_ptr< FileBackend > > ngen::serialization::FileBackend::registry_

staticprivate

registry_mutex_

std::mutex ngen::serialization::FileBackend::registry_mutex_

staticprivate

---

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

• include/utilities/bmi/file_backend.hpp
• src/utilities/bmi/file_backend.cpp