G4RunToolStateSynchronization Class Reference

Thread-safe lifecycle state shared by the Athena and Geant4 main threads. More...

#include <G4RunToolStateSynchronization.h>

Collaboration diagram for G4RunToolStateSynchronization:

Public Types
enum class	Status {   Starting , Running , FinalizeRequested , Failed ,   Stopped }

Public Member Functions
void	NotifyBeginRun ()
	Transition Starting to Running. Ignored in every other state.
void	RequestFinalize ()
	Transition Starting or Running to FinalizeRequested.
void	Fail (std::string message)
	Transition any non-terminal state to Failed and wake startup waiters.
void	NotifyThreadExit ()
	Record normal exit after finalization, or failure after an unexpected exit.
bool	WaitBeginRun (std::string &failureMessage)
	Wait until startup succeeds or the lifecycle reaches a terminal condition.
bool	StopRequested () const
	Return whether the Geant4 run loop must stop.

Private Attributes
Status	m_status {Status::Starting}
std::string	m_failureMessage
std::mutex	m_mutex
std::condition_variable	m_cv

Detailed Description

Thread-safe lifecycle state shared by the Athena and Geant4 main threads.

The normal lifecycle is:

Starting –NotifyBeginRun()--> Running Starting/Running –RequestFinalize()--> FinalizeRequested FinalizeRequested –NotifyThreadExit()--> Stopped

A failure before normal thread exit instead transitions Starting, Running or FinalizeRequested to Failed. An unexpected thread exit while Starting or Running is also treated as a failure. Failed and Stopped are terminal states; late BeginOfRun, finalize and failure notifications cannot leave them.

Definition at line 24 of file G4RunToolStateSynchronization.h.

Member Enumeration Documentation

Status

enum class G4RunToolStateSynchronization::Status

strong

Enumerator
Starting	Waiting for the first Geant4 BeginOfRun notification.
Running	BeginOfRun was observed; Athena may submit events.
FinalizeRequested	Athena requested termination of the Geant4 run loop.
Failed	The Geant4 main thread failed; terminal state.
Stopped	The Geant4 main thread exited normally; terminal state.

Definition at line 27 of file G4RunToolStateSynchronization.h.

                    {
    Starting,          
    Running,           
    FinalizeRequested, 
    Failed,            
    Stopped            
  };

Member Function Documentation

Fail()

void G4RunToolStateSynchronization::Fail

(

std::string

message

)

Transition any non-terminal state to Failed and wake startup waiters.

Definition at line 31 of file G4RunToolStateSynchronization.cxx.

{
  {
    std::scoped_lock lk(m_mutex);
    // Preserve the first terminal outcome and its diagnostic message.
    if (m_status != Status::Failed && m_status != Status::Stopped) {
      m_failureMessage = std::move(message);
      m_status = Status::Failed;
    }
  }
  m_cv.notify_all();
}

NotifyBeginRun()

void G4RunToolStateSynchronization::NotifyBeginRun

(

)

Transition Starting to Running. Ignored in every other state.

Definition at line 9 of file G4RunToolStateSynchronization.cxx.

{
  {
    std::scoped_lock lk(m_mutex);
    if (m_status == Status::Starting) {
      m_status = Status::Running;
    }
  }
  m_cv.notify_all();
}

NotifyThreadExit()

void G4RunToolStateSynchronization::NotifyThreadExit

(

)

Record normal exit after finalization, or failure after an unexpected exit.

Definition at line 44 of file G4RunToolStateSynchronization.cxx.

{
  {
    std::scoped_lock lk(m_mutex);
    if (m_status == Status::Starting || m_status == Status::Running) {
      if (m_failureMessage.empty()) {
        m_failureMessage =
          "Geant4 main thread exited without completing its lifecycle";
      }
      m_status = Status::Failed;
    }
    else if (m_status == Status::FinalizeRequested) {
      m_status = Status::Stopped;
    }
  }
  m_cv.notify_all();
}

RequestFinalize()

void G4RunToolStateSynchronization::RequestFinalize

(

)

Transition Starting or Running to FinalizeRequested.

Definition at line 20 of file G4RunToolStateSynchronization.cxx.

{
  {
    std::scoped_lock lk(m_mutex);
    if (m_status == Status::Starting || m_status == Status::Running) {
      m_status = Status::FinalizeRequested;
    }
  }
  m_cv.notify_all();
}

StopRequested()

bool G4RunToolStateSynchronization::StopRequested

(

)

const

Return whether the Geant4 run loop must stop.

Definition at line 78 of file G4RunToolStateSynchronization.cxx.

{
  std::scoped_lock lk(m_mutex);
  return m_status == Status::FinalizeRequested ||
         m_status == Status::Failed ||
         m_status == Status::Stopped;
}

WaitBeginRun()

bool G4RunToolStateSynchronization::WaitBeginRun

(

std::string &

failureMessage

)

Wait until startup succeeds or the lifecycle reaches a terminal condition.

Definition at line 62 of file G4RunToolStateSynchronization.cxx.

{
  std::unique_lock lk(m_mutex);
  m_cv.wait(lk, [this]{ return m_status != Status::Starting; });
  if (m_status == Status::Running) {
    return true;
  }
 
  failureMessage = m_failureMessage;
  if (failureMessage.empty()) {
    failureMessage = "Geant4 stopped before beginning a run";
  }
  return false;
}

Member Data Documentation

m_cv

std::condition_variable G4RunToolStateSynchronization::m_cv

private

Definition at line 52 of file G4RunToolStateSynchronization.h.

m_failureMessage

std::string G4RunToolStateSynchronization::m_failureMessage

private

Definition at line 50 of file G4RunToolStateSynchronization.h.

m_mutex

std::mutex G4RunToolStateSynchronization::m_mutex

mutableprivate

Definition at line 51 of file G4RunToolStateSynchronization.h.

m_status

Status G4RunToolStateSynchronization::m_status {Status::Starting}

private

Definition at line 49 of file G4RunToolStateSynchronization.h.

{Status::Starting};

---

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

• G4RunToolStateSynchronization.h
• G4RunToolStateSynchronization.cxx