+ |
+
+ |
+
+ 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.
+
+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;
+
+}
+
+ +++ Requires: T must be a complete type. The expression delete p + must be well-formed. +
++ Effects: delete p; +
+
+++ Requires: T must be a complete type. The expression delete [] p + must be well-formed. +
++ Effects: delete [] p; +
+
+template<class T> struct checked_deleter
+{
+ typedef void result_type;
+ typedef T * argument_type;
+ void operator()(T * p);
+};
+
+ +++ Requires: T must be a complete type. The expression delete p + must be well-formed. +
++ Effects: delete p; +
+
+template<class T> struct checked_array_deleter
+{
+ typedef void result_type;
+ typedef T * argument_type;
+ void operator()(T * p);
+};
+
+ +++ Requires: T must be a complete type. The expression delete [] p + must be well-formed. +
++ Effects: delete [] p; +
+
+ 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.
Boost
-Utility LibraryThe 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 LibraryThe 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.hppThe entire contents of the header <boost/utility.hpp>
- are in namespace boost.
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.
- -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.
- -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 + + ++
The entire contents of the header
+<boost/utility.hpp>+ are innamespace boost.Contents
++
+- + Class templates supporting the base-from-member + idiom
+- + Function templates checked_delete() and + checked_array_delete()
+- + Function templates next() and prior()
+- + Class noncopyable
+- + Function template addressof()
+- + Function template tie() and supporting class tied.
++ Function templates checked_delete() and + checked_array_delete()
+ ++ 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+1inside + 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
- -Function template tie()
- -
-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.
+