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