From 8b223d86e1742036b8e88b8b30105d1affc6b246 Mon Sep 17 00:00:00 2001 From: Jared Hoberock Date: Thu, 2 Sep 2010 13:58:10 -0700 Subject: [PATCH] Eliminate Thrust-specific names for cuda_errc_t. Make cuda_errc_t a typedef of cudaError_t. Doxygenate thrust/system_error.h and headers in thrust/system. --- thrust/experimental/arch.inl | 2 +- thrust/system/cuda_error.h | 55 +++--------------- thrust/system/detail/cuda_error.inl | 47 ++------------- thrust/system/error_code.h | 80 +++++++++++++++++++++++--- thrust/system/system_error.h | 88 +++++++++++++++++++++++++++++ thrust/system_error.h | 29 ++++++++++ 6 files changed, 201 insertions(+), 100 deletions(-) diff --git a/thrust/experimental/arch.inl b/thrust/experimental/arch.inl index 54dcd46f9..6e7d1592e 100644 --- a/thrust/experimental/arch.inl +++ b/thrust/experimental/arch.inl @@ -50,7 +50,7 @@ inline void checked_get_current_device_properties(cudaDeviceProp &props) } if(current_device < 0) - throw thrust::experimental::system_error(thrust::experimental::cuda_errc::no_device, thrust::experimental::cuda_category()); + throw thrust::experimental::system_error(cudaErrorNoDevice, thrust::experimental::cuda_category()); // cache the result of the introspection call because it is expensive static std::map properties_map; diff --git a/thrust/system/cuda_error.h b/thrust/system/cuda_error.h index 34456b471..8060f21d8 100644 --- a/thrust/system/cuda_error.h +++ b/thrust/system/cuda_error.h @@ -34,6 +34,9 @@ namespace experimental namespace system { +/*! \addtogroup system + * \{ + */ // To construct an error_code after a CUDA Runtime error: // @@ -43,53 +46,8 @@ namespace system namespace cuda_errc { -// XXX maybe we should just use the enum cudaError directly here? -enum cuda_errc_t -{ - // from cuda/include/driver_types.h - // XXX some of these could use better names - success = ::cudaSuccess, - missing_configuration = ::cudaErrorMissingConfiguration, - memory_allocation = ::cudaErrorMemoryAllocation, - initialization_error = ::cudaErrorInitializationError, - launch_failure = ::cudaErrorLaunchFailure, - prior_launch_failure = ::cudaErrorPriorLaunchFailure, - launch_timeout = ::cudaErrorLaunchTimeout, - launch_out_of_resources = ::cudaErrorLaunchOutOfResources, - invalid_device_function = ::cudaErrorInvalidDeviceFunction, - invalid_configuration = ::cudaErrorInvalidConfiguration, - invalid_device = ::cudaErrorInvalidDevice, - invalid_value = ::cudaErrorInvalidValue, - invalid_pitch_value = ::cudaErrorInvalidPitchValue, - invalid_symbol = ::cudaErrorInvalidSymbol, - map_buffer_object_failed = ::cudaErrorMapBufferObjectFailed, - unmap_buffer_object_failed = ::cudaErrorUnmapBufferObjectFailed, - invalid_host_pointer = ::cudaErrorInvalidHostPointer, - invalid_device_pointer = ::cudaErrorInvalidDevicePointer, - invalid_texture = ::cudaErrorInvalidTexture, - invalid_texture_binding = ::cudaErrorInvalidTextureBinding, - invalid_channel_descriptor = ::cudaErrorInvalidChannelDescriptor, - invalid_memcpy_direction = ::cudaErrorInvalidMemcpyDirection, - address_of_constant_error = ::cudaErrorAddressOfConstant, - texture_fetch_failed = ::cudaErrorTextureFetchFailed, - texture_not_bound = ::cudaErrorTextureNotBound, - synchronization_error = ::cudaErrorSynchronizationError, - invalid_filter_setting = ::cudaErrorInvalidFilterSetting, - invalid_norm_setting = ::cudaErrorInvalidNormSetting, - mixed_device_execution = ::cudaErrorMixedDeviceExecution, - cuda_runtime_unloading = ::cudaErrorCudartUnloading, - unknown = ::cudaErrorUnknown, - not_yet_implemented = ::cudaErrorNotYetImplemented, - memory_value_too_large = ::cudaErrorMemoryValueTooLarge, - invalid_resource_handle = ::cudaErrorInvalidResourceHandle, - not_ready = ::cudaErrorNotReady, - cuda_runtime_is_newer_than_driver = ::cudaErrorInsufficientDriver, - set_on_active_process_error = ::cudaErrorSetOnActiveProcess, - no_device = ::cudaErrorNoDevice, - ecc_uncorrectable = ::cudaErrorECCUncorrectable, - startup_failure = ::cudaErrorStartupFailure, - api_failure_base = ::cudaErrorApiFailureBase, -}; // end cuda_errc_t +// typedef cudaError_t to cuda_errc_t so we don't have to update the list +typedef cudaError_t cuda_errc_t; } // end namespace cuda_errc @@ -122,6 +80,9 @@ inline error_condition make_error_condition(cuda_errc::cuda_errc_t e); */ inline const error_category &cuda_category(void); +/*! \} // end system + */ + } // end system diff --git a/thrust/system/detail/cuda_error.inl b/thrust/system/detail/cuda_error.inl index b8040ff41..b5d60989a 100644 --- a/thrust/system/detail/cuda_error.inl +++ b/thrust/system/detail/cuda_error.inl @@ -67,51 +67,12 @@ class cuda_error_category { using namespace cuda_errc; - switch(ev) + if(ev < cudaErrorApiFailureBase) { - case cudaSuccess: return make_error_condition(success); - case cudaErrorMissingConfiguration: return make_error_condition(missing_configuration); - case cudaErrorMemoryAllocation: return make_error_condition(memory_allocation); - case cudaErrorInitializationError: return make_error_condition(initialization_error); - case cudaErrorLaunchFailure: return make_error_condition(launch_failure); - case cudaErrorPriorLaunchFailure: return make_error_condition(prior_launch_failure); - case cudaErrorLaunchTimeout: return make_error_condition(launch_timeout); - case cudaErrorLaunchOutOfResources: return make_error_condition(launch_out_of_resources); - case cudaErrorInvalidDeviceFunction: return make_error_condition(invalid_device_function); - case cudaErrorInvalidConfiguration: return make_error_condition(invalid_configuration); - case cudaErrorInvalidDevice: return make_error_condition(invalid_device); - case cudaErrorInvalidValue: return make_error_condition(invalid_value); - case cudaErrorInvalidPitchValue: return make_error_condition(invalid_pitch_value); - case cudaErrorInvalidSymbol: return make_error_condition(invalid_symbol); - case cudaErrorMapBufferObjectFailed: return make_error_condition(map_buffer_object_failed); - case cudaErrorUnmapBufferObjectFailed: return make_error_condition(unmap_buffer_object_failed); - case cudaErrorInvalidHostPointer: return make_error_condition(invalid_host_pointer); - case cudaErrorInvalidDevicePointer: return make_error_condition(invalid_device_pointer); - case cudaErrorInvalidTexture: return make_error_condition(invalid_texture); - case cudaErrorInvalidTextureBinding: return make_error_condition(invalid_texture_binding); - case cudaErrorInvalidChannelDescriptor:return make_error_condition(invalid_channel_descriptor); - case cudaErrorInvalidMemcpyDirection: return make_error_condition(invalid_memcpy_direction); - case cudaErrorAddressOfConstant: return make_error_condition(address_of_constant_error); - case cudaErrorTextureFetchFailed: return make_error_condition(texture_fetch_failed); - case cudaErrorTextureNotBound: return make_error_condition(texture_not_bound); - case cudaErrorSynchronizationError: return make_error_condition(synchronization_error); - case cudaErrorInvalidFilterSetting: return make_error_condition(invalid_filter_setting); - case cudaErrorInvalidNormSetting: return make_error_condition(invalid_norm_setting); - case cudaErrorMixedDeviceExecution: return make_error_condition(mixed_device_execution); - case cudaErrorCudartUnloading: return make_error_condition(cuda_runtime_unloading); - case cudaErrorUnknown: return make_error_condition(unknown); - case cudaErrorNotYetImplemented: return make_error_condition(not_yet_implemented); - case cudaErrorMemoryValueTooLarge: return make_error_condition(memory_value_too_large); - case cudaErrorInvalidResourceHandle: return make_error_condition(invalid_resource_handle); - case cudaErrorNotReady: return make_error_condition(not_ready); - case cudaErrorInsufficientDriver: return make_error_condition(cuda_runtime_is_newer_than_driver); - case cudaErrorSetOnActiveProcess: return make_error_condition(set_on_active_process_error); - case cudaErrorNoDevice: return make_error_condition(no_device); - case cudaErrorECCUncorrectable: return make_error_condition(ecc_uncorrectable); - case cudaErrorStartupFailure: return make_error_condition(startup_failure); - case cudaErrorApiFailureBase: return make_error_condition(api_failure_base); - default: return system_category().default_error_condition(ev); + return make_error_condition(static_cast(ev)); } + + return system_category().default_error_condition(ev); } }; // end cuda_error_category diff --git a/thrust/system/error_code.h b/thrust/system/error_code.h index ead31cce5..fb9436854 100644 --- a/thrust/system/error_code.h +++ b/thrust/system/error_code.h @@ -37,16 +37,23 @@ namespace system { +/*! \addtogroup system + * \{ + */ + class error_condition; class error_code; - +/*! A metafunction returning whether or not the parameter is an \p error_code enum. + */ template struct is_error_code_enum : public thrust::detail::false_type {}; +/*! A metafunction returning whether or not the parameter is an \p error_condition enum. + */ template struct is_error_condition_enum : public thrust::detail::false_type {}; -// XXX N3000 prefers enum class errc { ... } +// XXX N3092 prefers enum class errc { ... } namespace errc { @@ -153,9 +160,16 @@ template<> struct is_error_condition_enum : public thrust::detail: // [19.5.1.1] class error_category +/*! \brief The class \p error_category serves as a base class for types used to identify the + * source and encoding of a particular category of error code. Classes may be derived + * from \p error_category to support categories of errors in addition to those defined + * in the C++ International Standard. + */ class error_category { public: + /*! Destructor does nothing. + */ inline virtual ~error_category(void); // XXX enable upon c++0x @@ -225,23 +239,27 @@ inline const error_category &system_category(void); // [19.5.2] Class error_code +/*! \brief The class \p error_code describes an object used to hold error code values, such as + * those originating from the operating system or other low-level application program + * interfaces. + */ class error_code { public: // [19.5.2.2] constructors: /*! Effects: Constructs an object of type \p error_code. - * Postconditions: value() == 0 and category() == &system_category(). + * \post value() == 0 and category() == &system_category(). */ inline error_code(void); /*! Effects: Constructs an object of type \p error_code. - * Postconditions: value() == val and category() == &cat. + * \post value() == val and category() == &cat. */ inline error_code(int val, const error_category &cat); /*! Effects: Constructs an object of type \p error_code. - * Postconditions: *this == make_error_code(e). + * \post *this == make_error_code(e). */ template error_code(ErrorCodeEnum e @@ -253,11 +271,11 @@ class error_code // [19.5.2.3] modifiers: - /*! Postconditions: value() == val and category() == &cat. + /*! \post value() == val and category() == &cat. */ inline void assign(int val, const error_category &cat); - /*! Postconditions: *this == make_error_code(e). + /*! \post *this == make_error_code(e). */ template // XXX WAR msvc's problem with enable_if @@ -268,7 +286,7 @@ class error_code #endif // THRUST_HOST_COMPILER_MSVC operator=(ErrorCodeEnum e); - /*! Postconditions: value() == 0 and category() == system_category(). + /*! \post value() == 0 and category() == system_category(). */ inline void clear(void); @@ -331,7 +349,7 @@ template // [19.5.3] class error_condition -/*! The class \p error_condition describes an object used to hold values identifying +/*! \brief The class \p error_condition describes an object used to hold values identifying * error conditions. * * \note \p error_condition values are portable abstractions, while \p error_code values @@ -341,10 +359,24 @@ class error_condition { public: // [19.5.3.2] constructors + + /*! Constructs an object of type \p error_condition. + * \post value() == 0. + * \post category() == generic_category(). + */ inline error_condition(void); + /*! Constructs an object of type \p error_condition. + * \post value() == val. + * \post category() == cat. + */ inline error_condition(int val, const error_category &cat); + /*! Constructs an object of type \p error_condition. + * \post *this == make_error_condition(e). + * \note This constructor shall not participate in overload resolution unless + * is_error_condition_enum::value is true. + */ template error_condition(ErrorConditionEnum e // XXX WAR msvc's problem with enable_if @@ -354,8 +386,21 @@ class error_condition ); // [19.5.3.3] modifiers + + /*! Assigns to this \p error_code object from an error value and an \p error_category. + * \param val The new value to return from value(). + * \param cat The new \p error_category to return from category(). + * \post value() == val. + * \post category() == cat. + */ inline void assign(int val, const error_category &cat); + /*! Assigns to this \p error_code object from an error condition enumeration. + * \return *this + * \post *this == make_error_condition(e). + * \note This operator shall not participate in overload resolution unless + * is_error_condition_enum::value is true. + */ template // XXX WAR msvc's problem with enable_if #if THRUST_HOST_COMPILER != THRUST_HOST_COMPILER_MSVC @@ -365,18 +410,31 @@ class error_condition #endif // THRUST_HOST_COMPILER != THRUST_HOST_COMPILER_MSVC operator=(ErrorConditionEnum e); + /*! Clears this \p error_code object. + * \post value == 0 + * \post category() == generic_category(). + */ inline void clear(void); // [19.5.3.4] observers + + /*! \return The value encoded by this \p error_condition. + */ inline int value(void) const; + /*! \return A const reference to the \p error_category encoded by this \p error_condition. + */ inline const error_category &category(void) const; + /*! \return category().message(value()). + */ inline std::string message(void) const; // XXX replace below with this upon c++0x //explicit operator bool (void) const; + /*! \return value() != 0. + */ inline operator bool (void) const; /*! \cond @@ -447,9 +505,13 @@ inline bool operator!=(const error_condition &lhs, const error_code &rhs); */ inline bool operator!=(const error_condition &lhs, const error_condition &rhs); +/*! \} // end system + */ + } // end system + // import names into thrust:: using system::error_category; using system::error_code; diff --git a/thrust/system/system_error.h b/thrust/system/system_error.h index a511ba269..837e4b933 100644 --- a/thrust/system/system_error.h +++ b/thrust/system/system_error.h @@ -41,10 +41,50 @@ namespace system // [19.5.5.1] Class system_error overview +/*! \addtogroup system + * \{ + */ + /*! \brief The class \p system_error describes an exception object used to report error * conditions that have an associated \p error_code. Such error conditions typically * originate from the operating system or other low-level application program interfaces. * + * Thrust uses \p system_error to report the error codes returned from device backends + * such as the CUDA runtime. + * + * The following code listing demonstrates how to catch a \p system_error to recover + * from an error. + * + * \code + * + * #include + * #include + * #include + * + * void terminate_gracefully(void) + * { + * // application-specific termination code here + * ... + * } + * + * int main(void) + * { + * try + * { + * thrust::device_vector vec; + * thrust::sort(vec.begin(), vec.end()); + * } + * catch(thrust::system_error e) + * { + * std::cerr << "Error inside sort: " << e.what() << std::endl; + * terminate_gracefully(); + * } + * + * return 0; + * } + * + * \endcode + * * \note If an error represents an out-of-memory condition, implementations are encouraged * to throw an exception object of type \p std::bad_alloc rather than \p system_error. */ @@ -54,22 +94,67 @@ class system_error public: // [19.5.5.2] Class system_error members + /*! Constructs an object of class \p system_error. + * \param ec The value returned by \p code(). + * \param what_arg A string to include in the result returned by \p what(). + * \post code() == ec. + * \post std::string(what()).find(what_arg) != string::npos. + */ inline system_error(error_code ec, const std::string &what_arg); + /*! Constructs an object of class \p system_error. + * \param ec The value returned by \p code(). + * \param what_arg A string to include in the result returned by \p what(). + * \post code() == ec. + * \post std::string(what()).find(what_arg) != string::npos. + */ inline system_error(error_code ec, const char *what_arg); + /*! Constructs an object of class \p system_error. + * \param ec The value returned by \p code(). + * \post code() == ec. + */ inline system_error(error_code ec); + /*! Constructs an object of class \p system_error. + * \param ev The error value used to create an \p error_code. + * \param ecat The \p error_category used to create an \p error_code. + * \param what_arg A string to include in the result returned by \p what(). + * \post code() == error_code(ev, ecat). + * \post std::string(what()).find(what_arg) != string::npos. + */ inline system_error(int ev, const error_category &ecat, const std::string &what_arg); + /*! Constructs an object of class \p system_error. + * \param ev The error value used to create an \p error_code. + * \param ecat The \p error_category used to create an \p error_code. + * \param what_arg A string to include in the result returned by \p what(). + * \post code() == error_code(ev, ecat). + * \post std::string(what()).find(what_arg) != string::npos. + */ inline system_error(int ev, const error_category &ecat, const char *what_arg); + /*! Constructs an object of class \p system_error. + * \param ev The error value used to create an \p error_code. + * \param ecat The \p error_category used to create an \p error_code. + * \post code() == error_code(ev, ecat). + */ inline system_error(int ev, const error_category &ecat); + /*! Destructor does not throw. + */ inline virtual ~system_error(void) throw () {}; + /*! Returns an object encoding the error. + * \return ec or error_code(ev, ecat), from the + * constructor, as appropriate. + */ inline const error_code &code(void) const throw(); + /*! Returns a human-readable string indicating the nature of the error. + * \return a string incorporating code().message() and the + * arguments supplied in the constructor. + */ inline const char *what(void) const throw(); /*! \cond @@ -84,6 +169,9 @@ class system_error } // end system +/*! \} // end system + */ + // import names into thrust:: using system::system_error; diff --git a/thrust/system_error.h b/thrust/system_error.h index bafe98160..5ddea67e6 100644 --- a/thrust/system_error.h +++ b/thrust/system_error.h @@ -21,6 +21,35 @@ #pragma once #include + +namespace thrust +{ + +namespace experimental +{ + +/*! \addtogroup system System Diagnostics + * \{ + */ + +/*! \namespace system + * \brief \p system is the namespace which contains classes reporting error + * conditions originating from the operating system or other low-level + * application program interfaces such as the CUDA runtime. + * They are provided in a separate namespace for import convenience but are + * also aliased in the top-level \p thrust namespace for easy access. + */ +namespace system +{ +} // end system + +/*! \} // end system + */ + +} // end experimental + +} // end thrust + #include #include #include