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