197403Sobrien// <memory> -*- C++ -*- 297403Sobrien 3169691Skan// Copyright (C) 2001, 2002, 2004, 2005 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 18169691Skan// Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, 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 44169691Skan/** @file include/memory 45169691Skan * This is a Standard C++ Library header. 4697403Sobrien */ 4797403Sobrien 48132720Skan#ifndef _GLIBCXX_MEMORY 49132720Skan#define _GLIBCXX_MEMORY 1 5097403Sobrien 5197403Sobrien#pragma GCC system_header 5297403Sobrien 5397403Sobrien#include <bits/stl_algobase.h> 54132720Skan#include <bits/allocator.h> 5597403Sobrien#include <bits/stl_construct.h> 5697403Sobrien#include <bits/stl_iterator_base_types.h> //for iterator_traits 5797403Sobrien#include <bits/stl_uninitialized.h> 5897403Sobrien#include <bits/stl_raw_storage_iter.h> 59132720Skan#include <debug/debug.h> 60146897Skan#include <limits> 6197403Sobrien 62169691Skan_GLIBCXX_BEGIN_NAMESPACE(std) 63169691Skan 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 { 76146897Skan const ptrdiff_t __max = numeric_limits<ptrdiff_t>::max() / sizeof(_Tp); 77146897Skan if (__len > __max) 78146897Skan __len = __max; 79117397Skan 80117397Skan while (__len > 0) 81117397Skan { 82132720Skan _Tp* __tmp = static_cast<_Tp*>(::operator new(__len * sizeof(_Tp), 83132720Skan nothrow)); 84117397Skan if (__tmp != 0) 85117397Skan return pair<_Tp*, ptrdiff_t>(__tmp, __len); 86117397Skan __len /= 2; 87117397Skan } 88132720Skan return pair<_Tp*, ptrdiff_t>(static_cast<_Tp*>(0), 0); 89102782Skan } 90102782Skan 91102782Skan /** 92132720Skan * @brief Allocates a temporary buffer. 93117397Skan * @param len The number of objects of type Tp. 94132720Skan * @return See full description. 95102782Skan * 96117397Skan * Reinventing the wheel, but this time with prettier spokes! 97102782Skan * 98132720Skan * This function tries to obtain storage for @c len adjacent Tp 99132720Skan * objects. The objects themselves are not constructed, of course. 100132720Skan * A pair<> is returned containing "the buffer s address and 101132720Skan * capacity (in the units of sizeof(Tp)), or a pair of 0 values if 102132720Skan * no storage can be obtained." Note that the capacity obtained 103132720Skan * may be less than that requested if the memory is unavailable; 104132720Skan * you should compare len with the .second return value. 105132720Skan * 106132720Skan * Provides the nothrow exception guarantee. 107117397Skan */ 108117397Skan template<typename _Tp> 109146897Skan inline pair<_Tp*, ptrdiff_t> 110117397Skan get_temporary_buffer(ptrdiff_t __len) 111132720Skan { return std::__get_temporary_buffer(__len, static_cast<_Tp*>(0)); } 112102782Skan 113102782Skan /** 114117397Skan * @brief The companion to get_temporary_buffer(). 115117397Skan * @param p A buffer previously allocated by get_temporary_buffer. 116117397Skan * @return None. 117102782Skan * 118117397Skan * Frees the memory pointed to by p. 119117397Skan */ 120117397Skan template<typename _Tp> 121117397Skan void 122117397Skan return_temporary_buffer(_Tp* __p) 123132720Skan { ::operator delete(__p, nothrow); } 12497403Sobrien 125102782Skan /** 126132720Skan * A wrapper class to provide auto_ptr with reference semantics. 127132720Skan * For example, an auto_ptr can be assigned (or constructed from) 128132720Skan * the result of a function which returns an auto_ptr by value. 129102782Skan * 130117397Skan * All the auto_ptr_ref stuff should happen behind the scenes. 131117397Skan */ 132117397Skan template<typename _Tp1> 133117397Skan struct auto_ptr_ref 134117397Skan { 135117397Skan _Tp1* _M_ptr; 136117397Skan 137117397Skan explicit 138117397Skan auto_ptr_ref(_Tp1* __p): _M_ptr(__p) { } 139117397Skan }; 140102782Skan 141102782Skan 142102782Skan /** 143117397Skan * @brief A simple smart pointer providing strict ownership semantics. 144102782Skan * 145117397Skan * The Standard says: 146117397Skan * <pre> 147132720Skan * An @c auto_ptr owns the object it holds a pointer to. Copying 148132720Skan * an @c auto_ptr copies the pointer and transfers ownership to the 149132720Skan * destination. If more than one @c auto_ptr owns the same object 150132720Skan * at the same time the behavior of the program is undefined. 151102782Skan * 152132720Skan * The uses of @c auto_ptr include providing temporary 153132720Skan * exception-safety for dynamically allocated memory, passing 154132720Skan * ownership of dynamically allocated memory to a function, and 155132720Skan * returning dynamically allocated memory from a function. @c 156132720Skan * auto_ptr does not meet the CopyConstructible and Assignable 157132720Skan * requirements for Standard Library <a 158132720Skan * href="tables.html#65">container</a> elements and thus 159132720Skan * instantiating a Standard Library container with an @c auto_ptr 160132720Skan * results in undefined behavior. 161117397Skan * </pre> 162117397Skan * Quoted from [20.4.5]/3. 163102782Skan * 164132720Skan * Good examples of what can and cannot be done with auto_ptr can 165132720Skan * be found in the libstdc++ testsuite. 166102782Skan * 167117397Skan * @if maint 168132720Skan * _GLIBCXX_RESOLVE_LIB_DEFECTS 169117397Skan * 127. auto_ptr<> conversion issues 170117397Skan * These resolutions have all been incorporated. 171117397Skan * @endif 172117397Skan */ 173117397Skan template<typename _Tp> 174117397Skan class auto_ptr 175102782Skan { 176117397Skan private: 177117397Skan _Tp* _M_ptr; 178117397Skan 179117397Skan public: 180117397Skan /// The pointed-to type. 181117397Skan typedef _Tp element_type; 182117397Skan 183117397Skan /** 184117397Skan * @brief An %auto_ptr is usually constructed from a raw pointer. 185117397Skan * @param p A pointer (defaults to NULL). 186117397Skan * 187117397Skan * This object now @e owns the object pointed to by @a p. 188117397Skan */ 189117397Skan explicit 190117397Skan auto_ptr(element_type* __p = 0) throw() : _M_ptr(__p) { } 191102782Skan 192117397Skan /** 193117397Skan * @brief An %auto_ptr can be constructed from another %auto_ptr. 194117397Skan * @param a Another %auto_ptr of the same type. 195117397Skan * 196117397Skan * This object now @e owns the object previously owned by @a a, 197117397Skan * which has given up ownsership. 198117397Skan */ 199117397Skan auto_ptr(auto_ptr& __a) throw() : _M_ptr(__a.release()) { } 200102782Skan 201117397Skan /** 202117397Skan * @brief An %auto_ptr can be constructed from another %auto_ptr. 203117397Skan * @param a Another %auto_ptr of a different but related type. 204117397Skan * 205132720Skan * A pointer-to-Tp1 must be convertible to a 206132720Skan * pointer-to-Tp/element_type. 207117397Skan * 208117397Skan * This object now @e owns the object previously owned by @a a, 209117397Skan * which has given up ownsership. 210117397Skan */ 211117397Skan template<typename _Tp1> 212117397Skan auto_ptr(auto_ptr<_Tp1>& __a) throw() : _M_ptr(__a.release()) { } 21397403Sobrien 214117397Skan /** 215117397Skan * @brief %auto_ptr assignment operator. 216117397Skan * @param a Another %auto_ptr of the same type. 217117397Skan * 218117397Skan * This object now @e owns the object previously owned by @a a, 219117397Skan * which has given up ownsership. The object that this one @e 220117397Skan * used to own and track has been deleted. 221117397Skan */ 222117397Skan auto_ptr& 223117397Skan operator=(auto_ptr& __a) throw() 224117397Skan { 225117397Skan reset(__a.release()); 226117397Skan return *this; 227117397Skan } 228117397Skan 229117397Skan /** 230117397Skan * @brief %auto_ptr assignment operator. 231117397Skan * @param a Another %auto_ptr of a different but related type. 232117397Skan * 233117397Skan * A pointer-to-Tp1 must be convertible to a pointer-to-Tp/element_type. 234117397Skan * 235117397Skan * This object now @e owns the object previously owned by @a a, 236117397Skan * which has given up ownsership. The object that this one @e 237117397Skan * used to own and track has been deleted. 238117397Skan */ 239117397Skan template<typename _Tp1> 240117397Skan auto_ptr& 241117397Skan operator=(auto_ptr<_Tp1>& __a) throw() 242102782Skan { 243117397Skan reset(__a.release()); 244117397Skan return *this; 245117397Skan } 24697403Sobrien 247117397Skan /** 248132720Skan * When the %auto_ptr goes out of scope, the object it owns is 249132720Skan * deleted. If it no longer owns anything (i.e., @c get() is 250132720Skan * @c NULL), then this has no effect. 251117397Skan * 252117397Skan * @if maint 253117397Skan * The C++ standard says there is supposed to be an empty throw 254117397Skan * specification here, but omitting it is standard conforming. Its 255117397Skan * presence can be detected only if _Tp::~_Tp() throws, but this is 256117397Skan * prohibited. [17.4.3.6]/2 257169691Skan * @endif 258117397Skan */ 259117397Skan ~auto_ptr() { delete _M_ptr; } 260117397Skan 261117397Skan /** 262117397Skan * @brief Smart pointer dereferencing. 263117397Skan * 264117397Skan * If this %auto_ptr no longer owns anything, then this 265117397Skan * operation will crash. (For a smart pointer, "no longer owns 266117397Skan * anything" is the same as being a null pointer, and you know 267117397Skan * what happens when you dereference one of those...) 268117397Skan */ 269117397Skan element_type& 270132720Skan operator*() const throw() 271132720Skan { 272132720Skan _GLIBCXX_DEBUG_ASSERT(_M_ptr != 0); 273132720Skan return *_M_ptr; 274132720Skan } 275117397Skan 276117397Skan /** 277117397Skan * @brief Smart pointer dereferencing. 278117397Skan * 279117397Skan * This returns the pointer itself, which the language then will 280117397Skan * automatically cause to be dereferenced. 281117397Skan */ 282117397Skan element_type* 283132720Skan operator->() const throw() 284132720Skan { 285132720Skan _GLIBCXX_DEBUG_ASSERT(_M_ptr != 0); 286132720Skan return _M_ptr; 287132720Skan } 288117397Skan 289117397Skan /** 290117397Skan * @brief Bypassing the smart pointer. 291117397Skan * @return The raw pointer being managed. 292117397Skan * 293117397Skan * You can get a copy of the pointer that this object owns, for 294132720Skan * situations such as passing to a function which only accepts 295132720Skan * a raw pointer. 296117397Skan * 297117397Skan * @note This %auto_ptr still owns the memory. 298117397Skan */ 299117397Skan element_type* 300117397Skan get() const throw() { return _M_ptr; } 301117397Skan 302117397Skan /** 303117397Skan * @brief Bypassing the smart pointer. 304117397Skan * @return The raw pointer being managed. 305117397Skan * 306117397Skan * You can get a copy of the pointer that this object owns, for 307132720Skan * situations such as passing to a function which only accepts 308132720Skan * a raw pointer. 309117397Skan * 310117397Skan * @note This %auto_ptr no longer owns the memory. When this object 311117397Skan * goes out of scope, nothing will happen. 312117397Skan */ 313117397Skan element_type* 314117397Skan release() throw() 315117397Skan { 316117397Skan element_type* __tmp = _M_ptr; 317117397Skan _M_ptr = 0; 318117397Skan return __tmp; 319117397Skan } 320117397Skan 321117397Skan /** 322117397Skan * @brief Forcibly deletes the managed object. 323117397Skan * @param p A pointer (defaults to NULL). 324117397Skan * 325132720Skan * This object now @e owns the object pointed to by @a p. The 326132720Skan * previous object has been deleted. 327117397Skan */ 328117397Skan void 329117397Skan reset(element_type* __p = 0) throw() 330117397Skan { 331117397Skan if (__p != _M_ptr) 332117397Skan { 333117397Skan delete _M_ptr; 334117397Skan _M_ptr = __p; 335117397Skan } 336117397Skan } 337117397Skan 338169691Skan /** 339117397Skan * @brief Automatic conversions 340117397Skan * 341117397Skan * These operations convert an %auto_ptr into and from an auto_ptr_ref 342117397Skan * automatically as needed. This allows constructs such as 343117397Skan * @code 344117397Skan * auto_ptr<Derived> func_returning_auto_ptr(.....); 345117397Skan * ... 346117397Skan * auto_ptr<Base> ptr = func_returning_auto_ptr(.....); 347117397Skan * @endcode 348117397Skan */ 349117397Skan auto_ptr(auto_ptr_ref<element_type> __ref) throw() 350117397Skan : _M_ptr(__ref._M_ptr) { } 351117397Skan 352117397Skan auto_ptr& 353117397Skan operator=(auto_ptr_ref<element_type> __ref) throw() 354117397Skan { 355117397Skan if (__ref._M_ptr != this->get()) 356117397Skan { 357117397Skan delete _M_ptr; 358117397Skan _M_ptr = __ref._M_ptr; 359117397Skan } 360117397Skan return *this; 361117397Skan } 362117397Skan 363117397Skan template<typename _Tp1> 364117397Skan operator auto_ptr_ref<_Tp1>() throw() 365117397Skan { return auto_ptr_ref<_Tp1>(this->release()); } 366102782Skan 367117397Skan template<typename _Tp1> 368117397Skan operator auto_ptr<_Tp1>() throw() 369117397Skan { return auto_ptr<_Tp1>(this->release()); } 370117397Skan }; 37197403Sobrien 372169691Skan_GLIBCXX_END_NAMESPACE 373169691Skan 374132720Skan#endif /* _GLIBCXX_MEMORY */ 375