A Discrete-Event Network Simulator
API
Fatal Error Handlers

Functions to help clean up when a fatal error is encountered. More...

+ Collaboration diagram for Fatal Error Handlers:

Modules

 Core example: NS_FATAL error handlers
 Example program illustrating use of the NS_FATAL error handlers.
 
 Fatal Implementation.
 

Files

file  abort.h
 NS_ABORT_x macro definitions.
 
file  fatal-error.h
 NS_FATAL_x macro definitions.
 

Macros

#define NS_ABORT_IF(cond)
 Abnormal program termination if a condition is true. More...
 
#define NS_ABORT_MSG(msg)
 Unconditional abnormal program termination with a message. More...
 
#define NS_ABORT_MSG_IF(cond, msg)
 Abnormal program termination if a condition is true, with a message. More...
 
#define NS_ABORT_MSG_UNLESS(cond, msg)   NS_ABORT_MSG_IF(!(cond), msg)
 Abnormal program termination if a condition is false, with a message. More...
 
#define NS_ABORT_UNLESS(cond)   NS_ABORT_IF(!(cond))
 Abnormal program termination if a condition is false. More...
 
#define NS_FATAL_ERROR(msg)   NS_FATAL_ERROR_IMPL(msg, true)
 Report a fatal error with a message and terminate. More...
 
#define NS_FATAL_ERROR_CONT(msg)   NS_FATAL_ERROR_IMPL(msg, false)
 Report a fatal error with a message, deferring termination. More...
 
#define NS_FATAL_ERROR_IMPL(msg, fatal)
 Fatal error reporting with a message, implementation. More...
 
#define NS_FATAL_ERROR_IMPL_NO_MSG(fatal)
 Fatal error reporting with no message, implementation. More...
 
#define NS_FATAL_ERROR_NO_MSG()   NS_FATAL_ERROR_IMPL_NO_MSG(true)
 Report a fatal error and terminate. More...
 
#define NS_FATAL_ERROR_NO_MSG_CONT()   NS_FATAL_ERROR_IMPL_NO_MSG(false)
 Report a fatal error, deferring termination. More...
 

Variables

constexpr std::string_view ns3::NS_FATAL_MSG {"NS_FATAL, terminating"}
 Output string marking imminent invocation of std::terminate. More...
 

Detailed Description

Functions to help clean up when a fatal error is encountered.

The functions in this group are used to perform limited clean up, like flushing active streams, when fatal errors are encountered (through assertion fail, calls to NS_ABORT_* or calls to NS_FATAL_ERROR).

Currently, other than flushing active ostreams, these functions does not interfere with outside memory. There is still a residual risk that invalid ostream pointers may be present, and may corrupt the memory on the attempt to execute the flush() function.

Macro Definition Documentation

◆ NS_ABORT_IF

#define NS_ABORT_IF (   cond)
Value:
do \
{ \
if (cond) \
{ \
std::cerr << "aborted. cond=\"" << #cond << ", "; \
NS_FATAL_ERROR_NO_MSG(); \
} \
} while (false)

Abnormal program termination if a condition is true.

Parameters
[in]condThe condition to be evaluated.

This is similar to NS_ASSERT(!(cond)), except this check is enabled in all builds. If cond is evaluated to true, the expression for cond is printed to stderr, followed by a call to the NS_FATAL_ERROR_NO_MSG() macro which prints the details of filename and line number to stderr. The program will be halted by calling std::terminate(), triggering any clean up code registered by std::set_terminate. The ns-3 default is a stream-flushing code, but may be overridden.

This macro is enabled unconditionally in all builds, including debug and optimized builds.

Definition at line 76 of file abort.h.

◆ NS_ABORT_MSG

#define NS_ABORT_MSG (   msg)
Value:
do \
{ \
std::cerr << "aborted. "; \
NS_FATAL_ERROR(msg); \
} while (false)

Unconditional abnormal program termination with a message.

Parameters
[in]msgThe message to output when this macro is hit.

This macro is essentially equivalent to NS_FATAL_ERROR, except it prepends the error message with the string "aborted. ". When this macro is hit at runtime, the program will be halted using std::terminate, which triggers clean up code registered by std::set_terminate.

This macro is enabled unconditionally in all builds, including debug and optimized builds.

See also
NS_FATAL_ERROR

Definition at line 49 of file abort.h.

◆ NS_ABORT_MSG_IF

#define NS_ABORT_MSG_IF (   cond,
  msg 
)
Value:
do \
{ \
if (cond) \
{ \
std::cerr << "aborted. cond=\"" << #cond << "\", "; \
NS_FATAL_ERROR(msg); \
} \
} while (false)

Abnormal program termination if a condition is true, with a message.

Parameters
[in]condThe condition to be evaluated.
[in]msgThe message to output when cond is true.

This is similar to NS_ASSERT_MSG(!(cond)), except this check is enabled in all builds. If cond is evaluated to true, the expression for cond is printed to stderr, followed by a call to the NS_FATAL_ERROR() macro which prints the user-specified error message, and details of filename and line number to stderr. The program will be halted by calling std::terminate(), triggering any clean up code registered by std::set_terminate. The ns-3 default is a stream-flushing code, but may be overridden.

This macro is enabled unconditionally in all builds, including debug and optimized builds.

Definition at line 108 of file abort.h.

◆ NS_ABORT_MSG_UNLESS

#define NS_ABORT_MSG_UNLESS (   cond,
  msg 
)    NS_ABORT_MSG_IF(!(cond), msg)

Abnormal program termination if a condition is false, with a message.

Parameters
[in]condThe condition to be evaluated.
[in]msgThe message to output if cond is false.

This is an alias for NS_ABORT_MSG_IF(!(cond))

See also
NS_ABORT_MSG_IF

Definition at line 144 of file abort.h.

◆ NS_ABORT_UNLESS

#define NS_ABORT_UNLESS (   cond)    NS_ABORT_IF(!(cond))

Abnormal program termination if a condition is false.

Parameters
[in]condThe condition to be evaluated.

This is an alias for NS_ABORT_IF(!(cond))

See also
NS_ABORT_IF

Definition at line 129 of file abort.h.

◆ NS_FATAL_ERROR

#define NS_FATAL_ERROR (   msg)    NS_FATAL_ERROR_IMPL(msg, true)

Report a fatal error with a message and terminate.

Parameters
[in]msgmessage to output when this macro is hit.

When this macro is hit at runtime, the user-specified error message are printed to stderr, followed by a call to the NS_FATAL_ERROR_NO_MSG() macro which prints the details of filename and line number to stderr. The program will be halted by calling std::terminate(), triggering any clean up code registered by std::set_terminate (NS3 default is a stream-flushing code, but may be overridden).

This macro is enabled unconditionally in all builds, including debug and optimized builds.

Definition at line 179 of file fatal-error.h.

◆ NS_FATAL_ERROR_CONT

#define NS_FATAL_ERROR_CONT (   msg)    NS_FATAL_ERROR_IMPL(msg, false)

Report a fatal error with a message, deferring termination.

When this macro is hit at runtime, details of filename and line number are printed to stderr, however the program is not halted. It is expected that the function using this macro will return an error code, and its caller will invoke NS_FATAL_ERROR(msg) triggering std::terminate().

This macro is enabled unconditionally in all builds, including debug and optimized builds.

Definition at line 195 of file fatal-error.h.

◆ NS_FATAL_ERROR_IMPL

#define NS_FATAL_ERROR_IMPL (   msg,
  fatal 
)
Value:
do \
{ \
std::cerr << "msg=\"" << msg << "\", "; \
NS_FATAL_ERROR_IMPL_NO_MSG(fatal); \
} while (false)

Fatal error reporting with a message, implementation.

When this macro is hit at runtime the error details will printed to stderr, including the message, file name and line number. Optionally, if fatal is true, the macro will invoke std::terminate(). If fatal is false, the invoking function should return an error code to its caller, which is expected to call NS_FATAL_ERROR to cause termination.

Parameters
[in]msgThe error message to print, if not empty.
[in]fatalCall std::terminate() if true.

This macro is enabled unconditionally in all builds, including debug and optimized builds.

Definition at line 120 of file fatal-error.h.

◆ NS_FATAL_ERROR_IMPL_NO_MSG

#define NS_FATAL_ERROR_IMPL_NO_MSG (   fatal)
Value:
do \
{ \
NS_LOG_APPEND_TIME_PREFIX_IMPL; \
NS_LOG_APPEND_NODE_PREFIX_IMPL; \
std::cerr << "file=" << __FILE__ << ", line=" << __LINE__ << std::endl; \
if (fatal) \
{ \
std::cerr << ns3::NS_FATAL_MSG << std::endl; \
std::terminate(); \
} \
} while (false)
constexpr std::string_view NS_FATAL_MSG
Output string marking imminent invocation of std::terminate.
Definition: fatal-error.h:67
void FlushStreams()
Flush all currently registered streams.
Definition: fatal-impl.cc:187

Fatal error reporting with no message, implementation.

When this macro is hit at runtime the error details will printed to stderr, including the file name and line number. Optionally, if fatal is true, the macro will invoke std::terminate(). If fatal is false, the invoking function should return an error code to its caller, which is expected to call NS_FATAL_ERROR to cause termination.

Parameters
[in]fatalCall std::terminate() if true.

This macro is enabled unconditionally in all builds, including debug and optimized builds.

Definition at line 88 of file fatal-error.h.

◆ NS_FATAL_ERROR_NO_MSG

#define NS_FATAL_ERROR_NO_MSG ( )    NS_FATAL_ERROR_IMPL_NO_MSG(true)

Report a fatal error and terminate.

When this macro is hit at runtime, details of filename and line number are printed to stderr, and the program is halted by calling std::terminate(). This will trigger any clean up code registered by std::set_terminate (NS3 default is a stream-flushing code), but may be overridden.

This macro is enabled unconditionally in all builds, including debug and optimized builds.

Definition at line 142 of file fatal-error.h.

◆ NS_FATAL_ERROR_NO_MSG_CONT

#define NS_FATAL_ERROR_NO_MSG_CONT ( )    NS_FATAL_ERROR_IMPL_NO_MSG(false)

Report a fatal error, deferring termination.

When this macro is hit at runtime, details of filename and line number are printed to stderr, however the program is not halted. It is expected that the function using this macro will return an error code, and its caller will invoke NS_FATAL_ERROR(msg) triggering std::terminate().

This macro is enabled unconditionally in all builds, including debug and optimized builds.

Definition at line 158 of file fatal-error.h.

Variable Documentation

◆ NS_FATAL_MSG

constexpr std::string_view ns3::NS_FATAL_MSG {"NS_FATAL, terminating"}
constexpr

Output string marking imminent invocation of std::terminate.

This is useful to know when capturing output and you want to strip system and compiler-dependent messages generated by std::terminate.

Definition at line 67 of file fatal-error.h.