From 01b3b9e39fd837974c20ea2a8d50bde1ff50960f Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Thu, 30 May 2019 16:47:32 +0100 Subject: [PATCH] Update libstdc++ documentation for Support and Diagnostics clauses * doc/xml/manual/diagnostics.xml: Update list of headers that define exception classes. * doc/xml/manual/support.xml: Rewrite advice around NULL. Rewrite section about new/delete overloads. Improve section on verbose terminate handler. * doc/html/*: Regenerate. From-SVN: r271782 --- libstdc++-v3/ChangeLog | 7 + libstdc++-v3/doc/html/index.html | 2 +- libstdc++-v3/doc/html/manual/diagnostics.html | 32 +- .../doc/html/manual/dynamic_memory.html | 159 +++++++--- libstdc++-v3/doc/html/manual/index.html | 2 +- .../doc/html/manual/std_contents.html | 2 +- libstdc++-v3/doc/html/manual/support.html | 40 ++- libstdc++-v3/doc/html/manual/termination.html | 41 ++- libstdc++-v3/doc/xml/manual/diagnostics.xml | 34 +- libstdc++-v3/doc/xml/manual/support.xml | 299 +++++++++++++----- 10 files changed, 440 insertions(+), 178 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 8b7b70e7cd8..15a388c62d3 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,5 +1,12 @@ 2019-05-30 Jonathan Wakely + * doc/xml/manual/diagnostics.xml: Update list of headers that define + exception classes. + * doc/xml/manual/support.xml: Rewrite advice around NULL. Rewrite + section about new/delete overloads. Improve section on verbose + terminate handler. + * doc/html/*: Regenerate. + * doc/xml/manual/status_cxx2020.xml: Add feature-test macro for P0811R3. Change status of P1353R0. * doc/html/*: Regenerate. diff --git a/libstdc++-v3/doc/html/index.html b/libstdc++-v3/doc/html/index.html index 2b7f36070f8..6302b323bee 100644 --- a/libstdc++-v3/doc/html/index.html +++ b/libstdc++-v3/doc/html/index.html @@ -28,7 +28,7 @@
4. Support -
Types
Fundamental Types
Numeric Properties
NULL
Dynamic Memory
Termination
Termination Handlers
Verbose Terminate Handler
5. +
Types
Fundamental Types
Numeric Properties
NULL
Dynamic Memory
Additional Notes
Termination
Termination Handlers
Verbose Terminate Handler
5. Diagnostics
Exceptions
API Reference
Adding Data to exception
Use of errno by the library
Concept Checking
6. diff --git a/libstdc++-v3/doc/html/manual/diagnostics.html b/libstdc++-v3/doc/html/manual/diagnostics.html index 67d1c13b4ad..23eb1a8189a 100644 --- a/libstdc++-v3/doc/html/manual/diagnostics.html +++ b/libstdc++-v3/doc/html/manual/diagnostics.html @@ -8,20 +8,32 @@ Diagnostics

Table of Contents

Exceptions
API Reference
Adding Data to exception
Use of errno by the library
Concept Checking

Exceptions

API Reference

- All exception objects are defined in one of the standard header - files: exception, - stdexcept, new, and - typeinfo. + Most exception classes are defined in one of the standard headers + <exception>, + <stdexcept>, + <new>, and + <typeinfo>. + The C++ 2011 revision of the standard added more exception types + in the headers + <functional>, + <future>, + <regex>, and + <system_error>. + The C++ 2017 revision of the standard added more exception types + in the headers + <any>, + <filesystem>, + <optional>, and + <variant>.

- The base exception object is exception, - located in exception. This object has no - string member. + All exceptions thrown by the library have a base class of type + std::exception, + defined in <exception>. + This type has no std::string member.

Derived from this are several classes that may have a - string member: a full hierarchy can be + std::string member. A full hierarchy can be found in the source documentation. -

- Full API details.

Adding Data to exception

The standard exception classes carry with them a single string as data (usually describing what went wrong or where the 'throw' took diff --git a/libstdc++-v3/doc/html/manual/dynamic_memory.html b/libstdc++-v3/doc/html/manual/dynamic_memory.html index 57599117cb8..9b7a1fc0644 100644 --- a/libstdc++-v3/doc/html/manual/dynamic_memory.html +++ b/libstdc++-v3/doc/html/manual/dynamic_memory.html @@ -3,45 +3,120 @@ Support  Next

Dynamic Memory

- There are six flavors each of new and - delete, so make certain that you're using the right - ones. Here are quickie descriptions of new: -

  • - single object form, throwing a - bad_alloc on errors; this is what most - people are used to using -

  • - Single object "nothrow" form, returning NULL on errors -

  • - Array new, throwing - bad_alloc on errors -

  • - Array nothrow new, returning - NULL on errors -

  • - Placement new, which does nothing (like - it's supposed to) -

  • - Placement array new, which also does - nothing -

- They are distinguished by the parameters that you pass to them, like - any other overloaded function. The six flavors of delete + In C++98 there are six flavors each of operator new + and operator delete, so make certain that you're + using the right ones. + Here are quickie descriptions of operator new: +

void* operator new(std::size_t);
+ Single object form. + Throws std::bad_alloc on error. + This is what most people are used to using. +
void* operator new(std::size_t, std::nothrow_t) noexcept;
+ Single object “nothrow” form. + Calls operator new(std::size_t) but if that throws, + returns a null pointer instead. +
void* operator new[](std::size_t);
+ Array new. + Calls operator new(std::size_t) and so + throws std::bad_alloc on error. +
void* operator new[](std::size_t, std::nothrow_t) noexcept;
+ Array “nothrow”new. + Calls operator new[](std::size_t) but if that throws, + returns a null pointer instead. +
void* operator new(std::size_t, void*) noexcept;
+ Non-allocating, “placement” single-object new, + which does nothing except return its argument. + This function cannot be replaced. +
void* operator new[](std::size_t, void*) noexcept;
+ Non-allocating, “placement” array new, + which also does nothing except return its argument. + This function cannot be replaced. +

+ They are distinguished by the arguments that you pass to them, like + any other overloaded function. The six flavors of + operator delete are distinguished the same way, but none of them are allowed to throw - an exception under any circumstances anyhow. (They match up for - completeness' sake.) + an exception under any circumstances anyhow. (The overloads match up + with the ones above, for completeness' sake.)

- Remember that it is perfectly okay to call delete on a - NULL pointer! Nothing happens, by definition. That is not the - same thing as deleting a pointer twice. + The C++ 2014 revision of the standard added two additional overloads of + operator delete for “sized deallocation”, + allowing the compiler to provide the size of the storage being freed. +

+ The C++ 2017 standard added even more overloads of both + operator new and operator delete + for allocating and deallocating storage for overaligned types. + These overloads correspond to each of the allocating forms of + operator new and operator delete + but with an additional parameter of type std::align_val_t. + These new overloads are not interchangeable with the versions without + an aligment parameter, so if memory was allocated by an overload of + operator new taking an alignment parameter, + then it must be decallocated by the corresponding overload of + operator delete that takes an alignment parameter. +

+ Apart from the non-allocating forms, the default versions of the array + and nothrow operator new functions will all result + in a call to either operator new(std::size_t) or + operator new(std::size_t, std::align_val_t), + and similarly the default versions of the array and nothrow + operator delete functions will result in a call to + either operator delete(void*) or + operator delete(void*, std::align_val_t) + (or the sized versions of those).

- By default, if one of the “throwing news” can't - allocate the memory requested, it tosses an instance of a - bad_alloc exception (or, technically, some class derived - from it). You can change this by writing your own function (called a - new-handler) and then registering it with set_new_handler(): + Apart from the non-allocating forms, any of these functions can be + replaced by defining a function with the same signature in your program. + Replacement versions must preserve certain guarantees, such as memory + obtained from a nothrow operator new being free-able + by the normal (non-nothrow) operator delete, + and the sized and unsized forms of operator delete + being interchangeable (because it's unspecified whether + the compiler calls the sized delete instead of the normal one). + The simplest way to meet the guarantees is to only replace the ordinary + operator new(size_t) and + operator delete(void*) and + operator delete(void*, std::size_t) + functions, and the replaced versions will be used by all of + operator new(size_t, nothrow_t), + operator new[](size_t) and + operator new[](size_t, nothrow_t) + and the corresponding operator delete functions. + To support types with extended alignment you may also need to replace + operator new(size_t, align_val_t) and + operator delete(void*, align_val_t) + operator delete(void*, size_t, align_val_t) + (which will then be used by the nothrow and array forms for + extended alignments). + If you do need to replace other forms (e.g. to define the nothrow + operator new to allocate memory directly, so it + works with exceptions disabled) then make sure the memory it allocates + can still be freed by the non-nothrow forms of + operator delete. +

+ If the default versions of operator new(std::size_t) + and operator new(size_t, std::align_val_t) + can't allocate the memory requested, they usually throw an exception + object of type std::bad_alloc (or some class + derived from that). However, the program can influence that behavior + by registering a “new-handler”, because what + operator new actually does is something like: 

-   typedef void (*PFV)(void);
+    while (true)
+    {
+      if (void* p = /* try to allocate memory */)
+        return p;
+      else if (std::new_handler h = std::get_new_handler ())
+        h ();
+      else
+        throw bad_alloc{};
+    }
+

+ This means you can influence what happens on allocation failure by + writing your own new-handler and then registering it with + std::set_new_handler: + 

+   typedef void (*PFV)();
 
    static char*  safety;
    static PFV    old_handler;
@@ -49,6 +124,7 @@
    void my_new_handler ()
    {
        delete[] safety;
+       safety = nullptr;
        popup_window ("Dude, you are running low on heap memory.  You"
 		     " should, like, close some windows, or something."
 		     " The next time you run out, we're gonna burn!");
@@ -62,10 +138,15 @@
        old_handler = set_new_handler (&my_new_handler);
        ...
    }
-

- bad_alloc is derived from the base exception - class defined in Sect1 19. -

Prev Up Next
Chapter 4.  +

Additional Notes

+ Remember that it is perfectly okay to delete a + null pointer! Nothing happens, by definition. That is not the + same thing as deleting a pointer twice. +

+ std::bad_alloc is derived from the base + std::exception class, + see Exceptions. +

Prev Up Next
Chapter 4.  Support  Home Termination
\ No newline at end of file diff --git a/libstdc++-v3/doc/html/manual/index.html b/libstdc++-v3/doc/html/manual/index.html index 69b56420978..3f2a48291f9 100644 --- a/libstdc++-v3/doc/html/manual/index.html +++ b/libstdc++-v3/doc/html/manual/index.html @@ -9,7 +9,7 @@
4. Support -
Types
Fundamental Types
Numeric Properties
NULL
Dynamic Memory
Termination
Termination Handlers
Verbose Terminate Handler
5. +
Types
Fundamental Types
Numeric Properties
NULL
Dynamic Memory
Additional Notes
Termination
Termination Handlers
Verbose Terminate Handler
5. Diagnostics
Exceptions
API Reference
Adding Data to exception
Use of errno by the library
Concept Checking
6. diff --git a/libstdc++-v3/doc/html/manual/std_contents.html b/libstdc++-v3/doc/html/manual/std_contents.html index cfb5db68a22..14586e8c75b 100644 --- a/libstdc++-v3/doc/html/manual/std_contents.html +++ b/libstdc++-v3/doc/html/manual/std_contents.html @@ -6,7 +6,7 @@

Table of Contents

4. Support -
Types
Fundamental Types
Numeric Properties
NULL
Dynamic Memory
Termination
Termination Handlers
Verbose Terminate Handler
5. +
Types
Fundamental Types
Numeric Properties
NULL
Dynamic Memory
Additional Notes
Termination
Termination Handlers
Verbose Terminate Handler
5. Diagnostics
Exceptions
API Reference
Adding Data to exception
Use of errno by the library
Concept Checking
6. diff --git a/libstdc++-v3/doc/html/manual/support.html b/libstdc++-v3/doc/html/manual/support.html index 689b35c2b83..c7c1cfedcc9 100644 --- a/libstdc++-v3/doc/html/manual/support.html +++ b/libstdc++-v3/doc/html/manual/support.html @@ -7,7 +7,7 @@
 Next

Chapter 4.  Support -

Table of Contents

Types
Fundamental Types
Numeric Properties
NULL
Dynamic Memory
Termination
Termination Handlers
Verbose Terminate Handler

+

Table of Contents

Types
Fundamental Types
Numeric Properties
NULL
Dynamic Memory
Additional Notes
Termination
Termination Handlers
Verbose Terminate Handler

This part deals with the functions called and objects created automatically during the course of a program's existence.

@@ -53,7 +53,7 @@ Specializing parts of the library on these types is prohibited: instead, use a POD.

Numeric Properties

- The header limits defines + The header <limits> defines traits classes to give access to various implementation defined-aspects of the fundamental types. The traits classes -- fourteen in total -- are all specializations of the class template @@ -102,28 +102,36 @@ The only change that might affect people is the type of NULL: while it is required to be a macro, the definition of that macro is not allowed - to be (void*)0, which is often used in C. + to be an expression with pointer type such as + (void*)0, which is often used in C.

For g++, NULL is #define'd to be __null, a magic keyword extension of - g++. + g++ that is slightly safer than a plain integer.

The biggest problem of #defining NULL to be something like “0L” is that the compiler will view that as a long integer before it views it as a pointer, so - overloading won't do what you expect. (This is why - g++ has a magic extension, so that - NULL is always a pointer.) -

In his book Effective - C++, Scott Meyers points out that the best way - to solve this problem is to not overload on pointer-vs-integer - types to begin with. He also offers a way to make your own magic - NULL that will match pointers before it - matches integers. -

See the - Effective - C++ CD example. + overloading won't do what you expect. It might not even have the + same size as a pointer, so passing NULL to a + varargs function where a pointer is expected might not even work + correctly if sizeof(NULL) < sizeof(void*). + The G++ __null extension is defined so that + sizeof(__null) == sizeof(void*) to avoid this problem. +

+ Scott Meyers explains this in more detail in his book + Effective + Modern C++ and as a guideline to solve this problem + recommends to not overload on pointer-vs-integer types to begin with. +

+ The C++ 2011 standard added the nullptr keyword, + which is a null pointer constant of a special type, + std::nullptr_t. Values of this type can be + implicitly converted to any pointer type, + and cannot convert to integer types or be deduced as an integer type. + Unless you need to be compatible with C++98/C++03 or C you should prefer + to use nullptr instead of NULL.

Prev Up Next
Part II.  Standard Contents  Home Dynamic Memory
\ No newline at end of file diff --git a/libstdc++-v3/doc/html/manual/termination.html b/libstdc++-v3/doc/html/manual/termination.html index 3e0d455f1c7..d30f0e0eaea 100644 --- a/libstdc++-v3/doc/html/manual/termination.html +++ b/libstdc++-v3/doc/html/manual/termination.html @@ -3,7 +3,9 @@ Support  Next

Termination

Termination Handlers

- Not many changes here to cstdlib. You should note that the + Not many changes here to + <cstdlib>. + You should note that the abort() function does not call the destructors of automatic nor static objects, so if you're depending on those to do cleanup, it isn't going to happen. @@ -24,8 +26,8 @@ The previous two actions are “interleaved,” that is, given this pseudocode: 

-  extern "C or C++" void  f1 (void);
-  extern "C or C++" void  f2 (void);
+  extern "C or C++" void f1 ();
+  extern "C or C++" void f2 ();
 
   static Thing obj1;
   atexit(f1);
@@ -43,11 +45,20 @@
       Note also that atexit() is only required to store 32
       functions, and the compiler/library might already be using some of
       those slots.  If you think you may run out, we recommend using
-      the xatexit/xexit combination from libiberty, which has no such limit.
+      the xatexit/xexit combination
+      from libiberty, which has no such limit.

Verbose Terminate Handler

If you are having difficulty with uncaught exceptions and want a little bit of help debugging the causes of the core dumps, you can make use of a GNU extension, the verbose terminate handler. +

+ The verbose terminate handler is only available for hosted environments + (see Configuring) and will be used + by default unless the library is built with + --disable-libstdcxx-verbose + or with exceptions disabled. + If you need to enable it explicitly you can do so by calling the + std::set_terminate function. 

 #include <exception>
 
@@ -61,12 +72,13 @@ int main()

The __verbose_terminate_handler function obtains the name of the current exception, attempts to demangle - it, and prints it to stderr. If the exception is derived from - exception then the output from + it, and prints it to stderr. + If the exception is derived from + std::exception then the output from what() will be included.

Any replacement termination function is required to kill the - program without returning; this one calls abort. + program without returning; this one calls std::abort.

For example: 

@@ -99,13 +111,14 @@ int main(int argc)
    Aborted

- The 'Aborted' line comes from the call to - abort(), of course. + The 'Aborted' line is printed by the shell after the process exits + by calling abort().

- This is the default termination handler; nothing need be done to + As this is the default termination handler, nothing need be done to use it. To go back to the previous “silent death” - method, simply include exception and - cstdlib, and call + method, simply include + <exception> and + <cstdlib>, and call 

      std::set_terminate(std::abort);

@@ -113,8 +126,8 @@ int main(int argc) abort as the terminate handler.

Note: the verbose terminate handler will attempt to write to - stderr. If your application closes stderr or redirects it to an - inappropriate location, + stderr. If your application closes + stderr or redirects it to an inappropriate location, __verbose_terminate_handler will behave in an unspecified manner.

Prev Up Next
Dynamic Memory Home Chapter 5.  diff --git a/libstdc++-v3/doc/xml/manual/diagnostics.xml b/libstdc++-v3/doc/xml/manual/diagnostics.xml index 67620e2cb40..08f576965d2 100644 --- a/libstdc++-v3/doc/xml/manual/diagnostics.xml +++ b/libstdc++-v3/doc/xml/manual/diagnostics.xml @@ -21,28 +21,38 @@
API Reference - All exception objects are defined in one of the standard header - files: exception, - stdexcept, new, and - typeinfo. + Most exception classes are defined in one of the standard headers + <exception>, + <stdexcept>, + <new>, and + <typeinfo>. + The C++ 2011 revision of the standard added more exception types + in the headers + <functional>, + <future>, + <regex>, and + <system_error>. + The C++ 2017 revision of the standard added more exception types + in the headers + <any>, + <filesystem>, + <optional>, and + <variant>. - The base exception object is exception, - located in exception. This object has no - string member. + All exceptions thrown by the library have a base class of type + std::exception, + defined in <exception>. + This type has no std::string member. Derived from this are several classes that may have a - string member: a full hierarchy can be + std::string member. A full hierarchy can be found in the source documentation. - - Full API details. - -
diff --git a/libstdc++-v3/doc/xml/manual/support.xml b/libstdc++-v3/doc/xml/manual/support.xml index 53f4fbc5225..da8fed0e015 100644 --- a/libstdc++-v3/doc/xml/manual/support.xml +++ b/libstdc++-v3/doc/xml/manual/support.xml @@ -26,9 +26,9 @@
Types - +
Fundamental Types - + C++ has the following builtin types: @@ -90,11 +90,9 @@
Numeric Properties - - - The header limits defines + The header <limits> defines traits classes to give access to various implementation defined-aspects of the fundamental types. The traits classes -- fourteen in total -- are all specializations of the class template @@ -145,42 +143,50 @@
NULL - + The only change that might affect people is the type of NULL: while it is required to be a macro, the definition of that macro is not allowed - to be (void*)0, which is often used in C. + to be an expression with pointer type such as + (void*)0, which is often used in C. For g++, NULL is #define'd to be __null, a magic keyword extension of - g++. + g++ that is slightly safer than a plain integer. The biggest problem of #defining NULL to be something like 0L is that the compiler will view that as a long integer before it views it as a pointer, so - overloading won't do what you expect. (This is why - g++ has a magic extension, so that - NULL is always a pointer.) + overloading won't do what you expect. It might not even have the + same size as a pointer, so passing NULL to a + varargs function where a pointer is expected might not even work + correctly if sizeof(NULL) < sizeof(void*). + The G++ __null extension is defined so that + sizeof(__null) == sizeof(void*) to avoid this problem. - In his book Effective - C++, Scott Meyers points out that the best way - to solve this problem is to not overload on pointer-vs-integer - types to begin with. He also offers a way to make your own magic - NULL that will match pointers before it - matches integers. + + Scott Meyers explains this in more detail in his book + Effective + Modern C++ and as a guideline to solve this problem + recommends to not overload on pointer-vs-integer types to begin with. - See the - Effective - C++ CD example. + + + The C++ 2011 standard added the nullptr keyword, + which is a null pointer constant of a special type, + std::nullptr_t. Values of this type can be + implicitly converted to any pointer type, + and cannot convert to integer types or be deduced as an integer type. + Unless you need to be compatible with C++98/C++03 or C you should prefer + to use nullptr instead of NULL.
@@ -188,59 +194,157 @@
Dynamic Memory - + - There are six flavors each of new and - delete, so make certain that you're using the right - ones. Here are quickie descriptions of new: + In C++98 there are six flavors each of operator new + and operator delete, so make certain that you're + using the right ones. + Here are quickie descriptions of operator new: - - - single object form, throwing a - bad_alloc on errors; this is what most - people are used to using - - - Single object "nothrow" form, returning NULL on errors - - - Array new, throwing - bad_alloc on errors - - - Array nothrow new, returning - NULL on errors - - - Placement new, which does nothing (like - it's supposed to) - - - Placement array new, which also does - nothing - - + + + void* operator new(std::size_t); + + Single object form. + Throws std::bad_alloc on error. + This is what most people are used to using. + + + + void* operator new(std::size_t, std::nothrow_t) noexcept; + + Single object nothrow form. + Calls operator new(std::size_t) but if that throws, + returns a null pointer instead. + + + + void* operator new[](std::size_t); + + Array new. + Calls operator new(std::size_t) and so + throws std::bad_alloc on error. + + + + void* operator new[](std::size_t, std::nothrow_t) noexcept; + + Array nothrow new. + Calls operator new[](std::size_t) but if that throws, + returns a null pointer instead. + + + + void* operator new(std::size_t, void*) noexcept; + + Non-allocating, placement single-object new, + which does nothing except return its argument. + This function cannot be replaced. + + + + void* operator new[](std::size_t, void*) noexcept; + + Non-allocating, placement array new, + which also does nothing except return its argument. + This function cannot be replaced. + + + - They are distinguished by the parameters that you pass to them, like - any other overloaded function. The six flavors of delete + They are distinguished by the arguments that you pass to them, like + any other overloaded function. The six flavors of + operator delete are distinguished the same way, but none of them are allowed to throw - an exception under any circumstances anyhow. (They match up for - completeness' sake.) + an exception under any circumstances anyhow. (The overloads match up + with the ones above, for completeness' sake.) - Remember that it is perfectly okay to call delete on a - NULL pointer! Nothing happens, by definition. That is not the - same thing as deleting a pointer twice. + The C++ 2014 revision of the standard added two additional overloads of + operator delete for sized deallocation, + allowing the compiler to provide the size of the storage being freed. + + + The C++ 2017 standard added even more overloads of both + operator new and operator delete + for allocating and deallocating storage for overaligned types. + These overloads correspond to each of the allocating forms of + operator new and operator delete + but with an additional parameter of type std::align_val_t. + These new overloads are not interchangeable with the versions without + an aligment parameter, so if memory was allocated by an overload of + operator new taking an alignment parameter, + then it must be decallocated by the corresponding overload of + operator delete that takes an alignment parameter. - By default, if one of the throwing news can't - allocate the memory requested, it tosses an instance of a - bad_alloc exception (or, technically, some class derived - from it). You can change this by writing your own function (called a - new-handler) and then registering it with set_new_handler(): + Apart from the non-allocating forms, the default versions of the array + and nothrow operator new functions will all result + in a call to either operator new(std::size_t) or + operator new(std::size_t, std::align_val_t), + and similarly the default versions of the array and nothrow + operator delete functions will result in a call to + either operator delete(void*) or + operator delete(void*, std::align_val_t) + (or the sized versions of those). + + + Apart from the non-allocating forms, any of these functions can be + replaced by defining a function with the same signature in your program. + Replacement versions must preserve certain guarantees, such as memory + obtained from a nothrow operator new being free-able + by the normal (non-nothrow) operator delete, + and the sized and unsized forms of operator delete + being interchangeable (because it's unspecified whether + the compiler calls the sized delete instead of the normal one). + The simplest way to meet the guarantees is to only replace the ordinary + operator new(size_t) and + operator delete(void*) and + operator delete(void*, std::size_t) + functions, and the replaced versions will be used by all of + operator new(size_t, nothrow_t), + operator new[](size_t) and + operator new[](size_t, nothrow_t) + and the corresponding operator delete functions. + To support types with extended alignment you may also need to replace + operator new(size_t, align_val_t) and + operator delete(void*, align_val_t) + operator delete(void*, size_t, align_val_t) + (which will then be used by the nothrow and array forms for + extended alignments). + If you do need to replace other forms (e.g. to define the nothrow + operator new to allocate memory directly, so it + works with exceptions disabled) then make sure the memory it allocates + can still be freed by the non-nothrow forms of + operator delete. + + + If the default versions of operator new(std::size_t) + and operator new(size_t, std::align_val_t) + can't allocate the memory requested, they usually throw an exception + object of type std::bad_alloc (or some class + derived from that). However, the program can influence that behavior + by registering a new-handler, because what + operator new actually does is something like: - typedef void (*PFV)(void); + while (true) + { + if (void* p = /* try to allocate memory */) + return p; + else if (std::new_handler h = std::get_new_handler ()) + h (); + else + throw bad_alloc{}; + } + + + This means you can influence what happens on allocation failure by + writing your own new-handler and then registering it with + std::set_new_handler: + + + typedef void (*PFV)(); static char* safety; static PFV old_handler; @@ -248,6 +352,7 @@ void my_new_handler () { delete[] safety; + safety = nullptr; popup_window ("Dude, you are running low on heap memory. You" " should, like, close some windows, or something." " The next time you run out, we're gonna burn!"); @@ -262,19 +367,32 @@ ... } + +
Additional Notes + - bad_alloc is derived from the base exception - class defined in Sect1 19. + Remember that it is perfectly okay to delete a + null pointer! Nothing happens, by definition. That is not the + same thing as deleting a pointer twice. + + std::bad_alloc is derived from the base + std::exception class, + see . + +
+
Termination - +
Termination Handlers - + - Not many changes here to cstdlib. You should note that the + Not many changes here to + <cstdlib>. + You should note that the abort() function does not call the destructors of automatic nor static objects, so if you're depending on those to do cleanup, it isn't going to happen. @@ -306,8 +424,8 @@ given this pseudocode: - extern "C or C++" void f1 (void); - extern "C or C++" void f2 (void); + extern "C or C++" void f1 (); + extern "C or C++" void f2 (); static Thing obj1; atexit(f1); @@ -329,19 +447,30 @@ Note also that atexit() is only required to store 32 functions, and the compiler/library might already be using some of those slots. If you think you may run out, we recommend using - the xatexit/xexit combination from libiberty, which has no such limit. + the xatexit/xexit combination + from libiberty, which has no such limit.
Verbose Terminate Handler - + If you are having difficulty with uncaught exceptions and want a little bit of help debugging the causes of the core dumps, you can make use of a GNU extension, the verbose terminate handler. + + The verbose terminate handler is only available for hosted environments + (see ) and will be used + by default unless the library is built with + + or with exceptions disabled. + If you need to enable it explicitly you can do so by calling the + std::set_terminate function. + + #include <exception> @@ -357,14 +486,15 @@ int main() The __verbose_terminate_handler function obtains the name of the current exception, attempts to demangle - it, and prints it to stderr. If the exception is derived from - exception then the output from + it, and prints it to stderr. + If the exception is derived from + std::exception then the output from what() will be included. Any replacement termination function is required to kill the - program without returning; this one calls abort. + program without returning; this one calls std::abort. @@ -407,15 +537,16 @@ int main(int argc) - The 'Aborted' line comes from the call to - abort(), of course. + The 'Aborted' line is printed by the shell after the process exits + by calling abort(). - This is the default termination handler; nothing need be done to + As this is the default termination handler, nothing need be done to use it. To go back to the previous silent death - method, simply include exception and - cstdlib, and call + method, simply include + <exception> and + <cstdlib>, and call @@ -429,8 +560,8 @@ int main(int argc) Note: the verbose terminate handler will attempt to write to - stderr. If your application closes stderr or redirects it to an - inappropriate location, + stderr. If your application closes + stderr or redirects it to an inappropriate location, __verbose_terminate_handler will behave in an unspecified manner. -- 2.30.2