contrib/llvm/tools/lldb/include/lldb/Utility/Status.h

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