From 32fb45eba9a4e98d433dc4846dfe3cbd471dfa30 Mon Sep 17 00:00:00 2001 From: Peter Dimov Date: Thu, 14 Nov 2002 14:53:32 +0000 Subject: [PATCH] checked_delete.hpp documentation added. [SVN r16238] --- checked_delete.html | 124 ++++++++++++++ include/boost/checked_delete.hpp | 3 + index.html | 61 ++++--- utility.htm | 276 +++++++++++++------------------ 4 files changed, 267 insertions(+), 197 deletions(-) create mode 100644 checked_delete.html diff --git a/checked_delete.html b/checked_delete.html new file mode 100644 index 0000000..bd7753e --- /dev/null +++ b/checked_delete.html @@ -0,0 +1,124 @@ + + + + Boost: checked_delete.hpp documentation + + + + + + + + + + + +
+ c++boost.gif (8819 bytes) + +

checked_delete.hpp

+
 
+

+ The header <boost/checked_delete.hpp> defines two + function templates, checked_delete and checked_array_delete, + and two class templates, checked_deleter and checked_array_deleter. +

+

The C++ Standard allows, in 5.3.5/5, pointers to incomplete class types to + be deleted with a delete-expression. When the class has a non-trivial + destructor, or a class-specific operator delete, the behavior is undefined. + Some compilers issue a warning when an incomplete type is deleted, but + unfortunately, not all do, and programmers sometimes ignore or disable + warnings.

+

A particularly troublesome case is when a smart pointer's destructor, such as + boost::scoped_ptr<T>::~scoped_ptr, is instantiated with an + incomplete type. This can often lead to silent, hard to track failures.

+

The supplied function and class templates can be used to prevent these problems, + as they require a complete type, and cause a compilation error otherwise.

+

Synopsis

+ 
+namespace boost
+{
+
+template<class T> void checked_delete(T * p);
+template<class T> void checked_array_delete(T * p);
+template<class T> struct checked_deleter;
+template<class T> struct checked_array_deleter;
+
+}
+
+

checked_delete

+

template<class T> void checked_delete(T * p);

+
+

+ Requires: T must be a complete type. The expression delete p + must be well-formed. +

+

+ Effects: delete p; +

+
+

checked_array_delete

+

template<class T> void checked_array_delete(T + * p);

+
+

+ Requires: T must be a complete type. The expression delete [] p + must be well-formed. +

+

+ Effects: delete [] p; +

+
+

checked_deleter

+ 
+template<class T> struct checked_deleter
+{
+    typedef void result_type;
+    typedef T * argument_type;
+    void operator()(T * p);
+};
+
+

void checked_deleter<T>::operator()(T * p);

+
+

+ Requires: T must be a complete type. The expression delete p + must be well-formed. +

+

+ Effects: delete p; +

+
+

checked_array_deleter

+ 
+template<class T> struct checked_array_deleter
+{
+    typedef void result_type;
+    typedef T * argument_type;
+    void operator()(T * p);
+};
+
+

void checked_array_deleter<T>::operator()(T * p);

+
+

+ Requires: T must be a complete type. The expression delete [] p + must be well-formed. +

+

+ Effects: delete [] p; +

+
+

Acknowledgements

+

+ The function templates checked_delete and checked_array_delete + were originally part of <boost/utility.hpp>, and the + documentation acknowledged Beman Dawes, Dave Abrahams, Vladimir Prus, + Rainer Deyke, John Maddock, and others as contributors. +

+

+
+ Copyright © 2002 by Peter Dimov. Permission to copy, use, modify, sell + and distribute this document is granted provided this copyright notice appears + in all copies. This document is provided "as is" without express or implied + warranty, and with no claim as to its suitability for any purpose.

+ + diff --git a/include/boost/checked_delete.hpp b/include/boost/checked_delete.hpp index 9e42d9c..bf689c9 100644 --- a/include/boost/checked_delete.hpp +++ b/include/boost/checked_delete.hpp @@ -9,12 +9,15 @@ // boost/checked_delete.hpp // // Copyright (c) 1999, 2000, 2001, 2002 boost.org +// Copyright (c) 2002 Peter Dimov // // Permission to copy, use, modify, sell and distribute this software // is granted provided this copyright notice appears in all copies. // This software is provided "as is" without express or implied // warranty, and with no claim as to its suitability for any purpose. // +// http://www.boost.org/libs/utility/checked_delete.html +// namespace boost { diff --git a/index.html b/index.html index b6f6875..d77a197 100644 --- a/index.html +++ b/index.html @@ -1,34 +1,31 @@ - - - - - - -Boost Utility Library - - - - -

Boost -Utility Library

-

The Boost Utility Library isn't really a single library at all.  It is -just a collection for components too small to be called libraries in their own -right.

-

But that doesn't mean there isn't useful stuff here.  Take a look:

-
-

base_from_member
- call_traits.htm
- compressed_pair.htm
- operators.htm
- tie
- utility.htm

-
-
-

Revised -07 May, 2002

-

 

- - - + + + + + + Boost Utility Library + + +

Boost + Utility Library

+

The Boost Utility Library isn't really a single library at all. It is just + a collection for components too small to be called libraries in their own + right.

+

But that doesn't mean there isn't useful stuff here. Take a look:

+
+

base_from_member
+ call_traits.htm
+ checked_delete.html
+ compressed_pair.htm
+ operators.htm
+ tie
+ utility.htm

+
+
+

Revised + + 07 May, 2002

+

 

+ diff --git a/utility.htm b/utility.htm index 9a24679..8c624d5 100644 --- a/utility.htm +++ b/utility.htm @@ -1,168 +1,114 @@ - - - -Header boost/utility.hpp Documentation - - - - -

c++boost.gif (8819 bytes)Header -boost/utility.hpp

- -

The entire contents of the header <boost/utility.hpp> - are in namespace boost.

- -

Contents

- - -

Function templates checked_delete() and -checked_array_delete()

- -

Deletion of a pointer to an incomplete type is an unsafe programming practice -because there is no way for the compiler to verify that the destructor is indeed -trivial.  The checked_delete() and checked_array_delete() function -templates simply delete or delete[] their argument, but also -require that their argument be a complete type.  They issue an appropriate -compiler error diagnostic if that requirement is not met.  A typical -implementation is shown; other implementations may vary:

- -
    template< typename T >
-    inline void checked_delete(T const volatile * x)
-    {
-        BOOST_STATIC_ASSERT( sizeof(T) ); // assert type complete at point
-                                          // of instantiation
-        delete x;
-    }
-
-    template< typename T >
-    inline void checked_array_delete(T const volatile * x)
-    {
-        BOOST_STATIC_ASSERT( sizeof(T) ); // assert type complete at point
-                                          // of instantiation
-        delete [] x;
-    }
- -

Contributed by Beman Dawes, based on a suggestion from Dave Abrahams, -generalizing an idea from Vladimir Prus, with comments from Rainer Deyke, John -Maddock, and others.

- -

Background

- -

The C++ Standard specifies that delete on a pointer to an incomplete types is -undefined behavior if the type has a non-trivial destructor in  [expr.delete] -5.3.5 paragraph.  No diagnostic is required.  Some but not all -compilers issue warnings if the type is incomplete at point of deletion.

- -

Function templates next() and prior()

- -

Certain data types, such as the C++ Standard Library's forward and -bidirectional iterators, do not provide addition and subtraction via operator+() -or operator-().  This means that non-modifying computation of the next or -prior value requires a temporary, even though operator++() or operator--() is -provided.  It also means that writing code like itr+1 inside a -template restricts the iterator category to random access iterators.

- -

The next() and prior() functions provide a simple way around these problems:

- -
- -
template <class T>
+	
+		
+		Header boost/utility.hpp Documentation
+	
+	
+		
c++boost.gif (8819 bytes)Header
+			boost/utility.hpp

+		
The entire contents of the header <boost/utility.hpp>
+			are in namespace boost.

+		
Contents

+		
+		

+			Function templates checked_delete() and 
+			checked_array_delete()

+		
See separate documentation.

+		

+			Function templates next() and prior()

+		
Certain data types, such as the C++ Standard Library's forward and bidirectional 
+			iterators, do not provide addition and subtraction via operator+() or 
+			operator-().  This means that non-modifying computation of the next or 
+			prior value requires a temporary, even though operator++() or operator--() is 
+			provided.  It also means that writing code like itr+1 inside 
+			a template restricts the iterator category to random access iterators.

+		
The next() and prior() functions provide a simple way around these problems:

+		

+			
template <class T>
 T next(T x) { return ++x; }
 
 template <class X>
 T prior(T x) { return --x; }

-
-

-
-
Usage is simple:

-
-

-
-
const std::list<T>::iterator p = get_some_iterator();
+		

+		
Usage is simple:

+		

+			
const std::list<T>::iterator p = get_some_iterator();
 const std::list<T>::iterator prev = boost::prior(p);

-
-

-
-
Contributed by Dave Abrahams.

-
-
Class noncopyable

-
-
Class noncopyable is a base class.  Derive your own class from noncopyable
-when you want to prohibit copy construction and copy assignment.

-
-
Some objects, particularly those which hold complex resources like files or
-network connections, have no sensible copy semantics.  Sometimes there are
-possible copy semantics, but these would be of very limited usefulness and be
-very difficult to implement correctly.  Sometimes you're implementing a class that doesn't need to be copied
-just yet and you don't want to take the time to write the appropriate functions. 
-Deriving from  noncopyable will prevent the otherwise implicitly-generated
-functions (which don't have the proper semantics) from becoming a trap for other programmers.

-
-
The traditional way to deal with these is to declare a private copy constructor and copy assignment, and then
-document why this is done.  But deriving from noncopyable is simpler
-and clearer, and doesn't require additional documentation.

-
-
The program noncopyable_test.cpp can be
-used to verify class noncopyable works as expected. It has have been run successfully under
-GCC 2.95, Metrowerks
-CodeWarrior 5.0, and Microsoft Visual C++ 6.0 sp 3.

-
-
Contributed by Dave Abrahams.

-
-
Example

-

-  
// inside one of your own headers ...
+		

+		
Contributed by Dave Abrahams.

+		
Class noncopyable

+		
Class noncopyable is a base class.  Derive your own class 
+			from noncopyable when you want to prohibit copy construction 
+			and copy assignment.

+		
Some objects, particularly those which hold complex resources like files or 
+			network connections, have no sensible copy semantics.  Sometimes there are 
+			possible copy semantics, but these would be of very limited usefulness and be 
+			very difficult to implement correctly.  Sometimes you're implementing a 
+			class that doesn't need to be copied just yet and you don't want to take the 
+			time to write the appropriate functions.  Deriving from noncopyable 
+			will prevent the otherwise implicitly-generated functions (which don't have the 
+			proper semantics) from becoming a trap for other programmers.

+		
The traditional way to deal with these is to declare a private copy constructor 
+			and copy assignment, and then document why this is done.  But deriving 
+			from noncopyable is simpler and clearer, and doesn't require additional 
+			documentation.

+		
The program noncopyable_test.cpp can be used 
+			to verify class noncopyable works as expected. It has have been run 
+			successfully under GCC 2.95, Metrowerks CodeWarrior 5.0, and Microsoft Visual 
+			C++ 6.0 sp 3.

+		
Contributed by Dave Abrahams.

+		
Example

+		

+			
// inside one of your own headers ...
 #include <boost/utility.hpp>
 
 class ResourceLadenFileSystem : boost::noncopyable {
 ...

-

-
-
Rationale

-
Class noncopyable has protected constructor and destructor members to
-emphasize that it is to be used only as a base class.  Dave Abrahams notes
-concern about the effect on compiler optimization of adding (even trivial inline)
-destructor declarations. He says "Probably this concern is misplaced, because
-noncopyable will be used mostly for classes which own resources and thus have non-trivial destruction semantics."

-
Function template addressof()

-
Function addressof() returns the address of an object.

-
-

-
+		

+		
Rationale

+		
Class noncopyable has protected constructor and destructor members to emphasize 
+			that it is to be used only as a base class.  Dave Abrahams notes concern 
+			about the effect on compiler optimization of adding (even trivial inline) 
+			destructor declarations. He says "Probably this concern is misplaced, 
+			because noncopyable will be used mostly for classes which own resources and 
+			thus have non-trivial destruction semantics."

+		
Function template addressof()

+		
Function addressof() returns the address of an object.

+		

+			
 template <typename T> inline T*                addressof(T& v);
 template <typename T> inline const T*          addressof(const T& v);
 template <typename T> inline volatile T*       addressof(volatile T& v);
 template <typename T> inline const volatile T* addressof(const volatile T& v);
 

-

-
-
-
C++ allows programmers to replace the unary
-operator&() class member used to get the address of
-an object.  Getting the real address of an object requires ugly
-casting tricks to avoid invoking the overloaded
-operator&().  Function addressof()
-provides a wrapper around the necessary code to make it easy to get an
-object's real address.
-

-
-
The program addressof_test.cpp can be
-used to verify that addressof() works as expected.

-
-
Contributed by Brad King based on ideas from discussion with Doug Gregor.

-
Example

-

-
#include <boost/utility.hpp>
+		

+		
C++ allows programmers to replace the unary operator&() class 
+			member used to get the address of an object. Getting the real address of an 
+			object requires ugly casting tricks to avoid invoking the overloaded operator&(). 
+			Function addressof() provides a wrapper around the necessary 
+			code to make it easy to get an object's real address.
+		

+		
The program addressof_test.cpp can be used to 
+			verify that addressof() works as expected.

+		
Contributed by Brad King based on ideas from discussion with Doug Gregor.

+		
Example

+		

+			
#include <boost/utility.hpp>
 
 struct useless_type {};
 class nonaddressable {
@@ -174,20 +120,20 @@ void f() {
   nonaddressable* xp = boost::addressof(x);
   // nonaddressable* xpe = &x; /* error */
 }

-

-
-
Class templates for the Base-from-Member Idiom

-
See separate documentation.

-
Function template tie()

-
See separate documentation.

-

-
Revised  10 September, 2001 
+			10 September, 2001
-

-
© Copyright boost.org 1999. Permission to copy, use, modify, sell and
-distribute this document is granted provided this copyright notice appears in
-all copies. This document is provided "as is" without express or
-implied warranty, and with no claim as to its suitability for any purpose.

-
+		

+		
© Copyright boost.org 1999-2002. Permission to copy, use, modify, sell and distribute 
+			this document is granted provided this copyright notice appears in all copies. 
+			This document is provided "as is" without express or implied 
+			warranty, and with no claim as to its suitability for any purpose.

+