// (C) Copyright Gennadiy Rozental 2001. // (C) Copyright Beman Dawes 2001. // Distributed under the Boost Software License, Version 1.0. // (See accompanying file LICENSE_1_0.txt or copy at // http://www.boost.org/LICENSE_1_0.txt) // See http://www.boost.org/libs/test for the library home page. // //!@file //!@brief Defines public interface of the Execution Monitor and related classes // *************************************************************************** #ifndef BOOST_TEST_EXECUTION_MONITOR_HPP_071894GER #define BOOST_TEST_EXECUTION_MONITOR_HPP_071894GER // Boost.Test #include #include #include #include // Boost #include #include #include #include #include #include #ifdef BOOST_SEH_BASED_SIGNAL_HANDLING // for the FP constants and control routines #include #ifndef EM_INVALID #define EM_INVALID _EM_INVALID #endif #ifndef EM_DENORMAL #define EM_DENORMAL _EM_DENORMAL #endif #ifndef EM_ZERODIVIDE #define EM_ZERODIVIDE _EM_ZERODIVIDE #endif #ifndef EM_OVERFLOW #define EM_OVERFLOW _EM_OVERFLOW #endif #ifndef EM_UNDERFLOW #define EM_UNDERFLOW _EM_UNDERFLOW #endif #ifndef MCW_EM #define MCW_EM _MCW_EM #endif #else // based on ISO C standard #if !defined(BOOST_NO_FENV_H) #include #endif #endif #if defined(BOOST_SEH_BASED_SIGNAL_HANDLING) && !defined(UNDER_CE) //! Indicates tha the floating point exception handling is supported //! through SEH #define BOOST_TEST_FPE_SUPPORT_WITH_SEH__ #elif !defined(BOOST_SEH_BASED_SIGNAL_HANDLING) && !defined(UNDER_CE) #if !defined(BOOST_NO_FENV_H) && !defined(BOOST_CLANG) && \ defined(__GLIBC__) && defined(__USE_GNU) && \ !(defined(__UCLIBC__) || defined(__nios2__) || defined(__microblaze__)) //! Indicates that floating point exception handling is supported for the //! non SEH version of it, for the GLIBC extensions only // see dicussions on the related topic: https://svn.boost.org/trac/boost/ticket/11756 #define BOOST_TEST_FPE_SUPPORT_WITH_GLIBC_EXTENSIONS__ #endif #endif // Additional macro documentations not being generated without this hack #ifdef BOOST_TEST_DOXYGEN_DOC__ //! Disables the support of the alternative stack //! during the compilation of the Boost.test framework. This is especially useful //! in case it is not possible to detect the lack of alternative stack support for //! your compiler (for instance, ESXi). #define BOOST_TEST_DISABLE_ALT_STACK #endif //____________________________________________________________________________// namespace boost { /// @defgroup ExecutionMonitor Function Execution Monitor /// @{ /// @section Intro Introduction /// Sometimes we need to call a function and make sure that no user or system originated exceptions are being thrown by it. Uniform exception reporting /// is also may be convenient. That's the purpose of the Boost.Test's Execution Monitor. /// /// The Execution Monitor is a lower-level component of the Boost Test Library. It is the base for implementing all other Boost.Test components, but also /// can be used standalone to get controlled execution of error-prone functions with a uniform error notification. The Execution Monitor calls a user-supplied /// function in a controlled environment, relieving users from messy error detection. /// /// The Execution Monitor usage is demonstrated in the example exec_mon_example. /// /// @section DesignRationale Design Rationale /// /// The Execution Monitor design assumes that it can be used when no (or almost no) memory available. Also the Execution Monitor /// is intended to be portable to as many platforms as possible. /// /// @section UserGuide User's guide /// The Execution Monitor is designed to solve the problem of executing potentially dangerous function that may result in any number of error conditions, /// in monitored environment that should prevent any undesirable exceptions to propagate out of function call and produce consistent result report for all outcomes. /// The Execution Monitor is able to produce informative report for all standard C++ exceptions and intrinsic types. All other exceptions are reported as unknown. /// If you prefer different message for your exception type or need to perform any action, the Execution Monitor supports custom exception translators. /// There are several other parameters of the monitored environment can be configured by setting appropriate properties of the Execution Monitor. /// /// All symbols in the Execution Monitor implementation are located in the namespace boost. To use the Execution Monitor you need to: /// -# include @c boost/test/execution_monitor.hpp /// -# Make an instance of execution_monitor. /// -# Optionally register custom exception translators for exception classes which require special processing. /// /// @subsection FuncExec Monitored function execution /// /// The class execution_monitor can monitor functions with the following signatures: /// - int () /// - void () /// /// This function is expected to be self sufficient part of your application. You can't pass any arguments to this function directly. Instead you /// should bind them into executable nullary function using bind function (either standard or boost variant). Neither you can return any other value, /// but an integer result code. If necessary you can bind output parameters by reference or use some other more complicated nullary functor, which /// maintains state. This includes class methods, static class methods etc. /// /// To start the monitored function, invoke the method execution_monitor::execute and pass the monitored function as an argument. If the call succeeds, /// the method returns the result code produced by the monitored function. If any of the following conditions occur: /// - Uncaught C++ exception /// - Hardware or software signal, trap, or other exception /// - Timeout reached /// - Debug assert event occurred (under Microsoft Visual C++ or compatible compiler) /// /// then the method throws the execution_exception. The exception contains unique error_code value identifying the error condition and the detailed message /// that can be used to report the error. /// /// @subsection Reporting Errors reporting and translation /// /// If you need to report an error inside monitored function execution you have to throw an exception. Do not use the execution_exception - it's not intended /// to be used for this purpose. The simplest choice is to use one of the following C++ types as an exception: /// - C string /// - std:string /// - any exception class in std::exception hierarchy /// - boost::exception /// /// execution_monitor will catch and report these types of exceptions. If exception is thrown which is unknown to execution_monitor, it can only /// report the fact of the exception. So in case if you prefer to use your own exception types or can't govern what exceptions are generated by monitored /// function and would like to see proper error message in a report, execution_monitor can be configured with custom "translator" routine, which will have /// a chance to either record the fact of the exception itself or translate it into one of standard exceptions and rethrow (or both). The translator routine /// is registered per exception type and is invoked when exception of this class (or one inherited from it) is thrown inside monitored routine. You can /// register as many independent translators as you like. See execution_monitor::register_exception_translator specification for requirements on translator /// function. /// /// Finally, if you need to abort the monitored function execution without reporting any errors, you can throw an exception execution_aborted. As a result /// the execution is aborted and zero result code is produced by the method execution_monitor::execute. /// /// @subsection Parameters Supported parameters /// /// The Execution Monitor behavior is configurable through the set of parameters (properties) associated with the instance of the monitor. See execution_monitor /// specification for a list of supported parameters and their semantic. // ************************************************************************** // // ************** detail::translator_holder_base ************** // // ************************************************************************** // namespace detail { class translator_holder_base; typedef boost::shared_ptr translator_holder_base_ptr; class BOOST_TEST_DECL translator_holder_base { protected: typedef boost::unit_test::const_string const_string; public: // Constructor translator_holder_base( translator_holder_base_ptr next, const_string tag ) : m_next( next ) , m_tag( std::string() + tag ) { } // Destructor virtual ~translator_holder_base() {} // translator holder interface // invokes the function F inside the try/catch guarding against specific exception virtual int operator()( boost::function const& F ) = 0; // erases specific translator holder from the chain translator_holder_base_ptr erase( translator_holder_base_ptr this_, const_string tag ) { if( m_next ) m_next = m_next->erase( m_next, tag ); return m_tag == tag ? m_next : this_; } #ifndef BOOST_NO_RTTI virtual translator_holder_base_ptr erase( translator_holder_base_ptr this_, std::type_info const& ) = 0; template translator_holder_base_ptr erase( translator_holder_base_ptr this_, boost::type* = 0 ) { if( m_next ) m_next = m_next->erase( m_next ); return erase( this_, typeid(ExceptionType) ); } #endif protected: // Data members translator_holder_base_ptr m_next; std::string m_tag; }; } // namespace detail // ************************************************************************** // /// @class execution_exception /// @brief This class is used to report any kind of an failure during execution of a monitored function inside of execution_monitor /// /// The instance of this class is thrown out of execution_monitor::execute invocation when failure is detected. Regardless of a kind of failure occurred /// the instance will provide a uniform way to catch and report it. /// /// One important design rationale for this class is that we should be ready to work after fatal memory corruptions or out of memory conditions. To facilitate /// this class never allocates any memory and assumes that strings it refers to are either some constants or live in a some kind of persistent (preallocated) memory. // ************************************************************************** // class BOOST_SYMBOL_VISIBLE execution_exception { typedef boost::unit_test::const_string const_string; public: /// These values are sometimes used as program return codes. /// The particular values have been chosen to avoid conflicts with /// commonly used program return codes: values < 100 are often user /// assigned, values > 255 are sometimes used to report system errors. /// Gaps in values allow for orderly expansion. /// /// @note(1) Only uncaught C++ exceptions are treated as errors. /// If a function catches a C++ exception, it never reaches /// the execution_monitor. /// /// The implementation decides what is a system_fatal_error and what is /// just a system_exception. Fatal errors are so likely to have corrupted /// machine state (like a stack overflow or addressing exception) that it /// is unreasonable to continue execution. /// /// @note(2) These errors include Unix signals and Windows structured /// exceptions. They are often initiated by hardware traps. enum error_code { no_error = 0, ///< for completeness only; never returned user_error = 200, ///< user reported non-fatal error cpp_exception_error = 205, ///< see note (1) above system_error = 210, ///< see note (2) above timeout_error = 215, ///< only detectable on certain platforms user_fatal_error = 220, ///< user reported fatal error system_fatal_error = 225 ///< see note (2) above }; /// Simple model for the location of failure in a source code struct BOOST_TEST_DECL location { explicit location( char const* file_name = 0, size_t line_num = 0, char const* func = 0 ); explicit location( const_string file_name, size_t line_num = 0, char const* func = 0 ); const_string m_file_name; ///< File name size_t m_line_num; ///< Line number const_string m_function; ///< Function name }; /// @name Constructors /// Constructs instance based on message, location and error code /// @param[in] ec error code /// @param[in] what_msg error message /// @param[in] location error location execution_exception( error_code ec, const_string what_msg, location const& location ); /// @name Access methods /// Exception error code error_code code() const { return m_error_code; } /// Exception message const_string what() const { return m_what; } /// Exception location location const& where() const { return m_location; } ///@} private: // Data members error_code m_error_code; const_string m_what; location m_location; }; // execution_exception // ************************************************************************** // /// @brief Function execution monitor /// This class is used to uniformly detect and report an occurrence of several types of signals and exceptions, reducing various /// errors to a uniform execution_exception that is returned to a caller. /// /// The executiom_monitor behavior can be customized through a set of public parameters (properties) associated with the execution_monitor instance. /// All parameters are implemented as public unit_test::readwrite_property data members of the class execution_monitor. // ************************************************************************** // class BOOST_TEST_DECL execution_monitor { typedef boost::unit_test::const_string const_string; public: /// Default constructor initializes all execution monitor properties execution_monitor(); /// Should monitor catch system errors. /// /// The @em p_catch_system_errors property is a boolean flag (default value is true) specifying whether or not execution_monitor should trap system /// errors/system level exceptions/signals, which would cause program to crash in a regular case (without execution_monitor). /// Set this property to false, for example, if you wish to force coredump file creation. The Unit Test Framework provides a /// runtime parameter @c \-\-catch_system_errors=yes to alter the behavior in monitored test cases. unit_test::readwrite_property p_catch_system_errors; /// Should monitor try to attach debugger in case of caught system error. /// /// The @em p_auto_start_dbg property is a boolean flag (default value is false) specifying whether or not execution_monitor should try to attach debugger /// in case system error is caught. unit_test::readwrite_property p_auto_start_dbg; /// Specifies the seconds that elapse before a timer_error occurs. /// /// The @em p_timeout property is an integer timeout (in microseconds) for monitored function execution. Use this parameter to monitor code with possible deadlocks /// or infinite loops. This feature is only available for some operating systems (not yet Microsoft Windows). unit_test::readwrite_property p_timeout; /// Should monitor use alternative stack for the signal catching. /// /// The @em p_use_alt_stack property is a boolean flag (default value is false) specifying whether or not execution_monitor should use an alternative stack /// for the sigaction based signal catching. When enabled the signals are delivered to the execution_monitor on a stack different from current execution /// stack, which is safer in case if it is corrupted by monitored function. For more details on alternative stack handling see appropriate manuals. unit_test::readwrite_property p_use_alt_stack; /// Should monitor try to detect hardware floating point exceptions (!= 0), and which specific exception to catch. /// /// The @em p_detect_fp_exceptions property is a boolean flag (default value is false) specifying whether or not execution_monitor should install hardware /// traps for the floating point exception on platforms where it's supported. unit_test::readwrite_property p_detect_fp_exceptions; // @name Monitoring entry points /// @brief Execution monitor entry point for functions returning integer value /// /// This method executes supplied function F inside a try/catch block and also may include other unspecified platform dependent error detection code. /// /// This method throws an execution_exception on an uncaught C++ exception, a hardware or software signal, trap, or other user exception. /// /// @note execute() doesn't consider it an error for F to return a non-zero value. /// @param[in] F Function to monitor /// @returns value returned by function call F(). /// @see vexecute int execute( boost::function const& F ); /// @brief Execution monitor entry point for functions returning void /// /// This method is semantically identical to execution_monitor::execute, but des't produce any result code. /// @param[in] F Function to monitor /// @see execute void vexecute( boost::function const& F ); // @} // @name Exception translator registration /// @brief Registers custom (user supplied) exception translator /// This method template registers a translator for an exception type specified as a first template argument. For example /// @code /// void myExceptTr( MyException const& ex ) { /*do something with the exception here*/} /// em.register_exception_translator( myExceptTr ); /// @endcode /// The translator should be any unary function/functor object which accepts MyException const&. This can be free standing function /// or bound class method. The second argument is an optional string tag you can associate with this translator routine. The only reason /// to specify the tag is if you plan to erase the translator eventually. This can be useful in scenario when you reuse the same /// execution_monitor instance to monitor different routines and need to register a translator specific to the routine being monitored. /// While it is possible to erase the translator based on an exception type it was registered for, tag string provides simpler way of doing this. /// @tparam ExceptionType type of the exception we register a translator for /// @tparam ExceptionTranslator type of the translator we register for this exception /// @param[in] tr translator function object with the signature void (ExceptionType const&) /// @param[in] tag tag associated with this translator template void register_exception_translator( ExceptionTranslator const& tr, const_string tag = const_string(), boost::type* = 0 ); /// @brief Erases custom exception translator based on a tag /// Use the same tag as the one used during translator registration /// @param[in] tag tag associated with translator you wants to erase void erase_exception_translator( const_string tag ) { m_custom_translators = m_custom_translators->erase( m_custom_translators, tag ); } #ifndef BOOST_NO_RTTI /// @brief Erases custom exception translator based on an exception type /// /// tparam ExceptionType Exception type for which you want to erase the translator template void erase_exception_translator( boost::type* = 0 ) { m_custom_translators = m_custom_translators->erase( m_custom_translators ); } //@} #endif private: // implementation helpers int catch_signals( boost::function const& F ); // Data members detail::translator_holder_base_ptr m_custom_translators; boost::scoped_array m_alt_stack; }; // execution_monitor // ************************************************************************** // // ************** detail::translator_holder ************** // // ************************************************************************** // namespace detail { template class translator_holder : public translator_holder_base { public: explicit translator_holder( ExceptionTranslator const& tr, translator_holder_base_ptr& next, const_string tag = const_string() ) : translator_holder_base( next, tag ), m_translator( tr ) {} // translator holder interface virtual int operator()( boost::function const& F ) { BOOST_TEST_I_TRY { return m_next ? (*m_next)( F ) : F(); } BOOST_TEST_I_CATCH( ExceptionType, e ) { m_translator( e ); return boost::exit_exception_failure; } } #ifndef BOOST_NO_RTTI virtual translator_holder_base_ptr erase( translator_holder_base_ptr this_, std::type_info const& ti ) { return ti == typeid(ExceptionType) ? m_next : this_; } #endif private: // Data members ExceptionTranslator m_translator; }; } // namespace detail template void execution_monitor::register_exception_translator( ExceptionTranslator const& tr, const_string tag, boost::type* ) { m_custom_translators.reset( new detail::translator_holder( tr, m_custom_translators, tag ) ); } // ************************************************************************** // /// @class execution_aborted /// @brief This is a trivial default constructible class. Use it to report graceful abortion of a monitored function execution. // ************************************************************************** // struct execution_aborted {}; // ************************************************************************** // // ************** system_error ************** // // ************************************************************************** // class system_error { public: // Constructor explicit system_error( char const* exp ); long const p_errno; char const* const p_failed_exp; }; //!@internal #define BOOST_TEST_SYS_ASSERT( cond ) BOOST_TEST_I_ASSRT( cond, ::boost::system_error( BOOST_STRINGIZE( exp ) ) ) // ************************************************************************** // // **************Floating point exception management interface ************** // // ************************************************************************** // namespace fpe { enum masks { BOOST_FPE_OFF = 0, #if defined(BOOST_TEST_FPE_SUPPORT_WITH_SEH__) /* *** */ BOOST_FPE_DIVBYZERO = EM_ZERODIVIDE, BOOST_FPE_INEXACT = EM_INEXACT, BOOST_FPE_INVALID = EM_INVALID, BOOST_FPE_OVERFLOW = EM_OVERFLOW, BOOST_FPE_UNDERFLOW = EM_UNDERFLOW|EM_DENORMAL, BOOST_FPE_ALL = MCW_EM, #elif !defined(BOOST_TEST_FPE_SUPPORT_WITH_GLIBC_EXTENSIONS__)/* *** */ BOOST_FPE_DIVBYZERO = BOOST_FPE_OFF, BOOST_FPE_INEXACT = BOOST_FPE_OFF, BOOST_FPE_INVALID = BOOST_FPE_OFF, BOOST_FPE_OVERFLOW = BOOST_FPE_OFF, BOOST_FPE_UNDERFLOW = BOOST_FPE_OFF, BOOST_FPE_ALL = BOOST_FPE_OFF, #else /* *** */ #if defined(FE_DIVBYZERO) BOOST_FPE_DIVBYZERO = FE_DIVBYZERO, #else BOOST_FPE_DIVBYZERO = BOOST_FPE_OFF, #endif #if defined(FE_INEXACT) BOOST_FPE_INEXACT = FE_INEXACT, #else BOOST_FPE_INEXACT = BOOST_FPE_OFF, #endif #if defined(FE_INVALID) BOOST_FPE_INVALID = FE_INVALID, #else BOOST_FPE_INVALID = BOOST_FPE_OFF, #endif #if defined(FE_OVERFLOW) BOOST_FPE_OVERFLOW = FE_OVERFLOW, #else BOOST_FPE_OVERFLOW = BOOST_FPE_OFF, #endif #if defined(FE_UNDERFLOW) BOOST_FPE_UNDERFLOW = FE_UNDERFLOW, #else BOOST_FPE_UNDERFLOW = BOOST_FPE_OFF, #endif #if defined(FE_ALL_EXCEPT) BOOST_FPE_ALL = FE_ALL_EXCEPT, #else BOOST_FPE_ALL = BOOST_FPE_OFF, #endif #endif /* *** */ BOOST_FPE_INV = BOOST_FPE_ALL+1 }; //____________________________________________________________________________// // return the previous set of enabled exceptions when successful, and BOOST_FPE_INV otherwise unsigned BOOST_TEST_DECL enable( unsigned mask ); unsigned BOOST_TEST_DECL disable( unsigned mask ); //____________________________________________________________________________// } // namespace fpe ///@} } // namespace boost #include #endif