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