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