InputFileIncidentGuard Class Reference

RAII guard that guarantees a matching end-incident for every begin-incident. More...

#include <InputFileIncidentGuard.h>

Collaboration diagram for InputFileIncidentGuard:

Public Member Functions
	~InputFileIncidentGuard ()
	Destructor: fires the end incident unless the guard has been moved from (disarmed).
	InputFileIncidentGuard (InputFileIncidentGuard &&other) noexcept
	Move constructor: takes ownership; the source is disarmed.
InputFileIncidentGuard &	operator= (InputFileIncidentGuard &&other) noexcept
	Move assignment: fires the end incident for the file being replaced (if any), then takes ownership of other.
	InputFileIncidentGuard (const InputFileIncidentGuard &)=delete
	Copy is not allowed.
InputFileIncidentGuard &	operator= (const InputFileIncidentGuard &)=delete
	Copy assignment is not allowed.

Static Public Member Functions
static InputFileIncidentGuard	begin (IIncidentSvc &incSvc, std::string_view source, std::string_view beginFileName, std::string_view guid, std::string_view endFileName={}, std::string_view beginType=IncidentType::BeginInputFile, std::string_view endType=IncidentType::EndInputFile)
	Factory: fire the begin incident and return a guard whose destructor fires the matching end incident.
static void	transition (std::optional< InputFileIncidentGuard > &guard, IIncidentSvc &incSvc, std::string_view source, std::string_view beginFileName, std::string_view guid, std::string_view endFileName={}, std::string_view beginType=IncidentType::BeginInputFile, std::string_view endType=IncidentType::EndInputFile)
	Replace the guard in an optional, with strict End-before-Begin ordering.

Private Member Functions
	InputFileIncidentGuard (IIncidentSvc &incSvc, std::string_view source, std::string_view beginFileName, std::string_view guid, std::string endFileName, std::string_view beginType, std::string_view endType)
	Private constructor used by begin().

Private Attributes
IIncidentSvc *	m_incSvc
	Incident service pointer; nullptr if disarmed (moved-from).
std::string	m_source
	Source name for both begin and end incidents.
std::string	m_guid
	File GUID passed to the FileIncident.
std::string	m_endFileName
	fileName used for the end incident.
std::string	m_endType
	Incident type string for the end incident (e.g. "EndInputFile").

Detailed Description

RAII guard that guarantees a matching end-incident for every begin-incident.

Purpose

Event selectors fire BeginInputFile / EndInputFile incidents to notify listeners (e.g. MetaDataSvc) of input file transitions. These incidents must always be paired: every Begin must have a matching End. When the firing points are scattered across multiple methods, manual pairing is error-prone – early returns, exceptions, or forgotten calls can leave incidents unmatched.

This guard uses RAII to enforce pairing: the constructor fires the begin incident, and the destructor fires the matching end incident. Instances can only be created through the static begin() factory, which is marked [[nodiscard]] so the compiler warns if the guard is discarded.

Semantics

• Move-only: the moved-from instance is disarmed (will not fire the end incident). Copy is deleted.
• File transitions: use transition() instead of direct assignment to guarantee End(old) fires before Begin(new).
• Custom incident types: defaults to BeginInputFile / EndInputFile, overridable for other paired incidents (e.g. BeginInputMemFile / EndInputMemFile).

Usage

Typical usage as an std::optional member of an event selector:

// Member:
std::optional<InputFileIncidentGuard> m_guard;
 
// File transition (End for old file, then Begin for new):
InputFileIncidentGuard::transition(m_guard, incSvc, name(), fileName, guid);
 
// First file (no previous guard to reset):
m_guard = InputFileIncidentGuard::begin(incSvc, name(), fileName, guid);
 
// Shutdown -- fire End for the last file:
m_guard.reset();
 
// Scoped guard for eventless files (Begin + End in same scope):
{
   auto guard = InputFileIncidentGuard::begin(incSvc, name(),
                     fileName, {}, "eventless:" + fileName);
}

Definition at line 75 of file InputFileIncidentGuard.h.

Constructor & Destructor Documentation

~InputFileIncidentGuard()

InputFileIncidentGuard::~InputFileIncidentGuard ( )

inline

Destructor: fires the end incident unless the guard has been moved from (disarmed).

Definition at line 132 of file InputFileIncidentGuard.h.

                             {
      if (m_incSvc) {
         m_incSvc->fireIncident(
            FileIncident(m_source, m_endType,
                         m_endFileName, m_guid));
      }
   }

InputFileIncidentGuard() [1/3]

InputFileIncidentGuard::InputFileIncidentGuard ( InputFileIncidentGuard && other )

inlinenoexcept

Move constructor: takes ownership; the source is disarmed.

Definition at line 141 of file InputFileIncidentGuard.h.

      : m_incSvc(std::exchange(other.m_incSvc, nullptr))
      , m_source(std::move(other.m_source))
      , m_guid(std::move(other.m_guid))
      , m_endFileName(std::move(other.m_endFileName))
      , m_endType(std::move(other.m_endType))
   {}

InputFileIncidentGuard() [2/3]

InputFileIncidentGuard::InputFileIncidentGuard ( const InputFileIncidentGuard & )

delete

Copy is not allowed.

InputFileIncidentGuard() [3/3]

InputFileIncidentGuard::InputFileIncidentGuard ( IIncidentSvc & incSvc, std::string_view source, std::string_view beginFileName, std::string_view guid, std::string endFileName, std::string_view beginType, std::string_view endType )

inlineprivate

Private constructor used by begin().

Definition at line 174 of file InputFileIncidentGuard.h.

      : m_incSvc(&incSvc)
      , m_source(source)
      , m_guid(guid)
      , m_endFileName(std::move(endFileName))
      , m_endType(endType)
   {
      m_incSvc->fireIncident(
         FileIncident(m_source, std::string(beginType),
                      std::string(beginFileName), m_guid));
   }

Member Function Documentation

begin()

InputFileIncidentGuard InputFileIncidentGuard::begin ( IIncidentSvc & incSvc, std::string_view source, std::string_view beginFileName, std::string_view guid, std::string_view endFileName = {}, std::string_view beginType = IncidentType::BeginInputFile, std::string_view endType = IncidentType::EndInputFile )

inlinestaticnodiscard

Factory: fire the begin incident and return a guard whose destructor fires the matching end incident.

Parameters

incSvc	The incident service used to fire incidents.
source	Source name passed to the FileIncident (typically the selector's name()).
beginFileName	fileName for the begin incident.
guid	File GUID passed to the FileIncident.
endFileName	fileName for the end incident. Defaults to "FID:" + guid; pass explicitly for eventless files.
beginType	Incident type string for the begin incident.
endType	Incident type string for the end incident.

This is the only way to create an instance.

Definition at line 93 of file InputFileIncidentGuard.h.

                                                                  {},
                                       std::string_view beginType = IncidentType::BeginInputFile,
                                       std::string_view endType = IncidentType::EndInputFile) {
      return InputFileIncidentGuard(incSvc, source, beginFileName, guid,
                                    endFileName.empty() ? "FID:" + std::string(guid)
                                                        : std::string(endFileName),
                                    beginType, endType);
   }

operator=() [1/2]

InputFileIncidentGuard & InputFileIncidentGuard::operator= ( const InputFileIncidentGuard & )

delete

Copy assignment is not allowed.

operator=() [2/2]

InputFileIncidentGuard & InputFileIncidentGuard::operator= ( InputFileIncidentGuard && other )

inlinenoexcept

Move assignment: fires the end incident for the file being replaced (if any), then takes ownership of other.

Definition at line 151 of file InputFileIncidentGuard.h.

                                                                            {
      if (this != &other) {
         if (m_incSvc) {
            m_incSvc->fireIncident(
               FileIncident(m_source, m_endType,
                            m_endFileName, m_guid));
         }
         m_incSvc = std::exchange(other.m_incSvc, nullptr);
         m_source = std::move(other.m_source);
         m_guid = std::move(other.m_guid);
         m_endFileName = std::move(other.m_endFileName);
         m_endType = std::move(other.m_endType);
      }
      return *this;
   }

transition()

void InputFileIncidentGuard::transition ( std::optional< InputFileIncidentGuard > & guard, IIncidentSvc & incSvc, std::string_view source, std::string_view beginFileName, std::string_view guid, std::string_view endFileName = {}, std::string_view beginType = IncidentType::BeginInputFile, std::string_view endType = IncidentType::EndInputFile )

inlinestatic

Replace the guard in an optional, with strict End-before-Begin ordering.

Parameters

guard

The optional holding the current guard. It is reset first (firing the end incident for the old file, if any), then a new guard is emplaced (firing the begin incident for the new file).

The remaining parameters are forwarded to begin(). Use this for file transitions instead of direct assignment.

Definition at line 117 of file InputFileIncidentGuard.h.

                                                     {},
                          std::string_view beginType = IncidentType::BeginInputFile,
                          std::string_view endType = IncidentType::EndInputFile) {
      guard.reset();
      guard = begin(incSvc, source, beginFileName, guid,
                    endFileName, beginType, endType);
   }

Member Data Documentation

m_endFileName

std::string InputFileIncidentGuard::m_endFileName

private

fileName used for the end incident.

Definition at line 199 of file InputFileIncidentGuard.h.

m_endType

std::string InputFileIncidentGuard::m_endType

private

Incident type string for the end incident (e.g. "EndInputFile").

Definition at line 201 of file InputFileIncidentGuard.h.

m_guid

std::string InputFileIncidentGuard::m_guid

private

File GUID passed to the FileIncident.

Definition at line 197 of file InputFileIncidentGuard.h.

m_incSvc

IIncidentSvc* InputFileIncidentGuard::m_incSvc

private

Incident service pointer; nullptr if disarmed (moved-from).

Definition at line 193 of file InputFileIncidentGuard.h.

m_source

std::string InputFileIncidentGuard::m_source

private

Source name for both begin and end incidents.

Definition at line 195 of file InputFileIncidentGuard.h.

---

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

• InputFileIncidentGuard.h