diff options
Diffstat (limited to 'libstdc++-v3/libsupc++')
| -rw-r--r-- | libstdc++-v3/libsupc++/exception | 33 | ||||
| -rw-r--r-- | libstdc++-v3/libsupc++/new | 24 | ||||
| -rw-r--r-- | libstdc++-v3/libsupc++/typeinfo | 24 |
3 files changed, 75 insertions, 6 deletions
diff --git a/libstdc++-v3/libsupc++/exception b/libstdc++-v3/libsupc++/exception index 3676a731481..a1daf8811cc 100644 --- a/libstdc++-v3/libsupc++/exception +++ b/libstdc++-v3/libsupc++/exception @@ -28,6 +28,11 @@ // invalidate any other reasons why the executable file might be covered by // the GNU General Public License. +/** @file exception + * This header defines several types and functions relating to the + * handling of exceptions in a C++ program. + */ + #ifndef __EXCEPTION__ #define __EXCEPTION__ @@ -35,14 +40,24 @@ extern "C++" { namespace std { + /** This is the base class for all exceptions thrown by the standard + * library, and by certain language expressions. You are free to derive + * your own %exception classes, or use a different hierarchy, or to + * throw non-class data (e.g., fundamental types). + * @brief Base class for all library exceptions. + */ class exception { public: exception() throw() { } virtual ~exception() throw(); + /** Returns a C-style character string describing the general cause + * of the current error. */ virtual const char* what() const throw(); }; + /** If an %exception is thrown which is not listed in a function's + * %exception specification, one of these may be thrown. */ class bad_exception : public exception { public: @@ -50,15 +65,33 @@ namespace std virtual ~bad_exception() throw(); }; + /// If you write a replacement %terminate handler, it must be of this type. typedef void (*terminate_handler) (); + /// If you write a replacement %unexpected handler, it must be of this type. typedef void (*unexpected_handler) (); + /// Takes a new handler function as an argument, returns the old function. terminate_handler set_terminate(terminate_handler) throw(); + /** The runtime will call this function if %exception handling must be + * abandoned for any reason. */ void terminate() __attribute__ ((__noreturn__)); + /// Takes a new handler function as an argument, returns the old function. unexpected_handler set_unexpected(unexpected_handler) throw(); + /** The runtime will call this function if an %exception is thrown which + * violates the function's %exception specification. */ void unexpected() __attribute__ ((__noreturn__)); + /** [18.6.4]/1: "Returns true after completing evaluation of a + * throw-expression until either completing initialization of the + * exception-declaration in the matching handler or entering @c unexpected() + * due to the throw; or after entering @c terminate() for any reason + * other than an explicit call to @c terminate(). [Note: This includes + * stack unwinding [15.2]. end note]" + * + * 2: "When @c uncaught_exception() is true, throwing an %exception can + * result in a call of @c terminate() (15.5.1)." + */ bool uncaught_exception() throw(); } // namespace std diff --git a/libstdc++-v3/libsupc++/new b/libstdc++-v3/libsupc++/new index 56cc1833fe8..0d1810c6207 100644 --- a/libstdc++-v3/libsupc++/new +++ b/libstdc++-v3/libsupc++/new @@ -28,6 +28,12 @@ // invalidate any other reasons why the executable file might be covered by // the GNU General Public License. +/** @file new + * This header defines several functions to manage dynamic memory and + * handling memory allocation errors; see + * http://gcc.gnu.org/onlinedocs/libstdc++/18_support/howto.html#4 for more. + */ + #ifndef __NEW__ #define __NEW__ @@ -38,6 +44,8 @@ extern "C++" { namespace std { + /** @c bad_alloc (or classes derived from it) is used to report allocation + * errors from the throwing forms of @c new. */ class bad_alloc : public exception { public: @@ -47,11 +55,24 @@ namespace std struct nothrow_t { }; extern const nothrow_t nothrow; + /** If you write your own error handler to be called by @c new, it must + * be of this type. */ typedef void (*new_handler)(); + /// Takes a replacement handler as the argument, returns the previous handler. new_handler set_new_handler(new_handler); } // namespace std -// Replaceable signatures. +//@{ +/** These are replaceable signatures: + * - normal single new and delete (no arguments, throw @c bad_alloc on error) + * - normal array new and delete (same) + * - @c nothrow single new and delete (take a @c nothrow argument, return + * @c NULL on error) + * - @c nothrow array new and delete (same) + * + * Placement new and delete signatures (take a memory address argument, + * does nothing) may not be replaced by a user's program. +*/ void *operator new(std::size_t) throw (std::bad_alloc); void *operator new[](std::size_t) throw (std::bad_alloc); void operator delete(void *) throw(); @@ -64,6 +85,7 @@ void operator delete[](void *, const std::nothrow_t&) throw(); // Default placement versions of operator new. inline void *operator new(std::size_t, void *place) throw() { return place; } inline void *operator new[](std::size_t, void *place) throw() { return place; } +//@} } // extern "C++" #endif diff --git a/libstdc++-v3/libsupc++/typeinfo b/libstdc++-v3/libsupc++/typeinfo index 8d8133b6a5c..6cabf7508eb 100644 --- a/libstdc++-v3/libsupc++/typeinfo +++ b/libstdc++-v3/libsupc++/typeinfo @@ -27,6 +27,10 @@ // invalidate any other reasons why the executable file might be covered by // the GNU General Public License. +/** @file typeinfo + * This header provides RTTI support. + */ + #ifndef __TYPEINFO__ #define __TYPEINFO__ @@ -49,17 +53,20 @@ namespace __cxxabiv1 namespace std { + /** The @c type_info class describes type information generated by + * an implementation. + * @brief Used in RTTI. */ class type_info { public: - // Destructor. Being the first non-inline virtual function, this - // controls in which translation unit the vtable is emitted. The - // compiler makes use of that information to know where to emit - // the runtime-mandated type_info structures in the new-abi. + /** Destructor. Being the first non-inline virtual function, this + * controls in which translation unit the vtable is emitted. The + * compiler makes use of that information to know where to emit + * the runtime-mandated type_info structures in the new-abi. */ virtual ~type_info(); private: - // Assigning type_info is not supported. made private. + /// Assigning type_info is not supported. Made private. type_info& operator=(const type_info&); type_info(const type_info&); @@ -71,6 +78,8 @@ namespace std public: // the public interface + /** Returns an \e implementation-defined byte string; this is not + * portable between compilers! */ const char* name() const { return __name; } @@ -81,6 +90,8 @@ namespace std // type. Uniqueness must use the _name value, not object address. bool operator==(const type_info& __arg) const; #else + /** Returns true if @c *this preceeds @c __arg in the implementation's + * collation order. */ // In new abi we can rely on type_info's NTBS being unique, // and therefore address comparisons are sufficient. bool before(const type_info& __arg) const @@ -112,6 +123,8 @@ namespace std void **__obj_ptr) const; }; + /** If you attempt an invalid @c dynamic_cast expression, an instance of + * this class (or something derived from this class) is thrown. */ class bad_cast : public exception { public: @@ -119,6 +132,7 @@ namespace std virtual ~bad_cast() throw(); }; + /** If you use a NULL pointer in a @c typeid expression, this is thrown. */ class bad_typeid : public exception { public: |
