]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/ |
2 | / Copyright (c) 2002, 2003, 2005 Peter Dimov | |
3 | / Copyright (c) 2014 Glen Fernandes | |
4 | / | |
5 | / Distributed under the Boost Software License, Version 1.0. (See | |
6 | / accompanying file LICENSE_1_0.txt or copy at | |
7 | / http://www.boost.org/LICENSE_1_0.txt) | |
8 | /] | |
9 | ||
10 | [section:checked_delete checked_delete] | |
11 | ||
12 | [simplesect Authors] | |
13 | ||
14 | * Beman Dawes | |
15 | * Dave Abrahams | |
16 | * Vladimir Prus | |
17 | * Rainer Deyke | |
18 | * John Maddock | |
19 | ||
20 | [endsimplesect] | |
21 | ||
22 | [section Overview] | |
23 | ||
24 | The header `<boost/checked_delete.hpp>` defines two function | |
25 | templates, `checked_delete` and `checked_array_delete`, and two | |
26 | class templates, `checked_deleter` and `checked_array_deleter`. | |
27 | ||
28 | The C++ Standard allows, in 5.3.5/5, pointers to incomplete | |
29 | class types to be deleted with a delete-expression. When the | |
30 | class has a non-trivial destructor, or a class-specific | |
31 | operator delete, the behavior is undefined. Some compilers | |
32 | issue a warning when an incomplete type is deleted, but | |
33 | unfortunately, not all do, and programmers sometimes ignore or | |
34 | disable warnings. | |
35 | ||
36 | A particularly troublesome case is when a smart pointer's | |
37 | destructor, such as `boost::scoped_ptr<T>::~scoped_ptr`, is | |
38 | instantiated with an incomplete type. This can often lead to | |
39 | silent, hard to track failures. | |
40 | ||
41 | The supplied function and class templates can be used to | |
42 | prevent these problems, as they require a complete type, and | |
43 | cause a compilation error otherwise. | |
44 | ||
45 | [endsect] | |
46 | ||
47 | [section Synopsis] | |
48 | ||
49 | `` | |
50 | namespace boost | |
51 | { | |
52 | template<class T> void checked_delete(T * p); | |
53 | template<class T> void checked_array_delete(T * p); | |
54 | template<class T> struct checked_deleter; | |
55 | template<class T> struct checked_array_deleter; | |
56 | } | |
57 | `` | |
58 | ||
59 | [endsect] | |
60 | ||
61 | [section checked_delete] | |
62 | ||
63 | [section template<class T> void checked_delete(T * p);] | |
64 | ||
65 | * *Requires:* `T` must be a complete type. The expression | |
66 | `delete p` must be well-formed. | |
67 | * *Effects:* `delete p;` | |
68 | ||
69 | [endsect] | |
70 | ||
71 | [endsect] | |
72 | ||
73 | [section checked_array_delete] | |
74 | ||
75 | [section template<class T> void checked_array_delete(T * p);] | |
76 | ||
77 | * *Requires:* `T` must be a complete type. The expression | |
78 | `delete [] p` must be well-formed. | |
79 | * *Effects:* `delete [] p;` | |
80 | ||
81 | [endsect] | |
82 | ||
83 | [endsect] | |
84 | ||
85 | [section checked_deleter] | |
86 | ||
87 | `` | |
88 | template<class T> struct checked_deleter | |
89 | { | |
90 | typedef void result_type; | |
91 | typedef T * argument_type; | |
92 | void operator()(T * p) const; | |
93 | }; | |
94 | `` | |
95 | ||
96 | [section void checked_deleter<T>::operator()(T * p) const;] | |
97 | ||
98 | * *Requires:* `T` must be a complete type. The expression | |
99 | `delete p` must be well-formed. | |
100 | * *Effects:* `delete p;` | |
101 | ||
102 | [endsect] | |
103 | ||
104 | [endsect] | |
105 | ||
106 | [section checked_array_deleter] | |
107 | ||
108 | `` | |
109 | template<class T> struct checked_array_deleter | |
110 | { | |
111 | typedef void result_type; | |
112 | typedef T * argument_type; | |
113 | void operator()(T * p) const; | |
114 | }; | |
115 | `` | |
116 | ||
117 | [section void checked_array_deleter<T>::operator()(T * p) const;] | |
118 | ||
119 | * *Requires:* `T` must be a complete type. The expression | |
120 | `delete [] p` must be well-formed. | |
121 | * *Effects:* `delete [] p;` | |
122 | ||
123 | [endsect] | |
124 | ||
125 | [endsect] | |
126 | ||
127 | [section Acknowledgements] | |
128 | ||
129 | The function templates `checked_delete` and | |
130 | `checked_array_delete` were originally part of | |
131 | `<boost/utility.hpp>`, and the documentation | |
132 | acknowledged Beman Dawes, Dave Abrahams, | |
133 | Vladimir Prus, Rainer Deyke, John Maddock, | |
134 | and others as contributors. | |
135 | ||
136 | [endsect] | |
137 | ||
138 | [endsect] |