Rerun C++ SDK
Loading...
Searching...
No Matches
error.hpp
1#pragma once
2
3#include <cstdint>
4#include <string>
5
6#ifdef __cpp_exceptions
7#include <stdexcept>
8#endif
9
10namespace arrow {
11 class Status;
12}
13
14struct rr_error;
15
16/// Return error if a given rerun::Error producing expression is not rerun::ErrorCode::Ok.
17#define RR_RETURN_NOT_OK(status_expr) \
18 do { \
19 const rerun::Error _status_ = status_expr; \
20 if (_status_.is_err()) { \
21 return _status_; \
22 } \
23 } while (false)
24
25namespace rerun {
26 /// Status codes returned by the SDK as part of `Status`.
27 ///
28 /// Category codes are used to group errors together, but are never returned directly.
29 enum class ErrorCode : uint32_t {
30 Ok = 0x0000'0000,
31 OutOfMemory,
32 NotImplemented,
33 SdkVersionMismatch,
34
35 // Invalid argument errors.
36 _CategoryArgument = 0x0000'0010,
37 UnexpectedNullArgument,
38 InvalidStringArgument,
39 InvalidEnumValue,
40 InvalidRecordingStreamHandle,
41 InvalidSocketAddress,
42 InvalidComponentTypeHandle,
43 InvalidTensorDimension,
44 InvalidArchetypeField,
45 FileRead,
46
47 // Recording stream errors
48 _CategoryRecordingStream = 0x0000'0100,
49 RecordingStreamRuntimeFailure,
50 RecordingStreamCreationFailure,
51 RecordingStreamSaveFailure,
52 RecordingStreamStdoutFailure,
53 RecordingStreamSpawnFailure,
54 RecordingStreamChunkValidationFailure,
55
56 // Arrow data processing errors.
57 _CategoryArrow = 0x0000'1000,
58 ArrowFfiSchemaImportError,
59 ArrowFfiArrayImportError,
60
61 // Utility errors.
62 _CategoryUtilities = 0x0001'0000,
63 VideoLoadError,
64
65 // Errors relating to file IO.
66 _CategoryFileIO = 0x0010'0000,
67 FileOpenFailure,
68
69 // Errors directly translated from arrow::StatusCode.
70 _CategoryArrowCppStatus = 0x1000'0000,
71 ArrowStatusCode_KeyError,
72 ArrowStatusCode_TypeError,
73 ArrowStatusCode_Invalid,
74 ArrowStatusCode_IOError,
75 ArrowStatusCode_CapacityError,
76 ArrowStatusCode_IndexError,
77 ArrowStatusCode_Cancelled,
78 ArrowStatusCode_UnknownError,
79 ArrowStatusCode_NotImplemented,
80 ArrowStatusCode_SerializationError,
81 ArrowStatusCode_RError,
82 ArrowStatusCode_CodeGenError,
83 ArrowStatusCode_ExpressionValidationError,
84 ArrowStatusCode_ExecutionError,
85 ArrowStatusCode_AlreadyExists,
86
87 Unknown = 0xFFFF'FFFF,
88 };
89
90 /// Callback function type for log handlers.
91 using StatusLogHandler = void (*)(const class Error& status, void* userdata);
92
93 /// Status outcome object (success or error) returned for fallible operations.
94 ///
95 /// Converts to `true` for success, `false` for failure.
96 class [[nodiscard]] Error {
97 public:
98 /// Result code for the given operation.
99 ErrorCode code = ErrorCode::Ok;
100
101 /// Human readable description of the error.
102 std::string description;
103
104 public:
105 Error() = default;
106
107 Error(ErrorCode _code, std::string _description)
108 : code(_code), description(std::move(_description)) {}
109
110 /// Construct from a C status object.
111 Error(const rr_error& status);
112
113 /// Construct from an arrow status.
114 Error(const arrow::Status& status);
115
116 /// Creates a new error set to ok.
117 static Error ok() {
118 return Error();
119 }
120
121 /// Compare two errors for equality. Requires the description to match.
122 bool operator==(const Error& other) const {
123 return code == other.code && description == other.description;
124 }
125
126 /// Returns true if the code is `Ok`.
127 bool is_ok() const {
128 return code == ErrorCode::Ok;
129 }
130
131 /// Returns true if the code is not `Ok`.
132 bool is_err() const {
133 return code != ErrorCode::Ok;
134 }
135
136 /// Sets global log handler called for `handle`.
137 ///
138 /// The default will log to stderr, unless `RERUN_STRICT` is set to something truthy.
139 ///
140 /// \param handler The handler to call, or `nullptr` to reset to the default.
141 /// \param userdata Userdata pointer that will be passed to each invocation of the handler.
142 ///
143 /// @see log, log_on_failure
144 static void set_log_handler(StatusLogHandler handler, void* userdata = nullptr);
145
146 /// Handle this error based on the set log handler.
147 ///
148 /// If there is no error, nothing happens.
149 ///
150 /// If you have set a log handler with `set_log_handler`, it will be called.
151 /// Else if the `RERUN_STRICT` env-var is set to something truthy,
152 /// an exception will be thrown (if `__cpp_exceptions` are enabled),
153 /// or the program will abort.
154 ///
155 /// If no log handler is installed, and we are not in strict mode,
156 /// the error will be logged to stderr.
157 void handle() const;
158
159 /// Calls the `handle` method and then exits the application with code 1 if the error is not `Ok`.
160 /// @see throw_on_failure
161 void exit_on_failure() const;
162
163 /// Throws a `std::runtime_error` if the status is not `Ok`.
164 ///
165 /// If exceptions are disabled, this will forward to `exit_on_failure` instead.
166 /// @see exit_on_failure
167 void throw_on_failure() const {
168#ifdef __cpp_exceptions
169 if (is_err()) {
170 throw std::runtime_error(description);
171 }
172#else
173 exit_on_failure();
174#endif
175 }
176 };
177} // namespace rerun
Status outcome object (success or error) returned for fallible operations.
Definition error.hpp:96
void handle() const
Handle this error based on the set log handler.
bool is_err() const
Returns true if the code is not Ok.
Definition error.hpp:132
bool is_ok() const
Returns true if the code is Ok.
Definition error.hpp:127
static Error ok()
Creates a new error set to ok.
Definition error.hpp:117
static void set_log_handler(StatusLogHandler handler, void *userdata=nullptr)
Sets global log handler called for handle.
void throw_on_failure() const
Throws a std::runtime_error if the status is not Ok.
Definition error.hpp:167
Error(const rr_error &status)
Construct from a C status object.
bool operator==(const Error &other) const
Compare two errors for equality. Requires the description to match.
Definition error.hpp:122
ErrorCode code
Result code for the given operation.
Definition error.hpp:99
Error(const arrow::Status &status)
Construct from an arrow status.
void exit_on_failure() const
Calls the handle method and then exits the application with code 1 if the error is not Ok.
std::string description
Human readable description of the error.
Definition error.hpp:102
All Rerun C++ types and functions are in the rerun namespace or one of its nested namespaces.
Definition rerun.hpp:23
void(*)(const class Error &status, void *userdata) StatusLogHandler
Callback function type for log handlers.
Definition error.hpp:91
ErrorCode
Status codes returned by the SDK as part of Status.
Definition error.hpp:29