| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
|---|
| 2 | <html> |
|---|
| 3 | <head> |
|---|
| 4 | <title>Boost: checked_delete.hpp documentation</title> |
|---|
| 5 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
|---|
| 6 | </head> |
|---|
| 7 | <body bgcolor="white" style="MARGIN-LEFT: 5%; MARGIN-RIGHT: 5%"> |
|---|
| 8 | <table border="0" width="100%"> |
|---|
| 9 | <tr> |
|---|
| 10 | <td width="277"><A href="../../index.htm"> <img src="../../boost.png" alt="boost.png (6897 bytes)" width="277" height="86" border="0"></A> |
|---|
| 11 | </td> |
|---|
| 12 | <td align="center"> |
|---|
| 13 | <h1>checked_delete.hpp</h1> |
|---|
| 14 | </td> |
|---|
| 15 | </tr> |
|---|
| 16 | <tr> |
|---|
| 17 | <td colspan="2" height="64"> </td> |
|---|
| 18 | </tr> |
|---|
| 19 | </table> |
|---|
| 20 | <p> |
|---|
| 21 | The header <STRONG><boost/checked_delete.hpp></STRONG> defines two |
|---|
| 22 | function templates, <STRONG>checked_delete</STRONG> and <STRONG>checked_array_delete</STRONG>, |
|---|
| 23 | and two class templates, <STRONG>checked_deleter</STRONG> and <STRONG>checked_array_deleter</STRONG>. |
|---|
| 24 | </p> |
|---|
| 25 | <P>The C++ Standard allows, in 5.3.5/5, pointers to incomplete class types to be |
|---|
| 26 | deleted with a <EM>delete-expression</EM>. When the class has a non-trivial |
|---|
| 27 | destructor, or a class-specific operator delete, the behavior is undefined. |
|---|
| 28 | Some compilers issue a warning when an incomplete type is deleted, but |
|---|
| 29 | unfortunately, not all do, and programmers sometimes ignore or disable |
|---|
| 30 | warnings.</P> |
|---|
| 31 | <P>A particularly troublesome case is when a smart pointer's destructor, such as <STRONG> |
|---|
| 32 | boost::scoped_ptr<T>::~scoped_ptr</STRONG>, is instantiated with an |
|---|
| 33 | incomplete type. This can often lead to silent, hard to track failures.</P> |
|---|
| 34 | <P>The supplied function and class templates can be used to prevent these problems, |
|---|
| 35 | as they require a complete type, and cause a compilation error otherwise.</P> |
|---|
| 36 | <h3><a name="Synopsis">Synopsis</a></h3> |
|---|
| 37 | <pre> |
|---|
| 38 | namespace boost |
|---|
| 39 | { |
|---|
| 40 | |
|---|
| 41 | template<class T> void checked_delete(T * p); |
|---|
| 42 | template<class T> void checked_array_delete(T * p); |
|---|
| 43 | template<class T> struct checked_deleter; |
|---|
| 44 | template<class T> struct checked_array_deleter; |
|---|
| 45 | |
|---|
| 46 | } |
|---|
| 47 | </pre> |
|---|
| 48 | <h3>checked_delete</h3> |
|---|
| 49 | <h4><a name="checked_delete">template<class T> void checked_delete(T * p);</a></h4> |
|---|
| 50 | <blockquote> |
|---|
| 51 | <p> |
|---|
| 52 | <b>Requires:</b> <b>T</b> must be a complete type. The expression <tt>delete p</tt> |
|---|
| 53 | must be well-formed. |
|---|
| 54 | </p> |
|---|
| 55 | <p> |
|---|
| 56 | <b>Effects:</b> <tt>delete p;</tt> |
|---|
| 57 | </p> |
|---|
| 58 | </blockquote> |
|---|
| 59 | <h3>checked_array_delete</h3> |
|---|
| 60 | <h4><a name="checked_array_delete">template<class T> void checked_array_delete(T |
|---|
| 61 | * p);</a></h4> |
|---|
| 62 | <blockquote> |
|---|
| 63 | <p> |
|---|
| 64 | <b>Requires:</b> <b>T</b> must be a complete type. The expression <tt>delete [] p</tt> |
|---|
| 65 | must be well-formed. |
|---|
| 66 | </p> |
|---|
| 67 | <p> |
|---|
| 68 | <b>Effects:</b> <tt>delete [] p;</tt> |
|---|
| 69 | </p> |
|---|
| 70 | </blockquote> |
|---|
| 71 | <h3>checked_deleter</h3> |
|---|
| 72 | <pre> |
|---|
| 73 | template<class T> struct checked_deleter |
|---|
| 74 | { |
|---|
| 75 | typedef void result_type; |
|---|
| 76 | typedef T * argument_type; |
|---|
| 77 | void operator()(T * p) const; |
|---|
| 78 | }; |
|---|
| 79 | </pre> |
|---|
| 80 | <h4>void checked_deleter<T>::operator()(T * p) const;</h4> |
|---|
| 81 | <blockquote> |
|---|
| 82 | <p> |
|---|
| 83 | <b>Requires:</b> <b>T</b> must be a complete type. The expression <tt>delete p</tt> |
|---|
| 84 | must be well-formed. |
|---|
| 85 | </p> |
|---|
| 86 | <p> |
|---|
| 87 | <b>Effects:</b> <tt>delete p;</tt> |
|---|
| 88 | </p> |
|---|
| 89 | </blockquote> |
|---|
| 90 | <h3>checked_array_deleter</h3> |
|---|
| 91 | <pre> |
|---|
| 92 | template<class T> struct checked_array_deleter |
|---|
| 93 | { |
|---|
| 94 | typedef void result_type; |
|---|
| 95 | typedef T * argument_type; |
|---|
| 96 | void operator()(T * p) const; |
|---|
| 97 | }; |
|---|
| 98 | </pre> |
|---|
| 99 | <h4>void checked_array_deleter<T>::operator()(T * p) const;</h4> |
|---|
| 100 | <blockquote> |
|---|
| 101 | <p> |
|---|
| 102 | <b>Requires:</b> <b>T</b> must be a complete type. The expression <tt>delete [] p</tt> |
|---|
| 103 | must be well-formed. |
|---|
| 104 | </p> |
|---|
| 105 | <p> |
|---|
| 106 | <b>Effects:</b> <tt>delete [] p;</tt> |
|---|
| 107 | </p> |
|---|
| 108 | </blockquote> |
|---|
| 109 | <h3><a name="Acknowledgements">Acknowledgements</a></h3> |
|---|
| 110 | <p> |
|---|
| 111 | The function templates <STRONG>checked_delete</STRONG> and <STRONG>checked_array_delete</STRONG> |
|---|
| 112 | were originally part of <STRONG><boost/utility.hpp></STRONG>, and the |
|---|
| 113 | documentation acknowledged Beman Dawes, Dave Abrahams, Vladimir Prus, Rainer |
|---|
| 114 | Deyke, John Maddock, and others as contributors. |
|---|
| 115 | </p> |
|---|
| 116 | <p> |
|---|
| 117 | <br> |
|---|
| 118 | <small>Copyright © 2002 by Peter Dimov. Distributed under the Boost Software License, Version |
|---|
| 119 | 1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or |
|---|
| 120 | copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p> |
|---|
| 121 | </body> |
|---|
| 122 | </html> |
|---|
