A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
fatal-error.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2006 INRIA, 2010 NICTA
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
7 * Quincy Tse <quincy.tse@nicta.com.au>
8 */
9#ifndef NS3_FATAL_ERROR_H
10#define NS3_FATAL_ERROR_H
11
12#include "fatal-impl.h"
13#include "log.h" // NS_LOG_APPEND...
14
15#include <cstdlib>
16#include <exception>
17#include <iostream>
18#include <string_view>
19
20// If stacktrace is available, print it on fatal errors
21#ifdef STACKTRACE_LIBRARY_IS_LINKED
22#include <stacktrace>
23/**
24 * @brief Macro prints the current stack trace to standard error.
25 *
26 * This macro is defined only if the stacktrace library is linked.
27 */
28
29#define PRINT_STACKTRACE std::cerr << std::stacktrace::current() << std::endl
30#else
31/**
32 * @brief Macro does nothing if stacktrace library is not available.
33 */
34#define PRINT_STACKTRACE
35#endif
36
37/**
38 * @file
39 * @ingroup fatal
40 * @brief \c NS_FATAL_x macro definitions.
41 */
42
43/**
44 * @ingroup core
45 * @defgroup fatal Fatal Error Handlers
46 *
47 * @brief Functions to help clean up when a fatal error
48 * is encountered.
49 *
50 * The functions in this group are used to perform
51 * limited clean up, like flushing active streams, when
52 * fatal errors are encountered (through assertion fail,
53 * calls to NS_ABORT_* or calls to NS_FATAL_ERROR).
54 *
55 * Currently, other than flushing active ostreams, these
56 * functions does not interfere with outside memory. There
57 * is still a residual risk that invalid ostream
58 * pointers may be present, and may corrupt the memory
59 * on the attempt to execute the flush() function.
60 */
61
62namespace ns3
63{
64
65/**
66 * @ingroup fatal
67 *
68 * @brief Output string marking imminent invocation of std::terminate.
69 *
70 * This is useful to know when capturing output and you want to strip
71 * system and compiler-dependent messages generated by std::terminate.
72 */
73constexpr std::string_view NS_FATAL_MSG{"NS_FATAL, terminating"};
74
75} // namespace ns3
76
77/**
78 * @ingroup fatal
79 *
80 * @brief Fatal error reporting with no message, implementation.
81 *
82 * When this macro is hit at runtime the error details will
83 * printed to \c stderr, including the file name and line number.
84 * Optionally, if \c fatal is true, the macro
85 * will invoke \c std::terminate(). If \c fatal is false,
86 * the invoking function should return an error code to its caller,
87 * which is expected to call NS_FATAL_ERROR to cause termination.
88 *
89 * @param [in] fatal Call \c std::terminate() if true.
90 *
91 * This macro is enabled unconditionally in all builds,
92 * including debug and optimized builds.
93 */
94#define NS_FATAL_ERROR_IMPL_NO_MSG(fatal) \
95 do \
96 { \
97 NS_LOG_APPEND_TIME_PREFIX_IMPL; \
98 NS_LOG_APPEND_NODE_PREFIX_IMPL; \
99 std::cerr << "file=" << __FILE__ << ", line=" << __LINE__ << std::endl; \
100 ::ns3::FatalImpl::FlushStreams(); \
101 if (fatal) \
102 { \
103 std::cerr << ns3::NS_FATAL_MSG << std::endl; \
104 PRINT_STACKTRACE; \
105 std::terminate(); \
106 } \
107 } while (false)
108
109/**
110 * @ingroup fatal
111 *
112 * @brief Fatal error reporting with a message, implementation.
113 *
114 * When this macro is hit at runtime the error details will
115 * printed to \c stderr, including the message, file name and line number.
116 * Optionally, if \c fatal is true, the macro
117 * will invoke \c std::terminate(). If \c fatal is false,
118 * the invoking function should return an error code to its caller,
119 * which is expected to call NS_FATAL_ERROR to cause termination.
120 *
121 * @param [in] msg The error message to print, if not empty.
122 * @param [in] fatal Call \c std::terminate() if true.
123 *
124 * This macro is enabled unconditionally in all builds,
125 * including debug and optimized builds.
126 */
127#define NS_FATAL_ERROR_IMPL(msg, fatal) \
128 do \
129 { \
130 std::cerr << "msg=\"" << msg << "\", "; \
131 NS_FATAL_ERROR_IMPL_NO_MSG(fatal); \
132 } while (false)
133
134/**
135 * @ingroup fatal
136 *
137 * @brief Report a fatal error and terminate.
138 *
139 * When this macro is hit at runtime, details of filename
140 * and line number are printed to \c stderr, and the program
141 * is halted by calling \c std::terminate(). This will
142 * trigger any clean up code registered by
143 * \c std::set_terminate (NS3 default is a stream-flushing
144 * code), but may be overridden.
145 *
146 * This macro is enabled unconditionally in all builds,
147 * including debug and optimized builds.
148 */
149#define NS_FATAL_ERROR_NO_MSG() NS_FATAL_ERROR_IMPL_NO_MSG(true)
150
151/**
152 * @ingroup fatal
153 *
154 * @brief Report a fatal error, deferring termination.
155 *
156 * When this macro is hit at runtime, details of filename
157 * and line number are printed to \c stderr, however the program
158 * is _not_ halted. It is expected that the function using this
159 * macro will return an error code, and its caller will
160 * invoke NS_FATAL_ERROR(msg) triggering std::terminate().
161 *
162 * This macro is enabled unconditionally in all builds,
163 * including debug and optimized builds.
164 */
165#define NS_FATAL_ERROR_NO_MSG_CONT() NS_FATAL_ERROR_IMPL_NO_MSG(false)
166
167/**
168 * @ingroup fatal
169 *
170 * @brief Report a fatal error with a message and terminate.
171 *
172 * @param [in] msg message to output when this macro is hit.
173 *
174 * When this macro is hit at runtime, the user-specified
175 * error message are printed to \c stderr, followed by a call
176 * to the NS_FATAL_ERROR_NO_MSG() macro which prints the
177 * details of filename and line number to \c stderr. The
178 * program will be halted by calling \c std::terminate(),
179 * triggering any clean up code registered by
180 * \c std::set_terminate (NS3 default is a stream-flushing
181 * code, but may be overridden).
182 *
183 * This macro is enabled unconditionally in all builds,
184 * including debug and optimized builds.
185 */
186#define NS_FATAL_ERROR(msg) NS_FATAL_ERROR_IMPL(msg, true)
187
188/**
189 * @ingroup fatal
190 *
191 * @brief Report a fatal error with a message, deferring termination.
192 *
193 * When this macro is hit at runtime, details of filename
194 * and line number are printed to \c stderr, however the program
195 * is _not_ halted. It is expected that the function using this
196 * macro will return an error code, and its caller will
197 * invoke NS_FATAL_ERROR(msg) triggering \c std::terminate().
198 *
199 * This macro is enabled unconditionally in all builds,
200 * including debug and optimized builds.
201 */
202#define NS_FATAL_ERROR_CONT(msg) NS_FATAL_ERROR_IMPL(msg, false)
203
204#endif /* FATAL_ERROR_H */
ns3::FatalImpl::RegisterStream(), ns3::FatalImpl::UnregisterStream(), and ns3::FatalImpl::FlushStream...
constexpr std::string_view NS_FATAL_MSG
Output string marking imminent invocation of std::terminate.
Definition fatal-error.h:73
Debug message logging.
Every class exported by the ns3 library is enclosed in the ns3 namespace.