std_memory.h revision 132720
197403Sobrien// <memory> -*- C++ -*- 297403Sobrien 3132720Skan// Copyright (C) 2001, 2002, 2004 Free Software Foundation, Inc. 497403Sobrien// 597403Sobrien// This file is part of the GNU ISO C++ Library. This library is free 697403Sobrien// software; you can redistribute it and/or modify it under the 797403Sobrien// terms of the GNU General Public License as published by the 897403Sobrien// Free Software Foundation; either version 2, or (at your option) 997403Sobrien// any later version. 1097403Sobrien 1197403Sobrien// This library is distributed in the hope that it will be useful, 1297403Sobrien// but WITHOUT ANY WARRANTY; without even the implied warranty of 1397403Sobrien// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 1497403Sobrien// GNU General Public License for more details. 1597403Sobrien 1697403Sobrien// You should have received a copy of the GNU General Public License along 1797403Sobrien// with this library; see the file COPYING. If not, write to the Free 1897403Sobrien// Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, 1997403Sobrien// USA. 2097403Sobrien 2197403Sobrien// As a special exception, you may use this file as part of a free software 2297403Sobrien// library without restriction. Specifically, if other files instantiate 2397403Sobrien// templates or use macros or inline functions from this file, or you compile 2497403Sobrien// this file and link it with other files to produce an executable, this 2597403Sobrien// file does not by itself cause the resulting executable to be covered by 2697403Sobrien// the GNU General Public License. This exception does not however 2797403Sobrien// invalidate any other reasons why the executable file might be covered by 2897403Sobrien// the GNU General Public License. 2997403Sobrien 3097403Sobrien/* 3197403Sobrien * Copyright (c) 1997-1999 3297403Sobrien * Silicon Graphics Computer Systems, Inc. 3397403Sobrien * 3497403Sobrien * Permission to use, copy, modify, distribute and sell this software 3597403Sobrien * and its documentation for any purpose is hereby granted without fee, 3697403Sobrien * provided that the above copyright notice appear in all copies and 3797403Sobrien * that both that copyright notice and this permission notice appear 3897403Sobrien * in supporting documentation. Silicon Graphics makes no 3997403Sobrien * representations about the suitability of this software for any 4097403Sobrien * purpose. It is provided "as is" without express or implied warranty. 4197403Sobrien * 4297403Sobrien */ 4397403Sobrien 4497403Sobrien/** @file memory 4597403Sobrien * This is a Standard C++ Library header. You should @c #include this header 4697403Sobrien * in your programs, rather than any of the "st[dl]_*.h" implementation files. 4797403Sobrien */ 4897403Sobrien 49132720Skan#ifndef _GLIBCXX_MEMORY 50132720Skan#define _GLIBCXX_MEMORY 1 5197403Sobrien 5297403Sobrien#pragma GCC system_header 5397403Sobrien 5497403Sobrien#include <bits/stl_algobase.h> 55132720Skan#include <bits/allocator.h> 5697403Sobrien#include <bits/stl_construct.h> 5797403Sobrien#include <bits/stl_iterator_base_types.h> //for iterator_traits 5897403Sobrien#include <bits/stl_uninitialized.h> 5997403Sobrien#include <bits/stl_raw_storage_iter.h> 60132720Skan#include <debug/debug.h> 6197403Sobrien 6297403Sobriennamespace std 6397403Sobrien{ 64102782Skan /** 65117397Skan * @if maint 66117397Skan * This is a helper function. The unused second parameter exists to 67117397Skan * permit the real get_temporary_buffer to use template parameter deduction. 68102782Skan * 69117397Skan * XXX This should perhaps use the pool. 70117397Skan * @endif 71117397Skan */ 72117397Skan template<typename _Tp> 73117397Skan pair<_Tp*, ptrdiff_t> 74117397Skan __get_temporary_buffer(ptrdiff_t __len, _Tp*) 75102782Skan { 76117397Skan if (__len > ptrdiff_t(INT_MAX / sizeof(_Tp))) 77117397Skan __len = INT_MAX / sizeof(_Tp); 78117397Skan 79117397Skan while (__len > 0) 80117397Skan { 81132720Skan _Tp* __tmp = static_cast<_Tp*>(::operator new(__len * sizeof(_Tp), 82132720Skan nothrow)); 83117397Skan if (__tmp != 0) 84117397Skan return pair<_Tp*, ptrdiff_t>(__tmp, __len); 85117397Skan __len /= 2; 86117397Skan } 87132720Skan return pair<_Tp*, ptrdiff_t>(static_cast<_Tp*>(0), 0); 88102782Skan } 89102782Skan 90102782Skan /** 91132720Skan * @brief Allocates a temporary buffer. 92117397Skan * @param len The number of objects of type Tp. 93132720Skan * @return See full description. 94102782Skan * 95117397Skan * Reinventing the wheel, but this time with prettier spokes! 96102782Skan * 97132720Skan * This function tries to obtain storage for @c len adjacent Tp 98132720Skan * objects. The objects themselves are not constructed, of course. 99132720Skan * A pair<> is returned containing "the buffer s address and 100132720Skan * capacity (in the units of sizeof(Tp)), or a pair of 0 values if 101132720Skan * no storage can be obtained." Note that the capacity obtained 102132720Skan * may be less than that requested if the memory is unavailable; 103132720Skan * you should compare len with the .second return value. 104132720Skan * 105132720Skan * Provides the nothrow exception guarantee. 106117397Skan */ 107117397Skan template<typename _Tp> 108117397Skan inline pair<_Tp*,ptrdiff_t> 109117397Skan get_temporary_buffer(ptrdiff_t __len) 110132720Skan { return std::__get_temporary_buffer(__len, static_cast<_Tp*>(0)); } 111102782Skan 112102782Skan /** 113117397Skan * @brief The companion to get_temporary_buffer(). 114117397Skan * @param p A buffer previously allocated by get_temporary_buffer. 115117397Skan * @return None. 116102782Skan * 117117397Skan * Frees the memory pointed to by p. 118117397Skan */ 119117397Skan template<typename _Tp> 120117397Skan void 121117397Skan return_temporary_buffer(_Tp* __p) 122132720Skan { ::operator delete(__p, nothrow); } 12397403Sobrien 124102782Skan /** 125132720Skan * A wrapper class to provide auto_ptr with reference semantics. 126132720Skan * For example, an auto_ptr can be assigned (or constructed from) 127132720Skan * the result of a function which returns an auto_ptr by value. 128102782Skan * 129117397Skan * All the auto_ptr_ref stuff should happen behind the scenes. 130117397Skan */ 131117397Skan template<typename _Tp1> 132117397Skan struct auto_ptr_ref 133117397Skan { 134117397Skan _Tp1* _M_ptr; 135117397Skan 136117397Skan explicit 137117397Skan auto_ptr_ref(_Tp1* __p): _M_ptr(__p) { } 138117397Skan }; 139102782Skan 140102782Skan 141102782Skan /** 142117397Skan * @brief A simple smart pointer providing strict ownership semantics. 143102782Skan * 144117397Skan * The Standard says: 145117397Skan * <pre> 146132720Skan * An @c auto_ptr owns the object it holds a pointer to. Copying 147132720Skan * an @c auto_ptr copies the pointer and transfers ownership to the 148132720Skan * destination. If more than one @c auto_ptr owns the same object 149132720Skan * at the same time the behavior of the program is undefined. 150102782Skan * 151132720Skan * The uses of @c auto_ptr include providing temporary 152132720Skan * exception-safety for dynamically allocated memory, passing 153132720Skan * ownership of dynamically allocated memory to a function, and 154132720Skan * returning dynamically allocated memory from a function. @c 155132720Skan * auto_ptr does not meet the CopyConstructible and Assignable 156132720Skan * requirements for Standard Library <a 157132720Skan * href="tables.html#65">container</a> elements and thus 158132720Skan * instantiating a Standard Library container with an @c auto_ptr 159132720Skan * results in undefined behavior. 160117397Skan * </pre> 161117397Skan * Quoted from [20.4.5]/3. 162102782Skan * 163132720Skan * Good examples of what can and cannot be done with auto_ptr can 164132720Skan * be found in the libstdc++ testsuite. 165102782Skan * 166117397Skan * @if maint 167132720Skan * _GLIBCXX_RESOLVE_LIB_DEFECTS 168117397Skan * 127. auto_ptr<> conversion issues 169117397Skan * These resolutions have all been incorporated. 170117397Skan * @endif 171117397Skan */ 172117397Skan template<typename _Tp> 173117397Skan class auto_ptr 174102782Skan { 175117397Skan private: 176117397Skan _Tp* _M_ptr; 177117397Skan 178117397Skan public: 179117397Skan /// The pointed-to type. 180117397Skan typedef _Tp element_type; 181117397Skan 182117397Skan /** 183117397Skan * @brief An %auto_ptr is usually constructed from a raw pointer. 184117397Skan * @param p A pointer (defaults to NULL). 185117397Skan * 186117397Skan * This object now @e owns the object pointed to by @a p. 187117397Skan */ 188117397Skan explicit 189117397Skan auto_ptr(element_type* __p = 0) throw() : _M_ptr(__p) { } 190102782Skan 191117397Skan /** 192117397Skan * @brief An %auto_ptr can be constructed from another %auto_ptr. 193117397Skan * @param a Another %auto_ptr of the same type. 194117397Skan * 195117397Skan * This object now @e owns the object previously owned by @a a, 196117397Skan * which has given up ownsership. 197117397Skan */ 198117397Skan auto_ptr(auto_ptr& __a) throw() : _M_ptr(__a.release()) { } 199102782Skan 200117397Skan /** 201117397Skan * @brief An %auto_ptr can be constructed from another %auto_ptr. 202117397Skan * @param a Another %auto_ptr of a different but related type. 203117397Skan * 204132720Skan * A pointer-to-Tp1 must be convertible to a 205132720Skan * pointer-to-Tp/element_type. 206117397Skan * 207117397Skan * This object now @e owns the object previously owned by @a a, 208117397Skan * which has given up ownsership. 209117397Skan */ 210117397Skan template<typename _Tp1> 211117397Skan auto_ptr(auto_ptr<_Tp1>& __a) throw() : _M_ptr(__a.release()) { } 21297403Sobrien 213117397Skan /** 214117397Skan * @brief %auto_ptr assignment operator. 215117397Skan * @param a Another %auto_ptr of the same type. 216117397Skan * 217117397Skan * This object now @e owns the object previously owned by @a a, 218117397Skan * which has given up ownsership. The object that this one @e 219117397Skan * used to own and track has been deleted. 220117397Skan */ 221117397Skan auto_ptr& 222117397Skan operator=(auto_ptr& __a) throw() 223117397Skan { 224117397Skan reset(__a.release()); 225117397Skan return *this; 226117397Skan } 227117397Skan 228117397Skan /** 229117397Skan * @brief %auto_ptr assignment operator. 230117397Skan * @param a Another %auto_ptr of a different but related type. 231117397Skan * 232117397Skan * A pointer-to-Tp1 must be convertible to a pointer-to-Tp/element_type. 233117397Skan * 234117397Skan * This object now @e owns the object previously owned by @a a, 235117397Skan * which has given up ownsership. The object that this one @e 236117397Skan * used to own and track has been deleted. 237117397Skan */ 238117397Skan template<typename _Tp1> 239117397Skan auto_ptr& 240117397Skan operator=(auto_ptr<_Tp1>& __a) throw() 241102782Skan { 242117397Skan reset(__a.release()); 243117397Skan return *this; 244117397Skan } 24597403Sobrien 246117397Skan /** 247132720Skan * When the %auto_ptr goes out of scope, the object it owns is 248132720Skan * deleted. If it no longer owns anything (i.e., @c get() is 249132720Skan * @c NULL), then this has no effect. 250117397Skan * 251117397Skan * @if maint 252117397Skan * The C++ standard says there is supposed to be an empty throw 253117397Skan * specification here, but omitting it is standard conforming. Its 254117397Skan * presence can be detected only if _Tp::~_Tp() throws, but this is 255117397Skan * prohibited. [17.4.3.6]/2 256117397Skan * @end maint 257117397Skan */ 258117397Skan ~auto_ptr() { delete _M_ptr; } 259117397Skan 260117397Skan /** 261117397Skan * @brief Smart pointer dereferencing. 262117397Skan * 263117397Skan * If this %auto_ptr no longer owns anything, then this 264117397Skan * operation will crash. (For a smart pointer, "no longer owns 265117397Skan * anything" is the same as being a null pointer, and you know 266117397Skan * what happens when you dereference one of those...) 267117397Skan */ 268117397Skan element_type& 269132720Skan operator*() const throw() 270132720Skan { 271132720Skan _GLIBCXX_DEBUG_ASSERT(_M_ptr != 0); 272132720Skan return *_M_ptr; 273132720Skan } 274117397Skan 275117397Skan /** 276117397Skan * @brief Smart pointer dereferencing. 277117397Skan * 278117397Skan * This returns the pointer itself, which the language then will 279117397Skan * automatically cause to be dereferenced. 280117397Skan */ 281117397Skan element_type* 282132720Skan operator->() const throw() 283132720Skan { 284132720Skan _GLIBCXX_DEBUG_ASSERT(_M_ptr != 0); 285132720Skan return _M_ptr; 286132720Skan } 287117397Skan 288117397Skan /** 289117397Skan * @brief Bypassing the smart pointer. 290117397Skan * @return The raw pointer being managed. 291117397Skan * 292117397Skan * You can get a copy of the pointer that this object owns, for 293132720Skan * situations such as passing to a function which only accepts 294132720Skan * a raw pointer. 295117397Skan * 296117397Skan * @note This %auto_ptr still owns the memory. 297117397Skan */ 298117397Skan element_type* 299117397Skan get() const throw() { return _M_ptr; } 300117397Skan 301117397Skan /** 302117397Skan * @brief Bypassing the smart pointer. 303117397Skan * @return The raw pointer being managed. 304117397Skan * 305117397Skan * You can get a copy of the pointer that this object owns, for 306132720Skan * situations such as passing to a function which only accepts 307132720Skan * a raw pointer. 308117397Skan * 309117397Skan * @note This %auto_ptr no longer owns the memory. When this object 310117397Skan * goes out of scope, nothing will happen. 311117397Skan */ 312117397Skan element_type* 313117397Skan release() throw() 314117397Skan { 315117397Skan element_type* __tmp = _M_ptr; 316117397Skan _M_ptr = 0; 317117397Skan return __tmp; 318117397Skan } 319117397Skan 320117397Skan /** 321117397Skan * @brief Forcibly deletes the managed object. 322117397Skan * @param p A pointer (defaults to NULL). 323117397Skan * 324132720Skan * This object now @e owns the object pointed to by @a p. The 325132720Skan * previous object has been deleted. 326117397Skan */ 327117397Skan void 328117397Skan reset(element_type* __p = 0) throw() 329117397Skan { 330117397Skan if (__p != _M_ptr) 331117397Skan { 332117397Skan delete _M_ptr; 333117397Skan _M_ptr = __p; 334117397Skan } 335117397Skan } 336117397Skan 337117397Skan /** @{ 338117397Skan * @brief Automatic conversions 339117397Skan * 340117397Skan * These operations convert an %auto_ptr into and from an auto_ptr_ref 341117397Skan * automatically as needed. This allows constructs such as 342117397Skan * @code 343117397Skan * auto_ptr<Derived> func_returning_auto_ptr(.....); 344117397Skan * ... 345117397Skan * auto_ptr<Base> ptr = func_returning_auto_ptr(.....); 346117397Skan * @endcode 347117397Skan */ 348117397Skan auto_ptr(auto_ptr_ref<element_type> __ref) throw() 349117397Skan : _M_ptr(__ref._M_ptr) { } 350117397Skan 351117397Skan auto_ptr& 352117397Skan operator=(auto_ptr_ref<element_type> __ref) throw() 353117397Skan { 354117397Skan if (__ref._M_ptr != this->get()) 355117397Skan { 356117397Skan delete _M_ptr; 357117397Skan _M_ptr = __ref._M_ptr; 358117397Skan } 359117397Skan return *this; 360117397Skan } 361117397Skan 362117397Skan template<typename _Tp1> 363117397Skan operator auto_ptr_ref<_Tp1>() throw() 364117397Skan { return auto_ptr_ref<_Tp1>(this->release()); } 365102782Skan 366117397Skan template<typename _Tp1> 367117397Skan operator auto_ptr<_Tp1>() throw() 368117397Skan { return auto_ptr<_Tp1>(this->release()); } 369117397Skan /** @} */ 370117397Skan }; 37197403Sobrien} // namespace std 37297403Sobrien 373132720Skan#endif /* _GLIBCXX_MEMORY */ 374