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

   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.
  48   typedef uint32_t 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,
  62                   lldb::ErrorType type = lldb::eErrorTypeGeneric);
  63
  64   /* implicit */ Status(std::error_code EC);
  65
  66   explicit Status(const char *format, ...)
  67       __attribute__((format(printf, 2, 3)));
  68
  69   /// Assignment operator.
  70   ///
  71   /// \param[in] err
  72   ///     An error code.
  73   ///
  74   /// \return
  75   ///     A const reference to this object.
  76   const Status &operator=(const Status &rhs);
  77
  78   ~Status();
  79
  80   // llvm::Error support
  81   explicit Status(llvm::Error error) { *this = std::move(error); }
  82   const Status &operator=(llvm::Error error);
  83   llvm::Error ToError() const;
  84
  85   /// Get the error string associated with the current error.
  86   //
  87   /// Gets the error value as a NULL terminated C string. The error string
  88   /// will be fetched and cached on demand. The error string will be retrieved
  89   /// from a callback that is appropriate for the type of the error and will
  90   /// be cached until the error value is changed or cleared.
  91   ///
  92   /// \return
  93   ///     The error as a NULL terminated C string value if the error
  94   ///     is valid and is able to be converted to a string value,
  95   ///     NULL otherwise.
  96   const char *AsCString(const char *default_error_str = "unknown error") const;
  97
  98   /// Clear the object state.
  99   ///
 100   /// Reverts the state of this object to contain a generic success value and
 101   /// frees any cached error string value.
 102   void Clear();
 103
 104   /// Test for error condition.
 105   ///
 106   /// \return
 107   ///     \b true if this object contains an error, \b false
 108   ///     otherwise.
 109   bool Fail() const;
 110
 111   /// Access the error value.
 112   ///
 113   /// \return
 114   ///     The error value.
 115   ValueType GetError() const;
 116
 117   /// Access the error type.
 118   ///
 119   /// \return
 120   ///     The error type enumeration value.
 121   lldb::ErrorType GetType() const;
 122
 123   /// Set accessor from a kern_return_t.
 124   ///
 125   /// Set accesssor for the error value to \a err and the error type to \c
 126   /// MachKernel.
 127   ///
 128   /// \param[in] err
 129   ///     A mach error code.
 130   void SetMachError(uint32_t err);
 131
 132   void SetExpressionError(lldb::ExpressionResults, const char *mssg);
 133
 134   int SetExpressionErrorWithFormat(lldb::ExpressionResults, const char *format,
 135                                    ...) __attribute__((format(printf, 3, 4)));
 136
 137   /// Set accesssor with an error value and type.
 138   ///
 139   /// Set accesssor for the error value to \a err and the error type to \a
 140   /// type.
 141   ///
 142   /// \param[in] err
 143   ///     A mach error code.
 144   ///
 145   /// \param[in] type
 146   ///     The type for \a err.
 147   void SetError(ValueType err, lldb::ErrorType type);
 148
 149   /// Set the current error to errno.
 150   ///
 151   /// Update the error value to be \c errno and update the type to be \c
 152   /// Status::POSIX.
 153   void SetErrorToErrno();
 154
 155   /// Set the current error to a generic error.
 156   ///
 157   /// Update the error value to be \c LLDB_GENERIC_ERROR and update the type
 158   /// to be \c Status::Generic.
 159   void SetErrorToGenericError();
 160
 161   /// Set the current error string to \a err_str.
 162   ///
 163   /// Set accessor for the error string value for a generic errors, or to
 164   /// supply additional details above and beyond the standard error strings
 165   /// that the standard type callbacks typically provide. This allows custom
 166   /// strings to be supplied as an error explanation. The error string value
 167   /// will remain until the error value is cleared or a new error value/type
 168   /// is assigned.
 169   ///
 170   /// \param err_str
 171   ///     The new custom error string to copy and cache.
 172   void SetErrorString(llvm::StringRef err_str);
 173
 174   /// Set the current error string to a formatted error string.
 175   ///
 176   /// \param format
 177   ///     A printf style format string
 178   int SetErrorStringWithFormat(const char *format, ...)
 179       __attribute__((format(printf, 2, 3)));
 180
 181   int SetErrorStringWithVarArg(const char *format, va_list args);
 182
 183   template <typename... Args>
 184   void SetErrorStringWithFormatv(const char *format, Args &&... args) {
 185     SetErrorString(llvm::formatv(format, std::forward<Args>(args)...).str());
 186   }
 187
 188   /// Test for success condition.
 189   ///
 190   /// Returns true if the error code in this object is considered a successful
 191   /// return value.
 192   ///
 193   /// \return
 194   ///     \b true if this object contains an value that describes
 195   ///     success (non-erro), \b false otherwise.
 196   bool Success() const;
 197
 198   /// Test for a failure due to a generic interrupt.
 199   ///
 200   /// Returns true if the error code in this object was caused by an
 201   /// interrupt. At present only supports Posix EINTR.
 202   ///
 203   /// \return
 204   ///     \b true if this object contains an value that describes
 205   ///     failure due to interrupt, \b false otherwise.
 206   bool WasInterrupted() const;
 207
 208 protected:
 209   /// Member variables
 210   ValueType m_code;             ///< Status code as an integer value.
 211   lldb::ErrorType m_type;       ///< The type of the above error code.
 212   mutable std::string m_string; ///< A string representation of the error code.
 213 };
 214
 215 } // namespace lldb_private
 216
 217 namespace llvm {
 218 template <> struct format_provider<lldb_private::Status> {
 219   static void format(const lldb_private::Status &error, llvm::raw_ostream &OS,
 220                      llvm::StringRef Options);
 221 };
 222 }
 223
 224 #endif // #ifndef LLDB_UTILITY_STATUS_H