ceph/src/boost/libs/core/doc/checked_delete.qbk

   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]