LLDB  mainline
Status.h
Go to the documentation of this file.
1 //===-- Status.h ------------------------------------------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
9 #ifndef LLDB_UTILITY_STATUS_H
10 #define LLDB_UTILITY_STATUS_H
11 
12 #include "lldb/lldb-defines.h"
13 #include "lldb/lldb-enumerations.h"
14 #include "llvm/ADT/StringRef.h"
15 #include "llvm/Support/Error.h"
16 #include "llvm/Support/FormatVariadic.h"
17 #include <cstdarg>
18 #include <stdint.h>
19 #include <string>
20 #include <system_error>
21 #include <type_traits>
22 
23 namespace llvm {
24 class raw_ostream;
25 }
26 
27 namespace lldb_private {
28 
29 /// \class Status Status.h "lldb/Utility/Status.h" An error handling class.
30 ///
31 /// This class is designed to be able to hold any error code that can be
32 /// encountered on a given platform. The errors are stored as a value of type
33 /// Status::ValueType. This value should be large enough to hold any and all
34 /// errors that the class supports. Each error has an associated type that is
35 /// of type lldb::ErrorType. New types can be added to support new error
36 /// types, and architecture specific types can be enabled. In the future we
37 /// may wish to switch to a registration mechanism where new error types can
38 /// be registered at runtime instead of a hard coded scheme.
39 ///
40 /// All errors in this class also know how to generate a string representation
41 /// of themselves for printing results and error codes. The string value will
42 /// be fetched on demand and its string value will be cached until the error
43 /// is cleared of the value of the error changes.
44 class Status {
45 public:
46  /// Every error value that this object can contain needs to be able to fit
47  /// into ValueType.
49 
50  /// Default constructor.
51  ///
52  /// Initialize the error object with a generic success value.
53  ///
54  /// \param[in] err
55  /// An error code.
56  ///
57  /// \param[in] type
58  /// The type for \a err.
59  Status();
60 
61  explicit Status(ValueType err,
63 
64  /* implicit */ Status(std::error_code EC);
65 
66  explicit Status(const char *format, ...)
67  __attribute__((format(printf, 2, 3)));
68 
69  Status(const Status &rhs);
70  /// Assignment operator.
71  ///
72  /// \param[in] err
73  /// An error code.
74  ///
75  /// \return
76  /// A const reference to this object.
77  const Status &operator=(const Status &rhs);
78 
79  ~Status();
80 
81  // llvm::Error support
82  explicit Status(llvm::Error error) { *this = std::move(error); }
83  const Status &operator=(llvm::Error error);
84  llvm::Error ToError() const;
85 
86  /// Get the error string associated with the current error.
87  //
88  /// Gets the error value as a NULL terminated C string. The error string
89  /// will be fetched and cached on demand. The error string will be retrieved
90  /// from a callback that is appropriate for the type of the error and will
91  /// be cached until the error value is changed or cleared.
92  ///
93  /// \return
94  /// The error as a NULL terminated C string value if the error
95  /// is valid and is able to be converted to a string value,
96  /// NULL otherwise.
97  const char *AsCString(const char *default_error_str = "unknown error") const;
98 
99  /// Clear the object state.
100  ///
101  /// Reverts the state of this object to contain a generic success value and
102  /// frees any cached error string value.
103  void Clear();
104 
105  /// Test for error condition.
106  ///
107  /// \return
108  /// \b true if this object contains an error, \b false
109  /// otherwise.
110  bool Fail() const;
111 
112  /// Access the error value.
113  ///
114  /// \return
115  /// The error value.
116  ValueType GetError() const;
117 
118  /// Access the error type.
119  ///
120  /// \return
121  /// The error type enumeration value.
122  lldb::ErrorType GetType() const;
123 
124  /// Set accessor from a kern_return_t.
125  ///
126  /// Set accesssor for the error value to \a err and the error type to \c
127  /// MachKernel.
128  ///
129  /// \param[in] err
130  /// A mach error code.
131  void SetMachError(uint32_t err);
132 
133  void SetExpressionError(lldb::ExpressionResults, const char *mssg);
134 
135  int SetExpressionErrorWithFormat(lldb::ExpressionResults, const char *format,
136  ...) __attribute__((format(printf, 3, 4)));
137 
138  /// Set accesssor with an error value and type.
139  ///
140  /// Set accesssor for the error value to \a err and the error type to \a
141  /// type.
142  ///
143  /// \param[in] err
144  /// A mach error code.
145  ///
146  /// \param[in] type
147  /// The type for \a err.
148  void SetError(ValueType err, lldb::ErrorType type);
149 
150  /// Set the current error to errno.
151  ///
152  /// Update the error value to be \c errno and update the type to be \c
153  /// Status::POSIX.
154  void SetErrorToErrno();
155 
156  /// Set the current error to a generic error.
157  ///
158  /// Update the error value to be \c LLDB_GENERIC_ERROR and update the type
159  /// to be \c Status::Generic.
160  void SetErrorToGenericError();
161 
162  /// Set the current error string to \a err_str.
163  ///
164  /// Set accessor for the error string value for a generic errors, or to
165  /// supply additional details above and beyond the standard error strings
166  /// that the standard type callbacks typically provide. This allows custom
167  /// strings to be supplied as an error explanation. The error string value
168  /// will remain until the error value is cleared or a new error value/type
169  /// is assigned.
170  ///
171  /// \param err_str
172  /// The new custom error string to copy and cache.
173  void SetErrorString(llvm::StringRef err_str);
174 
175  /// Set the current error string to a formatted error string.
176  ///
177  /// \param format
178  /// A printf style format string
179  int SetErrorStringWithFormat(const char *format, ...)
180  __attribute__((format(printf, 2, 3)));
181 
182  int SetErrorStringWithVarArg(const char *format, va_list args);
183 
184  template <typename... Args>
185  void SetErrorStringWithFormatv(const char *format, Args &&... args) {
186  SetErrorString(llvm::formatv(format, std::forward<Args>(args)...).str());
187  }
188 
189  /// Test for success condition.
190  ///
191  /// Returns true if the error code in this object is considered a successful
192  /// return value.
193  ///
194  /// \return
195  /// \b true if this object contains an value that describes
196  /// success (non-erro), \b false otherwise.
197  bool Success() const;
198 
199  /// Test for a failure due to a generic interrupt.
200  ///
201  /// Returns true if the error code in this object was caused by an
202  /// interrupt. At present only supports Posix EINTR.
203  ///
204  /// \return
205  /// \b true if this object contains an value that describes
206  /// failure due to interrupt, \b false otherwise.
207  bool WasInterrupted() const;
208 
209 protected:
210  /// Member variables
211  ValueType m_code; ///< Status code as an integer value.
212  lldb::ErrorType m_type; ///< The type of the above error code.
213  mutable std::string m_string; ///< A string representation of the error code.
214 };
215 
216 } // namespace lldb_private
217 
218 namespace llvm {
219 template <> struct format_provider<lldb_private::Status> {
220  static void format(const lldb_private::Status &error, llvm::raw_ostream &OS,
221  llvm::StringRef Options);
222 };
223 }
224 
225 #endif // #ifndef LLDB_UTILITY_STATUS_H
A command line argument class.
Definition: Args.h:32
Enumerations for broadcasting.
Definition: SBLaunchInfo.h:14
Definition: Debugger.h:71
llvm::Error Error
std::string m_string
A string representation of the error code.
Definition: Status.h:213
Generic errors that can be any value.
void SetErrorStringWithFormatv(const char *format, Args &&... args)
Definition: Status.h:185
uint32_t ValueType
Every error value that this object can contain needs to be able to fit into ValueType.
Definition: Status.h:48
lldb::ErrorType m_type
The type of the above error code.
Definition: Status.h:212
An error handling class.
Definition: Status.h:44
ValueType m_code
Member variables.
Definition: Status.h:211