2 * Copyright (C) 2022 Jérémie Galarneau <jeremie.galarneau@efficios.com>
4 * SPDX-License-Identifier: LGPL-2.1-only
8 #ifndef LTTNG_EXCEPTION_H_
9 #define LTTNG_EXCEPTION_H_
11 #include <common/string-utils/c-string-view.hpp>
13 #include <lttng/lttng-error.h>
17 #include <system_error>
19 #define LTTNG_SOURCE_LOCATION() lttng::source_location(__FILE__, __func__, __LINE__)
21 #define LTTNG_THROW_CTL(msg, error_code) \
22 throw lttng::ctl::error(msg, error_code, LTTNG_SOURCE_LOCATION())
23 #define LTTNG_THROW_POSIX(msg, errno_code) \
24 throw lttng::posix_error(msg, errno_code, LTTNG_SOURCE_LOCATION())
25 #define LTTNG_THROW_ERROR(msg) throw lttng::runtime_error(msg, LTTNG_SOURCE_LOCATION())
26 #define LTTNG_THROW_UNSUPPORTED_ERROR(msg) \
27 throw lttng::unsupported_error(msg, LTTNG_SOURCE_LOCATION())
28 #define LTTNG_THROW_COMMUNICATION_ERROR(msg) \
29 throw lttng::communication_error(msg, LTTNG_SOURCE_LOCATION())
30 #define LTTNG_THROW_PROTOCOL_ERROR(msg) throw lttng::protocol_error(msg, LTTNG_SOURCE_LOCATION())
31 #define LTTNG_THROW_INVALID_ARGUMENT_ERROR(msg) \
32 throw lttng::invalid_argument_error(msg, LTTNG_SOURCE_LOCATION())
36 * @class source_location
37 * @brief Represents the location in the source code where an exception was thrown.
39 * The source_location class captures the file name, function name, and line number
40 * of the source code where an exception occurs. This information is useful for
41 * debugging and logging purposes.
44 * This class provides:
45 * - The name of the source file (file_name).
46 * - The name of the function (function_name).
47 * - The line number in the source file (line_number).
52 * // Code that may throw an exception.
53 * } catch (const lttng::runtime_error& ex) {
54 * // Handle the exception, possibly logging location information.
55 * ERR_FMT("{} [{}]", ex.what(), ex.source_location);
59 class source_location {
61 source_location(lttng::c_string_view file_name_,
62 lttng::c_string_view function_name_,
63 unsigned int line_number_) :
64 file_name(file_name_), function_name(function_name_), line_number(line_number_)
68 lttng::c_string_view file_name;
69 lttng::c_string_view function_name;
70 unsigned int line_number;
74 * @class runtime_error
75 * @brief Base type for all LTTng exceptions.
77 * Exceptions in the project provide an error message (through the usual what() method), but that
78 * message may not include the whole context of the error. For example, it is not always desirable
79 * to include the source location in a user-facing message.
81 * As such, exception handlers should mind the type of the exception being thrown and consider
82 * what context is suitable to extract (e.g. some context may only be relevant at the DEBUG logging
83 * level, while the error message may be user-facing).
85 * Since 'what()' is marked as noexcept, derived classes should format their generic message during
86 * their construction and pass it to the runtime_error constructor.
88 class runtime_error : public std::runtime_error {
90 runtime_error(const std::string& msg, const lttng::source_location& source_location);
92 lttng::source_location source_location;
96 * @class unsupported_error
97 * @brief Represents an error for unsupported features.
99 * This error may occur due to the current configuration making a feature unavailable
100 * (e.g. when using an older kernel or tracer release).
102 class unsupported_error : public lttng::runtime_error {
104 explicit unsupported_error(const std::string& msg,
105 const lttng::source_location& source_location);
111 * @brief Wraps lttng_error_code errors for reporting through liblttng-ctl's interface.
113 * There is typically a better way to report errors than using this type of exception. However, it
114 * is sometimes useful to transition legacy code to use RAII facilities and exceptions without
115 * revisiting every caller.
117 class error : public runtime_error {
119 explicit error(const std::string& msg,
120 lttng_error_code error_code,
121 const lttng::source_location& source_location);
123 lttng_error_code code() const noexcept
129 const lttng_error_code _error_code;
131 } /* namespace ctl */
135 * @brief Wraps a POSIX system error, including the location where the error occurred.
137 class posix_error : public std::system_error, lttng::runtime_error {
139 explicit posix_error(const std::string& msg,
140 unsigned int errno_code,
141 const lttng::source_location& source_location);
145 * @class communication_error
146 * @brief Base class for communication errors between components.
148 class communication_error : public lttng::runtime_error {
150 explicit communication_error(const std::string& msg,
151 const lttng::source_location& source_location);
155 * @class protocol_error
156 * @brief Base class for protocol layer communication errors (encoding or decoding problems).
158 class protocol_error : public communication_error {
160 explicit protocol_error(const std::string& msg,
161 const lttng::source_location& source_location);
165 * @class invalid_argument_error
166 * @brief Represents an error for invalid arguments.
168 class invalid_argument_error : public lttng::runtime_error {
170 explicit invalid_argument_error(const std::string& msg,
171 const lttng::source_location& source_location);
174 } /* namespace lttng */
177 * Specialize fmt::formatter for lttng::source_location
179 * Due to a bug in g++ < 7.1, this specialization must be enclosed in the fmt namespace,
180 * see https://gcc.gnu.org/bugzilla/show_bug.cgi?id=56480.
184 struct formatter<lttng::source_location> : formatter<std::string> {
185 template <typename FormatContextType>
186 typename FormatContextType::iterator format(const lttng::source_location& location,
187 FormatContextType& ctx)
189 return format_to(ctx.out(),
191 location.function_name.data(),
192 location.file_name.data(),
193 location.line_number);
196 } /* namespace fmt */
198 #endif /* LTTNG_EXCEPTION_H_ */