[ceph.git] / ceph / src / boost / libs / core / doc / checked_delete.qbk

[/
 /  Copyright (c) 2002, 2003, 2005 Peter Dimov
 /  Copyright (c) 2014 Glen Fernandes
 /
 /  Distributed under the Boost Software License, Version 1.0. (See
 /  accompanying file LICENSE_1_0.txt or copy at
 /  http://www.boost.org/LICENSE_1_0.txt)
 /]

[section:checked_delete checked_delete]

[simplesect Authors]

* Beman Dawes
* Dave Abrahams
* Vladimir Prus
* Rainer Deyke
* John Maddock

[endsimplesect]

[section Overview]

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.

[endsect]

[section 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;
}
``

[endsect]

[section checked_delete]

[section 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;`

[endsect]

[endsect]

[section checked_array_delete]

[section 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;`

[endsect]

[endsect]

[section checked_deleter]

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

[section void checked_deleter<T>::operator()(T * p) const;]

* *Requires:* `T` must be a complete type. The expression
  `delete p` must be well-formed.
* *Effects:* `delete p;`
  
[endsect]

[endsect]

[section checked_array_deleter]

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

[section void checked_array_deleter<T>::operator()(T * p) const;]

* *Requires:* `T` must be a complete type. The expression
  `delete [] p` must be well-formed.
* *Effects:* `delete [] p;`

[endsect]

[endsect]

[section 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.

[endsect]

[endsect]
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]