First version of a class to represent operating system and lib/System

error codes in a platform independent way.

llvm-svn: 15761

llvm/include/llvm/System/ErrorCode.h

@@ -0,0 +1,208 @@
+//===- ErrorCode.h - Declare ErrorCode class --------------------*- C++ -*-===//
+//
+// Copyright (C) 2004 eXtensible Systems, Inc. All Rights Reserved.
+//
+// This program is open source software; you can redistribute it and/or modify
+// it under the terms of the University of Illinois Open Source License. See
+// LICENSE.TXT (distributed with this software) for details.
+//
+// This program is distributed in the hope that it will be useful, but
+// WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+// or FITNESS FOR A PARTICULAR PURPOSE.
+//
+//===----------------------------------------------------------------------===//
+/// @file lib/System/ErrorCode.h
+/// @author Reid Spencer <raspencer@x10sys.com> (original author)
+/// @version \verbatim $Id$ \endverbatim
+/// @date 2004/08/14
+/// @since 1.4
+/// @brief Declares the llvm::sys::ErrorCode class.
+//===----------------------------------------------------------------------===//
+#ifndef LLVM_SYSTEM_ERRORCODE_H
+#define LLVM_SYSTEM_ERRORCODE_H
+
+#include <string>
+
+/// @brief Computes an errorcode value from its domain and index values.
+#define LLVM_ERROR_CODE( domain, index ) \
+    ( ( domain << ::llvm::sys::ERROR_DOMAIN_SHIFT ) + \
+      ( index & ::llvm::sys::ERROR_INDEX_MASK ))
+
+namespace llvm {
+namespace sys {
+
+  /// @brief The number of bits to shift right to get the domain part of an error code.
+  const uint32_t ERROR_DOMAIN_SHIFT = (sizeof(uint32_t)*8)*3/4;
+
+  const uint32_t ERROR_DOMAIN_MASK =
+    ((1<<((sizeof(uint32_t)*8)-ERROR_DOMAIN_SHIFT))-1)<<ERROR_DOMAIN_SHIFT;
+
+  /// @brief The mask to get only the index part of an error code.
+  const uint32_t ERROR_INDEX_MASK = ( 1 << ERROR_DOMAIN_SHIFT) - 1;
+
+  /// @brief The maximum value for the index part of an error code.
+  const uint32_t MAX_ERROR_INDEX= ERROR_INDEX_MASK;
+
+  /// @brief The minimum value for the index part of an error code.
+  const uint32_t MIN_ERROR_INDEX= 1;
+
+  /// @brief A constant to represent the non error condition.
+  const uint32_t NOT_AN_ERROR = 0;
+
+  /// @brief An enumeration of the possible error code domains
+  enum ErrorDomains {
+    OSDomain = 0,     ///< The domain of operating system specific error codes
+    SystemDomain = 1, ///< The domain of lib/System specific error codes
+  };
+
+  /// @brief An enumeration of the error codes defined by lib/System.
+  enum SystemErrors {
+    ERR_SYS_INVALID_ARG = LLVM_ERROR_CODE(SystemDomain,1),
+  };
+
+  /// This class provides the error code value for every error that the System
+  /// library can produce. It simply partitions a uint32_t into a domain part
+  /// (top 8 bits) and an index part (low 24 bits). This is necessary since 
+  /// lib/System can generate its own error codes and there needs to be a way
+  /// to distinguish them from the operating system errors.
+  ///
+  /// Note that ErrorCode is the only way to determine if an error occurred
+  /// resulting from a lib/System call. lib/System will (by design) never throw
+  /// an exception. This is done to make lib/System calls very efficient and to
+  /// avoid the overhead of exception processing since most of the time the
+  /// calls will succeed.
+  ///
+  /// There are various methods on the ErrorCode class to translate the error
+  /// code into a readable string, should the need arise. There are also methods
+  /// to distinguish the kind of error and this works in a platform agnostic
+  /// way for most of the common cases.
+  ///
+  /// @since 1.4
+  /// @brief Provides a 32 bit error code that encapsulates error domain and 
+  /// index.
+  class ErrorCode
+  {
+  /// @name Constructors
+  /// @{
+  public:
+
+    /// This constructor instantiates a new ErrorCode object
+    /// with a "no error" error code.
+    /// @brief Constructor.
+    ErrorCode() throw() : Code(NOT_AN_ERROR) {}
+
+    /// This constructor instantiates a new ErrorCode object
+    /// with an integer code.
+    /// @brief Constructor.
+    ErrorCode (uint32_t code) throw() : Code(code) {}
+
+    /// This constructor instantiates a new ErrorCode object
+    /// with an integer code.
+    /// @brief Constructor.
+    ErrorCode(int code) throw()
+      : Code ( static_cast<uint32_t>( code ) ) { }
+
+    /// Copies one ErrorCode to another.
+    /// @brief Copy Constructor.
+    ErrorCode(const ErrorCode& that) throw() : Code ( that.Code ) { }
+
+    /// Nothing much to do.
+    /// @brief Destructor
+    ~ErrorCode(void) throw() {}
+
+  /// @}
+  /// @name Operators
+  /// @{
+  public:
+    /// Assigns one ErrorCode object to another
+    /// @brief Assignment Operator.
+    ErrorCode & operator = (const ErrorCode& that) throw() {
+      Code = that.Code;
+      return *this;
+    }
+
+    /// Returns true if \p this and \p that refer to the same type of error
+    /// @brief Equality Operator.
+    bool operator == (const ErrorCode& that) const throw() {
+      return Code == that.Code;
+    }
+
+    /// Returns true if \p this and \p that do not refer to the same type of error
+    /// @brief Inequality Operator.
+    bool operator != (const ErrorCode& that) const throw() {
+      return Code != that.Code;
+    }
+
+    /// @return a non zero value if an error condition exists
+    /// @brief Test Operator
+    operator bool() const throw() { return Code == NOT_AN_ERROR; }
+
+    /// @return a non zero value if an error condition exists
+    /// @brief Test Operator.
+    operator int() const throw() { return Code; }
+
+    /// @brief unsigned conversion operator.
+    operator unsigned int() const throw() { return Code; }
+
+    /// @brief long conversion operator.
+    operator long() const throw() { return Code; }
+
+    /// @brief unsigned long conversion operator
+    operator unsigned long() const throw() { return Code; }
+
+  /// @}
+  /// @name Accessors
+  /// @{
+  public:
+    /// @returns the integer error code value.
+    /// @brief Provides the integer error code value.
+    uint32_t code() const throw() { return Code; }
+
+    /// @returns the integer domain number for the error number
+    /// @brief Provides the domain of the error
+    uint32_t domain() const throw() {
+      return (Code & ERROR_DOMAIN_MASK) >> ERROR_DOMAIN_SHIFT;
+    }
+
+    /// @brief Provides the index of the error
+    uint32_t index() const throw() {
+      return Code & ERROR_INDEX_MASK;
+    }
+
+    /// @brief Provides a readable string related to the error code
+    std::string description() const throw();
+
+    /// If \p this ErrorCode and \p ec have the same error code then return 
+    /// true, otherwise false.
+    /// @param ec An errorcode value to compare against this ErrorCode
+    /// @returns true if \p this ErrorCode has the same error code as \p errcode
+    /// @brief Determines identity of the error code.
+    bool is( const ErrorCode& ec ) const throw() { return Code == ec.Code; }
+
+  /// @}
+  /// @name Mutators
+  /// @{
+  public:
+    /// @returns the previous integer error code value.
+    /// @brief allows the integer error code to be set.
+    uint32_t code(uint32_t code) throw() {
+      uint32_t old_code = Code;
+      Code = code;
+      return old_code;
+    }
+
+  /// @}
+  /// @name Data
+  /// @{
+  private:
+    uint32_t Code; ///< The error code value
+  /// @}
+
+  };
+
+}
+}
+
+// vim: sw=2 smartindent smarttab tw=80 autoindent expandtab
+
+#endif