include/llvm/System/ErrorCode.h

   1 //===- ErrorCode.h - Declare ErrorCode class --------------------*- C++ -*-===//
   2 //
   3 // Copyright (C) 2004 eXtensible Systems, Inc. All Rights Reserved.
   4 //
   5 // This program is open source software; you can redistribute it and/or modify
   6 // it under the terms of the University of Illinois Open Source License. See
   7 // LICENSE.TXT (distributed with this software) for details.
   8 //
   9 // This program is distributed in the hope that it will be useful, but
  10 // WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  11 // or FITNESS FOR A PARTICULAR PURPOSE.
  12 //
  13 //===----------------------------------------------------------------------===//
  14 /// @file lib/System/ErrorCode.h
  15 /// @author Reid Spencer <raspencer@x10sys.com> (original author)
  16 /// @version \verbatim $Id$ \endverbatim
  17 /// @date 2004/08/14
  18 /// @since 1.4
  19 /// @brief Declares the llvm::sys::ErrorCode class.
  20 //===----------------------------------------------------------------------===//
  21 #ifndef LLVM_SYSTEM_ERRORCODE_H
  22 #define LLVM_SYSTEM_ERRORCODE_H
  23
  24 #include <string>
  25
  26 /// @brief Computes an errorcode value from its domain and index values.
  27 #define LLVM_ERROR_CODE( domain, index ) \
  28     ( ( domain << ::llvm::sys::ERROR_DOMAIN_SHIFT ) + \
  29       ( index & ::llvm::sys::ERROR_INDEX_MASK ))
  30
  31 namespace llvm {
  32 namespace sys {
  33
  34   /// @brief The number of bits to shift right to get the domain part of an error code.
  35   const uint32_t ERROR_DOMAIN_SHIFT = (sizeof(uint32_t)*8)*3/4;
  36
  37   const uint32_t ERROR_DOMAIN_MASK =
  38     ((1<<((sizeof(uint32_t)*8)-ERROR_DOMAIN_SHIFT))-1)<<ERROR_DOMAIN_SHIFT;
  39
  40   /// @brief The mask to get only the index part of an error code.
  41   const uint32_t ERROR_INDEX_MASK = ( 1 << ERROR_DOMAIN_SHIFT) - 1;
  42
  43   /// @brief The maximum value for the index part of an error code.
  44   const uint32_t MAX_ERROR_INDEX= ERROR_INDEX_MASK;
  45
  46   /// @brief The minimum value for the index part of an error code.
  47   const uint32_t MIN_ERROR_INDEX= 1;
  48
  49   /// @brief A constant to represent the non error condition.
  50   const uint32_t NOT_AN_ERROR = 0;
  51
  52   /// @brief An enumeration of the possible error code domains
  53   enum ErrorDomains {
  54     OSDomain = 0,     ///< The domain of operating system specific error codes
  55     SystemDomain = 1, ///< The domain of lib/System specific error codes
  56   };
  57
  58   /// @brief An enumeration of the error codes defined by lib/System.
  59   enum SystemErrors {
  60     ERR_SYS_INVALID_ARG = LLVM_ERROR_CODE(SystemDomain,1),
  61   };
  62
  63   /// This class provides the error code value for every error that the System
  64   /// library can produce. It simply partitions a uint32_t into a domain part
  65   /// (top 8 bits) and an index part (low 24 bits). This is necessary since
  66   /// lib/System can generate its own error codes and there needs to be a way
  67   /// to distinguish them from the operating system errors.
  68   ///
  69   /// Note that ErrorCode is the only way to determine if an error occurred
  70   /// resulting from a lib/System call. lib/System will (by design) never throw
  71   /// an exception. This is done to make lib/System calls very efficient and to
  72   /// avoid the overhead of exception processing since most of the time the
  73   /// calls will succeed.
  74   ///
  75   /// There are various methods on the ErrorCode class to translate the error
  76   /// code into a readable string, should the need arise. There are also methods
  77   /// to distinguish the kind of error and this works in a platform agnostic
  78   /// way for most of the common cases.
  79   ///
  80   /// @since 1.4
  81   /// @brief Provides a 32 bit error code that encapsulates error domain and
  82   /// index.
  83   class ErrorCode
  84   {
  85   /// @name Constructors
  86   /// @{
  87   public:
  88
  89     /// This constructor instantiates a new ErrorCode object
  90     /// with a "no error" error code.
  91     /// @brief Constructor.
  92     ErrorCode() throw() : Code(NOT_AN_ERROR) {}
  93
  94     /// This constructor instantiates a new ErrorCode object
  95     /// with an integer code.
  96     /// @brief Constructor.
  97     ErrorCode (uint32_t code) throw() : Code(code) {}
  98
  99     /// This constructor instantiates a new ErrorCode object
 100     /// with an integer code.
 101     /// @brief Constructor.
 102     ErrorCode(int code) throw()
 103       : Code ( static_cast<uint32_t>( code ) ) { }
 104
 105     /// Copies one ErrorCode to another.
 106     /// @brief Copy Constructor.
 107     ErrorCode(const ErrorCode& that) throw() : Code ( that.Code ) { }
 108
 109     /// Nothing much to do.
 110     /// @brief Destructor
 111     ~ErrorCode(void) throw() {}
 112
 113   /// @}
 114   /// @name Operators
 115   /// @{
 116   public:
 117     /// Assigns one ErrorCode object to another
 118     /// @brief Assignment Operator.
 119     ErrorCode & operator = (const ErrorCode& that) throw() {
 120       Code = that.Code;
 121       return *this;
 122     }
 123
 124     /// Returns true if \p this and \p that refer to the same type of error
 125     /// @brief Equality Operator.
 126     bool operator == (const ErrorCode& that) const throw() {
 127       return Code == that.Code;
 128     }
 129
 130     /// Returns true if \p this and \p that do not refer to the same type of error
 131     /// @brief Inequality Operator.
 132     bool operator != (const ErrorCode& that) const throw() {
 133       return Code != that.Code;
 134     }
 135
 136     /// @return a non zero value if an error condition exists
 137     /// @brief Test Operator
 138     operator bool() const throw() { return Code == NOT_AN_ERROR; }
 139
 140     /// @return a non zero value if an error condition exists
 141     /// @brief Test Operator.
 142     operator int() const throw() { return Code; }
 143
 144     /// @brief unsigned conversion operator.
 145     operator unsigned int() const throw() { return Code; }
 146
 147     /// @brief long conversion operator.
 148     operator long() const throw() { return Code; }
 149
 150     /// @brief unsigned long conversion operator
 151     operator unsigned long() const throw() { return Code; }
 152
 153   /// @}
 154   /// @name Accessors
 155   /// @{
 156   public:
 157     /// @returns the integer error code value.
 158     /// @brief Provides the integer error code value.
 159     uint32_t code() const throw() { return Code; }
 160
 161     /// @returns the integer domain number for the error number
 162     /// @brief Provides the domain of the error
 163     uint32_t domain() const throw() {
 164       return (Code & ERROR_DOMAIN_MASK) >> ERROR_DOMAIN_SHIFT;
 165     }
 166
 167     /// @brief Provides the index of the error
 168     uint32_t index() const throw() {
 169       return Code & ERROR_INDEX_MASK;
 170     }
 171
 172     /// @brief Provides a readable string related to the error code
 173     std::string description() const throw();
 174
 175     /// If \p this ErrorCode and \p ec have the same error code then return
 176     /// true, otherwise false.
 177     /// @param ec An errorcode value to compare against this ErrorCode
 178     /// @returns true if \p this ErrorCode has the same error code as \p errcode
 179     /// @brief Determines identity of the error code.
 180     bool is( const ErrorCode& ec ) const throw() { return Code == ec.Code; }
 181
 182   /// @}
 183   /// @name Mutators
 184   /// @{
 185   public:
 186     /// @returns the previous integer error code value.
 187     /// @brief allows the integer error code to be set.
 188     uint32_t code(uint32_t code) throw() {
 189       uint32_t old_code = Code;
 190       Code = code;
 191       return old_code;
 192     }
 193
 194   /// @}
 195   /// @name Data
 196   /// @{
 197   private:
 198     uint32_t Code; ///< The error code value
 199   /// @}
 200
 201   };
 202
 203 }
 204 }
 205
 206 // vim: sw=2 smartindent smarttab tw=80 autoindent expandtab
 207
 208 #endif