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`.

#define	NS_ABORT_MSG(msg)
	Unconditional abnormal program termination with a message.

#define	NS_ABORT_MSG_IF(cond, msg)
	Abnormal program termination if a condition is `true`, with a message.

#define	NS_ABORT_MSG_UNLESS(cond, msg) NS_ABORT_MSG_IF(!(cond), msg)
	Abnormal program termination if a condition is `false`, with a message.

#define	NS_ABORT_UNLESS(cond) NS_ABORT_IF(!(cond))
	Abnormal program termination if a condition is `false`.

#define	NS_FATAL_ERROR(msg) NS_FATAL_ERROR_IMPL(msg, true)
	Report a fatal error with a message and terminate.

#define	NS_FATAL_ERROR_CONT(msg) NS_FATAL_ERROR_IMPL(msg, false)
	Report a fatal error with a message, deferring termination.

#define	NS_FATAL_ERROR_IMPL(msg, fatal)
	Fatal error reporting with a message, implementation.

#define	NS_FATAL_ERROR_IMPL_NO_MSG(fatal)
	Fatal error reporting with no message, implementation.

#define	NS_FATAL_ERROR_NO_MSG() NS_FATAL_ERROR_IMPL_NO_MSG(true)
	Report a fatal error and terminate.

#define	NS_FATAL_ERROR_NO_MSG_CONT() NS_FATAL_ERROR_IMPL_NO_MSG(false)
	Report a fatal error, deferring termination.

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

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] cond The 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] msg The 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]	cond	The condition to be evaluated.
[in]	msg	The 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]	cond	The condition to be evaluated.
[in]	msg	The 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] cond The 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] msg message 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]	msg	The error message to print, if not empty.
[in]	fatal	Call `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;                    \
        ::ns3::FatalImpl::FlushStreams();                                                          \
        if (fatal)                                                                                 \
        {                                                                                          \
            std::cerr << ns3::NS_FATAL_MSG << std::endl;                                           \
            std::terminate();                                                                      \
        }                                                                                          \
    } while (false)

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] fatal Call 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.

Modules

Files

Macros

Variables

Detailed Description

Macro Definition Documentation

◆ NS_ABORT_IF

◆ NS_ABORT_MSG

◆ NS_ABORT_MSG_IF

◆ NS_ABORT_MSG_UNLESS

◆ NS_ABORT_UNLESS

◆ NS_FATAL_ERROR

◆ NS_FATAL_ERROR_CONT

◆ NS_FATAL_ERROR_IMPL

◆ NS_FATAL_ERROR_IMPL_NO_MSG

◆ NS_FATAL_ERROR_NO_MSG

◆ NS_FATAL_ERROR_NO_MSG_CONT

Variable Documentation

◆ NS_FATAL_MSG