libstdc++-v3/include/bits/stl_memory.h

   1 // Memory implementation -*- C++ -*-
   2
   3 // Copyright (C) 2007 Free Software Foundation, Inc.
   4 //
   5 // This file is part of the GNU ISO C++ Library.  This library is free
   6 // software; you can redistribute it and/or modify it under the
   7 // terms of the GNU General Public License as published by the
   8 // Free Software Foundation; either version 2, or (at your option)
   9 // any later version.
  10
  11 // This library is distributed in the hope that it will be useful,
  12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 // GNU General Public License for more details.
  15
  16 // You should have received a copy of the GNU General Public License
  17 // along with this library; see the file COPYING.  If not, write to
  18 // the Free Software Foundation, 51 Franklin Street, Fifth Floor,
  19 // Boston, MA 02110-1301, USA.
  20
  21 // As a special exception, you may use this file as part of a free software
  22 // library without restriction.  Specifically, if other files instantiate
  23 // templates or use macros or inline functions from this file, or you compile
  24 // this file and link it with other files to produce an executable, this
  25 // file does not by itself cause the resulting executable to be covered by
  26 // the GNU General Public License.  This exception does not however
  27 // invalidate any other reasons why the executable file might be covered by
  28 // the GNU General Public License.
  29
  30 /** @file stl_memory.h
  31  *  This is an internal header file, included by other library headers.
  32  *  You should not attempt to use it directly.
  33  */
  34
  35 #ifndef _STL_MEMORY_H
  36 #define _STL_MEMORY_H 1
  37
  38 #include <bits/stl_algobase.h>
  39 #include <bits/allocator.h>
  40 #include <bits/stl_construct.h>
  41 #include <bits/stl_uninitialized.h>
  42 #include <bits/stl_raw_storage_iter.h>
  43 #include <debug/debug.h>
  44 #include <limits>
  45
  46 _GLIBCXX_BEGIN_NAMESPACE(std)
  47
  48   /**
  49    *  @if maint
  50    *  This is a helper function.  The unused second parameter exists to
  51    *  permit the real get_temporary_buffer to use template parameter deduction.
  52    *
  53    *  XXX This should perhaps use the pool.
  54    *  @endif
  55    */
  56   template<typename _Tp>
  57     pair<_Tp*, ptrdiff_t>
  58     __get_temporary_buffer(ptrdiff_t __len, _Tp*)
  59     {
  60       const ptrdiff_t __max = numeric_limits<ptrdiff_t>::max() / sizeof(_Tp);
  61       if (__len > __max)
  62         __len = __max;
  63
  64       while (__len > 0)
  65         {
  66           _Tp* __tmp = static_cast<_Tp*>(::operator new(__len * sizeof(_Tp),
  67                                                         nothrow));
  68           if (__tmp != 0)
  69             return pair<_Tp*, ptrdiff_t>(__tmp, __len);
  70           __len /= 2;
  71         }
  72       return pair<_Tp*, ptrdiff_t>(static_cast<_Tp*>(0), 0);
  73     }
  74
  75   /**
  76    *  @brief Allocates a temporary buffer.
  77    *  @param  len  The number of objects of type Tp.
  78    *  @return See full description.
  79    *
  80    *  Reinventing the wheel, but this time with prettier spokes!
  81    *
  82    *  This function tries to obtain storage for @c len adjacent Tp
  83    *  objects.  The objects themselves are not constructed, of course.
  84    *  A pair<> is returned containing "the buffer s address and
  85    *  capacity (in the units of sizeof(Tp)), or a pair of 0 values if
  86    *  no storage can be obtained."  Note that the capacity obtained
  87    *  may be less than that requested if the memory is unavailable;
  88    *  you should compare len with the .second return value.
  89    *
  90    * Provides the nothrow exception guarantee.
  91    */
  92   template<typename _Tp>
  93     inline pair<_Tp*, ptrdiff_t>
  94     get_temporary_buffer(ptrdiff_t __len)
  95     { return std::__get_temporary_buffer(__len, static_cast<_Tp*>(0)); }
  96
  97   /**
  98    *  @brief The companion to get_temporary_buffer().
  99    *  @param  p  A buffer previously allocated by get_temporary_buffer.
 100    *  @return   None.
 101    *
 102    *  Frees the memory pointed to by p.
 103    */
 104   template<typename _Tp>
 105     void
 106     return_temporary_buffer(_Tp* __p)
 107     { ::operator delete(__p, nothrow); }
 108
 109   /**
 110    *  A wrapper class to provide auto_ptr with reference semantics.
 111    *  For example, an auto_ptr can be assigned (or constructed from)
 112    *  the result of a function which returns an auto_ptr by value.
 113    *
 114    *  All the auto_ptr_ref stuff should happen behind the scenes.
 115    */
 116   template<typename _Tp1>
 117     struct auto_ptr_ref
 118     {
 119       _Tp1* _M_ptr;
 120
 121       explicit
 122       auto_ptr_ref(_Tp1* __p): _M_ptr(__p) { }
 123     };
 124
 125
 126   /**
 127    *  @brief  A simple smart pointer providing strict ownership semantics.
 128    *
 129    *  The Standard says:
 130    *  <pre>
 131    *  An @c auto_ptr owns the object it holds a pointer to.  Copying
 132    *  an @c auto_ptr copies the pointer and transfers ownership to the
 133    *  destination.  If more than one @c auto_ptr owns the same object
 134    *  at the same time the behavior of the program is undefined.
 135    *
 136    *  The uses of @c auto_ptr include providing temporary
 137    *  exception-safety for dynamically allocated memory, passing
 138    *  ownership of dynamically allocated memory to a function, and
 139    *  returning dynamically allocated memory from a function.  @c
 140    *  auto_ptr does not meet the CopyConstructible and Assignable
 141    *  requirements for Standard Library <a
 142    *  href="tables.html#65">container</a> elements and thus
 143    *  instantiating a Standard Library container with an @c auto_ptr
 144    *  results in undefined behavior.
 145    *  </pre>
 146    *  Quoted from [20.4.5]/3.
 147    *
 148    *  Good examples of what can and cannot be done with auto_ptr can
 149    *  be found in the libstdc++ testsuite.
 150    *
 151    *  @if maint
 152    *  _GLIBCXX_RESOLVE_LIB_DEFECTS
 153    *  127.  auto_ptr<> conversion issues
 154    *  These resolutions have all been incorporated.
 155    *  @endif
 156    */
 157   template<typename _Tp>
 158     class auto_ptr
 159     {
 160     private:
 161       _Tp* _M_ptr;
 162
 163     public:
 164       /// The pointed-to type.
 165       typedef _Tp element_type;
 166
 167       /**
 168        *  @brief  An %auto_ptr is usually constructed from a raw pointer.
 169        *  @param  p  A pointer (defaults to NULL).
 170        *
 171        *  This object now @e owns the object pointed to by @a p.
 172        */
 173       explicit
 174       auto_ptr(element_type* __p = 0) throw() : _M_ptr(__p) { }
 175
 176       /**
 177        *  @brief  An %auto_ptr can be constructed from another %auto_ptr.
 178        *  @param  a  Another %auto_ptr of the same type.
 179        *
 180        *  This object now @e owns the object previously owned by @a a,
 181        *  which has given up ownsership.
 182        */
 183       auto_ptr(auto_ptr& __a) throw() : _M_ptr(__a.release()) { }
 184
 185       /**
 186        *  @brief  An %auto_ptr can be constructed from another %auto_ptr.
 187        *  @param  a  Another %auto_ptr of a different but related type.
 188        *
 189        *  A pointer-to-Tp1 must be convertible to a
 190        *  pointer-to-Tp/element_type.
 191        *
 192        *  This object now @e owns the object previously owned by @a a,
 193        *  which has given up ownsership.
 194        */
 195       template<typename _Tp1>
 196         auto_ptr(auto_ptr<_Tp1>& __a) throw() : _M_ptr(__a.release()) { }
 197
 198       /**
 199        *  @brief  %auto_ptr assignment operator.
 200        *  @param  a  Another %auto_ptr of the same type.
 201        *
 202        *  This object now @e owns the object previously owned by @a a,
 203        *  which has given up ownsership.  The object that this one @e
 204        *  used to own and track has been deleted.
 205        */
 206       auto_ptr&
 207       operator=(auto_ptr& __a) throw()
 208       {
 209         reset(__a.release());
 210         return *this;
 211       }
 212
 213       /**
 214        *  @brief  %auto_ptr assignment operator.
 215        *  @param  a  Another %auto_ptr of a different but related type.
 216        *
 217        *  A pointer-to-Tp1 must be convertible to a pointer-to-Tp/element_type.
 218        *
 219        *  This object now @e owns the object previously owned by @a a,
 220        *  which has given up ownsership.  The object that this one @e
 221        *  used to own and track has been deleted.
 222        */
 223       template<typename _Tp1>
 224         auto_ptr&
 225         operator=(auto_ptr<_Tp1>& __a) throw()
 226         {
 227           reset(__a.release());
 228           return *this;
 229         }
 230
 231       /**
 232        *  When the %auto_ptr goes out of scope, the object it owns is
 233        *  deleted.  If it no longer owns anything (i.e., @c get() is
 234        *  @c NULL), then this has no effect.
 235        *
 236        *  @if maint
 237        *  The C++ standard says there is supposed to be an empty throw
 238        *  specification here, but omitting it is standard conforming.  Its
 239        *  presence can be detected only if _Tp::~_Tp() throws, but this is
 240        *  prohibited.  [17.4.3.6]/2
 241        *  @endif
 242        */
 243       ~auto_ptr() { delete _M_ptr; }
 244
 245       /**
 246        *  @brief  Smart pointer dereferencing.
 247        *
 248        *  If this %auto_ptr no longer owns anything, then this
 249        *  operation will crash.  (For a smart pointer, "no longer owns
 250        *  anything" is the same as being a null pointer, and you know
 251        *  what happens when you dereference one of those...)
 252        */
 253       element_type&
 254       operator*() const throw()
 255       {
 256         _GLIBCXX_DEBUG_ASSERT(_M_ptr != 0);
 257         return *_M_ptr;
 258       }
 259
 260       /**
 261        *  @brief  Smart pointer dereferencing.
 262        *
 263        *  This returns the pointer itself, which the language then will
 264        *  automatically cause to be dereferenced.
 265        */
 266       element_type*
 267       operator->() const throw()
 268       {
 269         _GLIBCXX_DEBUG_ASSERT(_M_ptr != 0);
 270         return _M_ptr;
 271       }
 272
 273       /**
 274        *  @brief  Bypassing the smart pointer.
 275        *  @return  The raw pointer being managed.
 276        *
 277        *  You can get a copy of the pointer that this object owns, for
 278        *  situations such as passing to a function which only accepts
 279        *  a raw pointer.
 280        *
 281        *  @note  This %auto_ptr still owns the memory.
 282        */
 283       element_type*
 284       get() const throw() { return _M_ptr; }
 285
 286       /**
 287        *  @brief  Bypassing the smart pointer.
 288        *  @return  The raw pointer being managed.
 289        *
 290        *  You can get a copy of the pointer that this object owns, for
 291        *  situations such as passing to a function which only accepts
 292        *  a raw pointer.
 293        *
 294        *  @note  This %auto_ptr no longer owns the memory.  When this object
 295        *  goes out of scope, nothing will happen.
 296        */
 297       element_type*
 298       release() throw()
 299       {
 300         element_type* __tmp = _M_ptr;
 301         _M_ptr = 0;
 302         return __tmp;
 303       }
 304
 305       /**
 306        *  @brief  Forcibly deletes the managed object.
 307        *  @param  p  A pointer (defaults to NULL).
 308        *
 309        *  This object now @e owns the object pointed to by @a p.  The
 310        *  previous object has been deleted.
 311        */
 312       void
 313       reset(element_type* __p = 0) throw()
 314       {
 315         if (__p != _M_ptr)
 316           {
 317             delete _M_ptr;
 318             _M_ptr = __p;
 319           }
 320       }
 321
 322       /**
 323        *  @brief  Automatic conversions
 324        *
 325        *  These operations convert an %auto_ptr into and from an auto_ptr_ref
 326        *  automatically as needed.  This allows constructs such as
 327        *  @code
 328        *    auto_ptr<Derived>  func_returning_auto_ptr(.....);
 329        *    ...
 330        *    auto_ptr<Base> ptr = func_returning_auto_ptr(.....);
 331        *  @endcode
 332        */
 333       auto_ptr(auto_ptr_ref<element_type> __ref) throw()
 334       : _M_ptr(__ref._M_ptr) { }
 335
 336       auto_ptr&
 337       operator=(auto_ptr_ref<element_type> __ref) throw()
 338       {
 339         if (__ref._M_ptr != this->get())
 340           {
 341             delete _M_ptr;
 342             _M_ptr = __ref._M_ptr;
 343           }
 344         return *this;
 345       }
 346
 347       template<typename _Tp1>
 348         operator auto_ptr_ref<_Tp1>() throw()
 349         { return auto_ptr_ref<_Tp1>(this->release()); }
 350
 351       template<typename _Tp1>
 352         operator auto_ptr<_Tp1>() throw()
 353         { return auto_ptr<_Tp1>(this->release()); }
 354     };
 355
 356   // _GLIBCXX_RESOLVE_LIB_DEFECTS
 357   // 541. shared_ptr template assignment and void
 358   template<>
 359     class auto_ptr<void>
 360     {
 361     public:
 362       typedef void element_type;
 363     };
 364
 365 _GLIBCXX_END_NAMESPACE
 366
 367 #endif /* _STL_MEMORY_H */