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/**
21 * \file
22 * \ingroup fatal
23 * \brief \c NS_FATAL_x macro definitions.
24 */
25
26/**
27 * \ingroup core
28 * \defgroup fatal Fatal Error Handlers
29 *
30 * \brief Functions to help clean up when a fatal error
31 * is encountered.
32 *
33 * The functions in this group are used to perform
34 * limited clean up, like flushing active streams, when
35 * fatal errors are encountered (through assertion fail,
36 * calls to NS_ABORT_* or calls to NS_FATAL_ERROR).
37 *
38 * Currently, other than flushing active ostreams, these
39 * functions does not interfere with outside memory. There
40 * is still a residual risk that invalid ostream
41 * pointers may be present, and may corrupt the memory
42 * on the attempt to execute the flush() function.
43 */
44
45namespace ns3
46{
47
48/**
49 * \ingroup fatal
50 *
51 * \brief Output string marking imminent invocation of std::terminate.
52 *
53 * This is useful to know when capturing output and you want to strip
54 * system and compiler-dependent messages generated by std::terminate.
55 */
56constexpr std::string_view NS_FATAL_MSG{"NS_FATAL, terminating"};
57
58} // namespace ns3
59
60/**
61 * \ingroup fatal
62 *
63 * \brief Fatal error reporting with no message, implementation.
64 *
65 * When this macro is hit at runtime the error details will
66 * printed to \c stderr, including the file name and line number.
67 * Optionally, if \c fatal is true, the macro
68 * will invoke \c std::terminate(). If \c fatal is false,
69 * the invoking function should return an error code to its caller,
70 * which is expected to call NS_FATAL_ERROR to cause termination.
71 *
72 * \param [in] fatal Call \c std::terminate() if true.
73 *
74 * This macro is enabled unconditionally in all builds,
75 * including debug and optimized builds.
76 */
77#define NS_FATAL_ERROR_IMPL_NO_MSG(fatal) \
78 do \
79 { \
80 NS_LOG_APPEND_TIME_PREFIX_IMPL; \
81 NS_LOG_APPEND_NODE_PREFIX_IMPL; \
82 std::cerr << "file=" << __FILE__ << ", line=" << __LINE__ << std::endl; \
83 ::ns3::FatalImpl::FlushStreams(); \
84 if (fatal) \
85 { \
86 std::cerr << ns3::NS_FATAL_MSG << std::endl; \
87 std::terminate(); \
88 } \
89 } while (false)
90
91/**
92 * \ingroup fatal
93 *
94 * \brief Fatal error reporting with a message, implementation.
95 *
96 * When this macro is hit at runtime the error details will
97 * printed to \c stderr, including the message, file name and line number.
98 * Optionally, if \c fatal is true, the macro
99 * will invoke \c std::terminate(). If \c fatal is false,
100 * the invoking function should return an error code to its caller,
101 * which is expected to call NS_FATAL_ERROR to cause termination.
102 *
103 * \param [in] msg The error message to print, if not empty.
104 * \param [in] fatal Call \c std::terminate() if true.
105 *
106 * This macro is enabled unconditionally in all builds,
107 * including debug and optimized builds.
108 */
109#define NS_FATAL_ERROR_IMPL(msg, fatal) \
110 do \
111 { \
112 std::cerr << "msg=\"" << msg << "\", "; \
113 NS_FATAL_ERROR_IMPL_NO_MSG(fatal); \
114 } while (false)
115
116/**
117 * \ingroup fatal
118 *
119 * \brief Report a fatal error and terminate.
120 *
121 * When this macro is hit at runtime, details of filename
122 * and line number are printed to \c stderr, and the program
123 * is halted by calling \c std::terminate(). This will
124 * trigger any clean up code registered by
125 * \c std::set_terminate (NS3 default is a stream-flushing
126 * code), but may be overridden.
127 *
128 * This macro is enabled unconditionally in all builds,
129 * including debug and optimized builds.
130 */
131#define NS_FATAL_ERROR_NO_MSG() NS_FATAL_ERROR_IMPL_NO_MSG(true)
132
133/**
134 * \ingroup fatal
135 *
136 * \brief Report a fatal error, deferring termination.
137 *
138 * When this macro is hit at runtime, details of filename
139 * and line number are printed to \c stderr, however the program
140 * is _not_ halted. It is expected that the function using this
141 * macro will return an error code, and its caller will
142 * invoke NS_FATAL_ERROR(msg) triggering std::terminate().
143 *
144 * This macro is enabled unconditionally in all builds,
145 * including debug and optimized builds.
146 */
147#define NS_FATAL_ERROR_NO_MSG_CONT() NS_FATAL_ERROR_IMPL_NO_MSG(false)
148
149/**
150 * \ingroup fatal
151 *
152 * \brief Report a fatal error with a message and terminate.
153 *
154 * \param [in] msg message to output when this macro is hit.
155 *
156 * When this macro is hit at runtime, the user-specified
157 * error message are printed to \c stderr, followed by a call
158 * to the NS_FATAL_ERROR_NO_MSG() macro which prints the
159 * details of filename and line number to \c stderr. The
160 * program will be halted by calling \c std::terminate(),
161 * triggering any clean up code registered by
162 * \c std::set_terminate (NS3 default is a stream-flushing
163 * code, but may be overridden).
164 *
165 * This macro is enabled unconditionally in all builds,
166 * including debug and optimized builds.
167 */
168#define NS_FATAL_ERROR(msg) NS_FATAL_ERROR_IMPL(msg, true)
169
170/**
171 * \ingroup fatal
172 *
173 * \brief Report a fatal error with a message, deferring termination.
174 *
175 * When this macro is hit at runtime, details of filename
176 * and line number are printed to \c stderr, however the program
177 * is _not_ halted. It is expected that the function using this
178 * macro will return an error code, and its caller will
179 * invoke NS_FATAL_ERROR(msg) triggering \c std::terminate().
180 *
181 * This macro is enabled unconditionally in all builds,
182 * including debug and optimized builds.
183 */
184#define NS_FATAL_ERROR_CONT(msg) NS_FATAL_ERROR_IMPL(msg, false)
185
186#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:56
Debug message logging.
Every class exported by the ns3 library is enclosed in the ns3 namespace.