Class to handle errors and exceptions in a simple, consistent stream-based manner. More...

#include <error.H>

Inheritance diagram for error:

[legend]

Collaboration diagram for error:

[legend]

Public Types
enum class	handlerTypes : char { DEFAULT = 0 , IGNORE , WARN , STRICT }
	Handling of errors. The exact handling depends on the local context. More...
Public Types inherited from messageStream
enum	errorSeverity : int { INFO = 1 , WARNING , SERIOUS , FATAL , USE_STDERR = 0x80 }
	Message type, error severity flags. More...

Public Member Functions
	error (const char *title)
	Construct from title string.
	error (const std::string &title)
	Construct from title string.
	error (const dictionary &errDict)
	Construct from dictionary.
	error (const error &err)
	Copy construct.
virtual	~error () noexcept
	Destructor.
string	message () const
	The accumulated error message.
void	clear () const
	Clear any accumulated error messages.
const string &	functionName () const noexcept
	The currently defined function name for output messages.
const string &	sourceFileName () const noexcept
	The currently defined source-file name for output messages.
int	sourceFileLineNumber () const noexcept
	The currently defined source-file line number for output messages.
bool	throwing () const noexcept
	Return the current exception throwing state (on or off).
bool	throwing (const bool on) noexcept
	Specify exception throwing state (on or off).
OSstream &	stream ()
	Return OSstream for output operations.
	operator OSstream & ()
	Implicit cast to OSstream for << operations.
OSstream &	operator() ()
	Explicit convert to OSstream for << operations.
OSstream &	operator() (string functionName, const char *sourceFileName=nullptr, const int sourceFileLineNumber=-1)
	Define basic print message with originating function name, optionally with 'source file, line number'.
OSstream &	operator() (const char functionName, const char sourceFileName=nullptr, const int sourceFileLineNumber=-1)
	Define basic print message with originating function name, optionally with 'source file, line number'.
	operator dictionary () const
	Extract a dictionary representation of the error information.
void	exit (const int errNo=1)
	Exit : can be called for any error to exit program.
void	abort ()
	Abort : used to stop code for fatal errors.
virtual void	write (Ostream &os, const bool withTitle=true) const
	Print error message.
bool	throwExceptions (const bool on=true) noexcept
	Specify exception throwing state (default is on).
bool	dontThrowExceptions () noexcept
	Deactivate exception throwing.
Public Member Functions inherited from messageStream
	messageStream (errorSeverity severity, int maxErrors=0, bool use_stderr=false)
	Construct untitled with given characteristics.
	messageStream (const char *title, errorSeverity severity, int maxErrors=0, bool use_stderr=false)
	Construct from components.
	messageStream (string title, errorSeverity severity, int maxErrors=0, bool use_stderr=false)
	Construct from components.
	messageStream (const dictionary &dict)
	Construct from dictionary as Fatal, extracting 'title'.
const string &	title () const noexcept
	The title of this error type.
int	maxErrors () const noexcept
	The maximum number of errors before program termination.
int	maxErrors (int nErrors) noexcept
	Set the maximum number of errors before program termination.
OSstream &	stream (OSstream *alternative=nullptr, int communicator=-1)
	Return OSstream for output operations.
OSstream &	masterStream (int communicator)
	Return OSstream for output operations on the master process only, Snull on other processes.
std::ostream &	stdStream ()
	Return std::ostream for output operations.
OSstream &	deprecated (const int afterVersion, const char functionName=nullptr, const char sourceFileName=nullptr, const int sourceFileLineNumber=0)
	Report deprecation (after specified API version) with 'From function-name, source file, line number'.
	operator OSstream & ()
	Implicit cast to OSstream for << operations.
OSstream &	operator() ()
	Explicitly convert to OSstream for << operations.
OSstream &	operator() (const std::string &functionName, const char *sourceFileName=nullptr, const int sourceFileLineNumber=0)
	Report 'From function-name', optionally with 'source file, line number'.
OSstream &	operator() (const char functionName, const char sourceFileName=nullptr, const int sourceFileLineNumber=0)
	Report 'From function-name', optionally with 'source file, line number'.
OSstream &	operator() (const char functionName, const char sourceFileName, const int sourceFileLineNumber, const std::string &ioFileName, const label ioStartLineNumber=-1, const label ioEndLineNumber=-1)
	Report 'From function-name, source file, line number' as well as io-file name and location.
OSstream &	operator() (const char functionName, const char sourceFileName, const int sourceFileLineNumber, const IOstream &)
	Report 'From function-name, source file, line number' as well as io-file name and location.
OSstream &	operator() (const char functionName, const char sourceFileName, const int sourceFileLineNumber, const dictionary &)
	Report 'From function-name, source file, line number' as well as io-file name and location.

Static Public Member Functions
static bool	master (const int communicator=-1)
	Like Pstream::master but with a Pstream::parRun guard in case Pstream has not yet been initialised.
static bool	warnAboutAge (const int version) noexcept
	Test if an age warning should be emitted.
static bool	warnAboutAge (const char *what, const int version)
	Emit warning on stderr about something being old.
static void	safePrintStack (std::ostream &os, int size=-1)
	Helper function to print a stack, with optional upper limit. Used when OpenFOAM IO not yet initialised.
static void	printStack (Ostream &os, int size=-1)
	Helper function to print a stack, with optional upper limit.
static bool	useAbort ()
	True if FOAM_ABORT is on.

Static Public Attributes
static const Enum< handlerTypes >	handlerNames
	Names of the error handler types.
Static Public Attributes inherited from messageStream
static int	level
	The output level (verbosity) of messages.
static int	redirect
	The output redirection of messages.

Protected Member Functions
void	simpleExit (const int errNo, const bool isAbort)
	Exit or abort, without throwing or job control handling.

Protected Attributes
string	functionName_
string	sourceFileName_
int	sourceFileLineNumber_
bool	throwing_
std::unique_ptr< OStringStream >	messageStreamPtr_
Protected Attributes inherited from messageStream
string	title_
	The title of this error type.
int	severity_
	The message type / error severity, possibly with USE_STDERR mask.
int	maxErrors_
	The maximum number of errors before program termination.
int	errorCount_
	The current number of errors counted.

Detailed Description

Class to handle errors and exceptions in a simple, consistent stream-based manner.

The error class is globally instantiated with a title string. Errors, messages and other data are piped to the messageStream class in the standard manner. Manipulators are supplied for exit and abort that may terminate the program or throw an exception depending on whether the exception handling has been switched on (off by default).

Usage: error << "message1" << "message2" << FoamDataType << exit(errNo);

error << "message1" << "message2" << FoamDataType << abort();

Foam::error::exit
void exit(const int errNo=1)
Exit : can be called for any error to exit program.
Definition error.C:352

Foam::error::abort
void abort()
Abort : used to stop code for fatal errors.
Definition error.C:358

Foam::error::error
error(const char *title)
Construct from title string.
Definition error.C:119

Source files

See also: Foam::errorManip Foam::errorManipArg

Definition at line 70 of file error.H.

Member Enumeration Documentation

◆ handlerTypes

enum class handlerTypes : char

strong

Handling of errors. The exact handling depends on the local context.

Enumerator
DEFAULT	Default behaviour (local meaning).
IGNORE	Ignore on errors/problems.
WARN	Warn on errors/problems.
STRICT	Fatal on errors/problems.

Definition at line 109 of file error.H.

Constructor & Destructor Documentation

◆ error() [1/4]

error ( const char * title )

explicit

Construct from title string.

Definition at line 119 of file error.C.

References messageStream::FATAL, functionName_, messageStream::messageStream(), messageStreamPtr_, sourceFileLineNumber_, sourceFileName_, throwing_, and messageStream::title().

Referenced by error(), error(), IOerror::IOerror(), and IOerror::IOerror().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ error() [2/4]

error ( const std::string & title )

inlineexplicit

Construct from title string.

Definition at line 133 of file error.H.

References error(), and messageStream::title().

Here is the call graph for this function:

◆ error() [3/4]

error ( const dictionary & errDict )

explicit

Construct from dictionary.

Definition at line 131 of file error.C.

References functionName_, messageStream::messageStream(), messageStreamPtr_, sourceFileLineNumber_, sourceFileName_, and throwing_.

Here is the call graph for this function:

◆ error() [4/4]

error ( const error & err )

Copy construct.

Definition at line 143 of file error.C.

References error(), functionName_, messageStream::messageStream(), messageStreamPtr_, sourceFileLineNumber_, sourceFileName_, and throwing_.

Here is the call graph for this function:

◆ ~error()

~error ( )

virtualnoexcept

Destructor.

Definition at line 165 of file error.C.

References Foam::noexcept.

Member Function Documentation

◆ simpleExit()

void simpleExit	(	const int	errNo,
		const bool	isAbort )

protected

Exit or abort, without throwing or job control handling.

Definition at line 263 of file error.C.

References UPstream::abort(), Foam::endl(), UPstream::exit(), Foam::nl, UPstream::parRun(), Foam::Perr, printStack(), and useAbort().

Here is the call graph for this function:

◆ master()

bool master ( const int communicator = -1 )

static

Like Pstream::master but with a Pstream::parRun guard in case Pstream has not yet been initialised.

Parameters

communicator is the numbered MPI communicator. By default it uses UPstream::worldComm

Definition at line 53 of file error.C.

References UPstream::master(), and UPstream::parRun().

Referenced by dictionary::csearchCompat(), Foam::warnCompatDegrees(), and FieldBase::warnLocalBoundaryConsistencyCompat().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ warnAboutAge() [1/2]

bool warnAboutAge ( const int version )

staticnoexcept

Test if an age warning should be emitted.

Parameters

version is the old version (YYMM) for determining the age in months compared to the current OpenFOAM version as conveyed by the foamVersion::api value.

Definition at line 67 of file error.C.

References Foam::foamVersion::api.

Referenced by dictionary::csearchCompat(), timeControl::read(), and FieldBase::warnLocalBoundaryConsistencyCompat().

Here is the caller graph for this function:

◆ warnAboutAge() [2/2]

bool warnAboutAge	(	const char *	what,
		const int	version )

static

Emit warning on stderr about something being old.

Parameters

what	description for the warning
version	is the old version (YYMM) for determining the age in months compared to the current OpenFOAM version as conveyed by the `foamVersion::api` value.

Definition at line 74 of file error.C.

References Foam::foamVersion::api.

◆ message()

Foam::string message ( ) const

The accumulated error message.

Definition at line 332 of file error.C.

References messageStreamPtr_.

Referenced by write(), and IOerror::write().

Here is the caller graph for this function:

◆ clear()

void clear ( ) const

Clear any accumulated error messages.

Definition at line 343 of file error.C.

References messageStreamPtr_.

◆ functionName()

const string & functionName ( ) const

inlinenoexcept

The currently defined function name for output messages.

Definition at line 199 of file error.H.

References functionName(), functionName_, and Foam::noexcept.

Referenced by functionName(), operator()(), operator()(), IOerror::operator()(), IOerror::operator()(), IOerror::operator()(), IOerror::SafeFatalIOError(), write(), and IOerror::write().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ sourceFileName()

const string & sourceFileName ( ) const

inlinenoexcept

The currently defined source-file name for output messages.

Definition at line 207 of file error.H.

References Foam::noexcept, and sourceFileName_.

Referenced by operator()(), operator()(), IOerror::operator()(), IOerror::operator()(), IOerror::operator()(), IOerror::SafeFatalIOError(), write(), and IOerror::write().

Here is the caller graph for this function:

◆ sourceFileLineNumber()

int sourceFileLineNumber ( ) const

inlinenoexcept

The currently defined source-file line number for output messages.

Definition at line 215 of file error.H.

References Foam::noexcept, and sourceFileLineNumber_.

Referenced by operator()(), operator()(), IOerror::operator()(), IOerror::operator()(), IOerror::operator()(), IOerror::SafeFatalIOError(), write(), and IOerror::write().

Here is the caller graph for this function:

◆ throwing() [1/2]

bool throwing ( ) const

inlinenoexcept

Return the current exception throwing state (on or off).

Definition at line 223 of file error.H.

References Foam::noexcept, and throwing_.

Referenced by throwExceptions().

Here is the caller graph for this function:

◆ throwing() [2/2]

bool throwing ( const bool on )

inlinenoexcept

Specify exception throwing state (on or off).

Returns: the previous throwing state

Definition at line 233 of file error.H.

References throwing_.

◆ stream()

Foam::OSstream & stream ( )

Return OSstream for output operations.

Definition at line 314 of file error.C.

References Foam::abort(), Foam::endl(), messageStreamPtr_, Foam::nl, and Foam::Perr.

Referenced by operator OSstream &(), operator()(), operator()(), and operator()().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ operator OSstream &()

operator OSstream & ( )

inline

Implicit cast to OSstream for << operations.

Definition at line 251 of file error.H.

References stream().

Here is the call graph for this function:

◆ operator()() [1/3]

OSstream & operator() ( )

inline

Explicit convert to OSstream for << operations.

Definition at line 259 of file error.H.

References stream().

Here is the call graph for this function:

◆ operator()() [2/3]

Foam::OSstream & operator()	(	string	functionName,
		const char *	sourceFileName = nullptr,
		const int	sourceFileLineNumber = -1 )

Define basic print message with originating function name, optionally with 'source file, line number'.

Returns: OSstream for further operations

Definition at line 171 of file error.C.

References functionName(), functionName_, sourceFileLineNumber(), sourceFileLineNumber_, sourceFileName(), sourceFileName_, and stream().

Here is the call graph for this function:

◆ operator()() [3/3]

Foam::OSstream & operator()	(	const char *	functionName,
		const char *	sourceFileName = nullptr,
		const int	sourceFileLineNumber = -1 )

Define basic print message with originating function name, optionally with 'source file, line number'.

Returns: OSstream for further operations

Definition at line 192 of file error.C.

References functionName(), functionName_, sourceFileLineNumber(), sourceFileLineNumber_, sourceFileName(), sourceFileName_, and stream().

Here is the call graph for this function:

◆ operator dictionary()

operator dictionary ( ) const

Extract a dictionary representation of the error information.

References os().

Here is the call graph for this function:

◆ safePrintStack()

void safePrintStack	(	std::ostream &	os,
		int	size = -1 )

static

Helper function to print a stack, with optional upper limit. Used when OpenFOAM IO not yet initialised.

Definition at line 26 of file dummyPrintStack.C.

References os().

Here is the call graph for this function:

◆ printStack()

void printStack	(	Ostream &	os,
		int	size = -1 )

static

Helper function to print a stack, with optional upper limit.

Definition at line 27 of file dummyPrintStack.C.

References os().

Referenced by Foam::chMod(), Foam::cp(), Foam::exists(), Foam::exitNow(), Foam::fileSize(), Foam::highResLastModified(), Foam::isDir(), Foam::isFile(), Foam::lastModified(), Foam::ln(), messageStream::masterStream(), Foam::mkDir(), Foam::mode(), Foam::mv(), Foam::mvBak(), GeometricField< Type, PatchField, GeoMesh >::oldTime(), Foam::readDir(), Foam::readLink(), Foam::reduce(), Foam::rm(), Foam::rmDir(), and simpleExit().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ useAbort()

bool useAbort ( )

static

True if FOAM_ABORT is on.

Definition at line 110 of file error.C.

References Switch::find(), and Foam::getEnv().

Referenced by Foam::exitNow(), and simpleExit().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ exit()

void exit ( const int errNo = 1 )

Exit : can be called for any error to exit program.

Redirects to abort() when FOAM_ABORT is on.

Definition at line 352 of file error.C.

Referenced by Foam::exit().

Here is the caller graph for this function:

◆ abort()

void abort ( )

Abort : used to stop code for fatal errors.

Prints stack before exiting.

Definition at line 358 of file error.C.

Referenced by Foam::abort().

Here is the caller graph for this function:

◆ write()

void write	(	Ostream &	os,
		const bool	withTitle = true ) const

virtual

Print error message.

Reimplemented in IOerror.

Definition at line 364 of file error.C.

References Foam::foamVersion::api, functionName(), messageStream::level, message(), Foam::nl, os(), Foam::foamVersion::patch, Foam::foamVersion::patched(), sourceFileLineNumber(), sourceFileName(), and messageStream::title().

Referenced by functionObjectList::end(), functionObjectList::execute(), Foam::operator<<(), and functionObjectList::read().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ throwExceptions()

bool throwExceptions ( const bool on = true )

inlinenoexcept

Specify exception throwing state (default is on).

Returns: the previous throwing state

Definition at line 343 of file error.H.

References Foam::noexcept, and throwing().

Referenced by dontThrowExceptions().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dontThrowExceptions()

bool dontThrowExceptions ( )

inlinenoexcept

Deactivate exception throwing.

Returns: the previous throwing state

Definition at line 353 of file error.H.

References Foam::noexcept, and throwExceptions().

Here is the call graph for this function:

Member Data Documentation

◆ functionName_

string functionName_

protected

Definition at line 87 of file error.H.

Referenced by error(), error(), error(), functionName(), operator()(), and operator()().

◆ sourceFileName_

string sourceFileName_

protected

Definition at line 88 of file error.H.

Referenced by error(), error(), error(), operator()(), operator()(), and sourceFileName().

◆ sourceFileLineNumber_

int sourceFileLineNumber_

protected

Definition at line 89 of file error.H.

Referenced by error(), error(), error(), operator()(), operator()(), and sourceFileLineNumber().

◆ throwing_

bool throwing_

protected

Definition at line 90 of file error.H.

Referenced by error(), error(), error(), throwing(), and throwing().

◆ messageStreamPtr_

std::unique_ptr<OStringStream> messageStreamPtr_

protected

Definition at line 91 of file error.H.

Referenced by clear(), error(), error(), error(), message(), and stream().

◆ handlerNames

const Foam::Enum< Foam::error::handlerTypes > handlerNames

static

Names of the error handler types.

Definition at line 120 of file error.H.

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

src/OpenFOAM/db/error/error.H
src/OpenFOAM/db/error/error.C
src/OSspecific/POSIX/printStack/dummyPrintStack.C
src/OSspecific/POSIX/printStack/printStack.C

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ handlerTypes

Constructor & Destructor Documentation

◆ error() [1/4]

◆ error() [2/4]

◆ error() [3/4]

◆ error() [4/4]

◆ ~error()

Member Function Documentation

◆ simpleExit()

◆ master()

◆ warnAboutAge() [1/2]

◆ warnAboutAge() [2/2]

◆ message()

◆ clear()

◆ functionName()

◆ sourceFileName()

◆ sourceFileLineNumber()

◆ throwing() [1/2]

◆ throwing() [2/2]

◆ stream()

◆ operator OSstream &()

◆ operator()() [1/3]

◆ operator()() [2/3]

◆ operator()() [3/3]

◆ operator dictionary()

◆ safePrintStack()

◆ printStack()

◆ useAbort()

◆ exit()

◆ abort()

◆ write()

◆ throwExceptions()

◆ dontThrowExceptions()

Member Data Documentation

◆ functionName_

◆ sourceFileName_

◆ sourceFileLineNumber_

◆ throwing_

◆ messageStreamPtr_

◆ handlerNames