contrib/llvm/tools/lldb/include/lldb/Core/Error.h

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