michael@0: // Copyright (c) 2006-2008 The Chromium Authors. All rights reserved.
michael@0: // Use of this source code is governed by a BSD-style license that can be
michael@0: // found in the LICENSE file.
michael@0: 
michael@0: // Scopers help you manage ownership of a pointer, helping you easily manage the
michael@0: // a pointer within a scope, and automatically destroying the pointer at the
michael@0: // end of a scope.  There are two main classes you will use, which coorespond
michael@0: // to the operators new/delete and new[]/delete[].
michael@0: //
michael@0: // Example usage (scoped_ptr):
michael@0: //   {
michael@0: //     scoped_ptr<Foo> foo(new Foo("wee"));
michael@0: //   }  // foo goes out of scope, releasing the pointer with it.
michael@0: //
michael@0: //   {
michael@0: //     scoped_ptr<Foo> foo;          // No pointer managed.
michael@0: //     foo.reset(new Foo("wee"));    // Now a pointer is managed.
michael@0: //     foo.reset(new Foo("wee2"));   // Foo("wee") was destroyed.
michael@0: //     foo.reset(new Foo("wee3"));   // Foo("wee2") was destroyed.
michael@0: //     foo->Method();                // Foo::Method() called.
michael@0: //     foo.get()->Method();          // Foo::Method() called.
michael@0: //     SomeFunc(foo.Release());      // SomeFunc takes owernship, foo no longer
michael@0: //                                   // manages a pointer.
michael@0: //     foo.reset(new Foo("wee4"));   // foo manages a pointer again.
michael@0: //     foo.reset();                  // Foo("wee4") destroyed, foo no longer
michael@0: //                                   // manages a pointer.
michael@0: //   }  // foo wasn't managing a pointer, so nothing was destroyed.
michael@0: //
michael@0: // Example usage (scoped_array):
michael@0: //   {
michael@0: //     scoped_array<Foo> foo(new Foo[100]);
michael@0: //     foo.get()->Method();  // Foo::Method on the 0th element.
michael@0: //     foo[10].Method();     // Foo::Method on the 10th element.
michael@0: //   }
michael@0: 
michael@0: #ifndef BASE_SCOPED_PTR_H_
michael@0: #define BASE_SCOPED_PTR_H_
michael@0: 
michael@0: // This is an implementation designed to match the anticipated future TR2
michael@0: // implementation of the scoped_ptr class, and its closely-related brethren,
michael@0: // scoped_array, scoped_ptr_malloc.
michael@0: 
michael@0: #include <assert.h>
michael@0: #include <stdlib.h>
michael@0: #include <cstddef>
michael@0: 
michael@0: // A scoped_ptr<T> is like a T*, except that the destructor of scoped_ptr<T>
michael@0: // automatically deletes the pointer it holds (if any).
michael@0: // That is, scoped_ptr<T> owns the T object that it points to.
michael@0: // Like a T*, a scoped_ptr<T> may hold either NULL or a pointer to a T object.
michael@0: // Also like T*, scoped_ptr<T> is thread-compatible, and once you
michael@0: // dereference it, you get the threadsafety guarantees of T.
michael@0: //
michael@0: // The size of a scoped_ptr is small:
michael@0: // sizeof(scoped_ptr<C>) == sizeof(C*)
michael@0: template <class C>
michael@0: class scoped_ptr {
michael@0:  public:
michael@0: 
michael@0:   // The element type
michael@0:   typedef C element_type;
michael@0: 
michael@0:   // Constructor.  Defaults to intializing with NULL.
michael@0:   // There is no way to create an uninitialized scoped_ptr.
michael@0:   // The input parameter must be allocated with new.
michael@0:   explicit scoped_ptr(C* p = NULL) : ptr_(p) { }
michael@0: 
michael@0:   // Destructor.  If there is a C object, delete it.
michael@0:   // We don't need to test ptr_ == NULL because C++ does that for us.
michael@0:   ~scoped_ptr() {
michael@0:     enum { type_must_be_complete = sizeof(C) };
michael@0:     delete ptr_;
michael@0:   }
michael@0: 
michael@0:   // Reset.  Deletes the current owned object, if any.
michael@0:   // Then takes ownership of a new object, if given.
michael@0:   // this->reset(this->get()) works.
michael@0:   void reset(C* p = NULL) {
michael@0:     if (p != ptr_) {
michael@0:       enum { type_must_be_complete = sizeof(C) };
michael@0:       delete ptr_;
michael@0:       ptr_ = p;
michael@0:     }
michael@0:   }
michael@0: 
michael@0:   // Accessors to get the owned object.
michael@0:   // operator* and operator-> will assert() if there is no current object.
michael@0:   C& operator*() const {
michael@0:     assert(ptr_ != NULL);
michael@0:     return *ptr_;
michael@0:   }
michael@0:   C* operator->() const  {
michael@0:     assert(ptr_ != NULL);
michael@0:     return ptr_;
michael@0:   }
michael@0:   C* get() const { return ptr_; }
michael@0: 
michael@0:   // Comparison operators.
michael@0:   // These return whether two scoped_ptr refer to the same object, not just to
michael@0:   // two different but equal objects.
michael@0:   bool operator==(C* p) const { return ptr_ == p; }
michael@0:   bool operator!=(C* p) const { return ptr_ != p; }
michael@0: 
michael@0:   // Swap two scoped pointers.
michael@0:   void swap(scoped_ptr& p2) {
michael@0:     C* tmp = ptr_;
michael@0:     ptr_ = p2.ptr_;
michael@0:     p2.ptr_ = tmp;
michael@0:   }
michael@0: 
michael@0:   // Release a pointer.
michael@0:   // The return value is the current pointer held by this object.
michael@0:   // If this object holds a NULL pointer, the return value is NULL.
michael@0:   // After this operation, this object will hold a NULL pointer,
michael@0:   // and will not own the object any more.
michael@0:   C* release() {
michael@0:     C* retVal = ptr_;
michael@0:     ptr_ = NULL;
michael@0:     return retVal;
michael@0:   }
michael@0: 
michael@0:  private:
michael@0:   C* ptr_;
michael@0: 
michael@0:   // Forbid comparison of scoped_ptr types.  If C2 != C, it totally doesn't
michael@0:   // make sense, and if C2 == C, it still doesn't make sense because you should
michael@0:   // never have the same object owned by two different scoped_ptrs.
michael@0:   template <class C2> bool operator==(scoped_ptr<C2> const& p2) const;
michael@0:   template <class C2> bool operator!=(scoped_ptr<C2> const& p2) const;
michael@0: 
michael@0:   // Disallow evil constructors
michael@0:   scoped_ptr(const scoped_ptr&);
michael@0:   void operator=(const scoped_ptr&);
michael@0: };
michael@0: 
michael@0: // Free functions
michael@0: template <class C>
michael@0: void swap(scoped_ptr<C>& p1, scoped_ptr<C>& p2) {
michael@0:   p1.swap(p2);
michael@0: }
michael@0: 
michael@0: template <class C>
michael@0: bool operator==(C* p1, const scoped_ptr<C>& p2) {
michael@0:   return p1 == p2.get();
michael@0: }
michael@0: 
michael@0: template <class C>
michael@0: bool operator!=(C* p1, const scoped_ptr<C>& p2) {
michael@0:   return p1 != p2.get();
michael@0: }
michael@0: 
michael@0: // scoped_array<C> is like scoped_ptr<C>, except that the caller must allocate
michael@0: // with new [] and the destructor deletes objects with delete [].
michael@0: //
michael@0: // As with scoped_ptr<C>, a scoped_array<C> either points to an object
michael@0: // or is NULL.  A scoped_array<C> owns the object that it points to.
michael@0: // scoped_array<T> is thread-compatible, and once you index into it,
michael@0: // the returned objects have only the threadsafety guarantees of T.
michael@0: //
michael@0: // Size: sizeof(scoped_array<C>) == sizeof(C*)
michael@0: template <class C>
michael@0: class scoped_array {
michael@0:  public:
michael@0: 
michael@0:   // The element type
michael@0:   typedef C element_type;
michael@0: 
michael@0:   // Constructor.  Defaults to intializing with NULL.
michael@0:   // There is no way to create an uninitialized scoped_array.
michael@0:   // The input parameter must be allocated with new [].
michael@0:   explicit scoped_array(C* p = NULL) : array_(p) { }
michael@0: 
michael@0:   // Destructor.  If there is a C object, delete it.
michael@0:   // We don't need to test ptr_ == NULL because C++ does that for us.
michael@0:   ~scoped_array() {
michael@0:     enum { type_must_be_complete = sizeof(C) };
michael@0:     delete[] array_;
michael@0:   }
michael@0: 
michael@0:   // Reset.  Deletes the current owned object, if any.
michael@0:   // Then takes ownership of a new object, if given.
michael@0:   // this->reset(this->get()) works.
michael@0:   void reset(C* p = NULL) {
michael@0:     if (p != array_) {
michael@0:       enum { type_must_be_complete = sizeof(C) };
michael@0:       delete[] array_;
michael@0:       array_ = p;
michael@0:     }
michael@0:   }
michael@0: 
michael@0:   // Get one element of the current object.
michael@0:   // Will assert() if there is no current object, or index i is negative.
michael@0:   C& operator[](std::ptrdiff_t i) const {
michael@0:     assert(i >= 0);
michael@0:     assert(array_ != NULL);
michael@0:     return array_[i];
michael@0:   }
michael@0: 
michael@0:   // Get a pointer to the zeroth element of the current object.
michael@0:   // If there is no current object, return NULL.
michael@0:   C* get() const {
michael@0:     return array_;
michael@0:   }
michael@0: 
michael@0:   // Comparison operators.
michael@0:   // These return whether two scoped_array refer to the same object, not just to
michael@0:   // two different but equal objects.
michael@0:   bool operator==(C* p) const { return array_ == p; }
michael@0:   bool operator!=(C* p) const { return array_ != p; }
michael@0: 
michael@0:   // Swap two scoped arrays.
michael@0:   void swap(scoped_array& p2) {
michael@0:     C* tmp = array_;
michael@0:     array_ = p2.array_;
michael@0:     p2.array_ = tmp;
michael@0:   }
michael@0: 
michael@0:   // Release an array.
michael@0:   // The return value is the current pointer held by this object.
michael@0:   // If this object holds a NULL pointer, the return value is NULL.
michael@0:   // After this operation, this object will hold a NULL pointer,
michael@0:   // and will not own the object any more.
michael@0:   C* release() {
michael@0:     C* retVal = array_;
michael@0:     array_ = NULL;
michael@0:     return retVal;
michael@0:   }
michael@0: 
michael@0:  private:
michael@0:   C* array_;
michael@0: 
michael@0:   // Forbid comparison of different scoped_array types.
michael@0:   template <class C2> bool operator==(scoped_array<C2> const& p2) const;
michael@0:   template <class C2> bool operator!=(scoped_array<C2> const& p2) const;
michael@0: 
michael@0:   // Disallow evil constructors
michael@0:   scoped_array(const scoped_array&);
michael@0:   void operator=(const scoped_array&);
michael@0: };
michael@0: 
michael@0: // Free functions
michael@0: template <class C>
michael@0: void swap(scoped_array<C>& p1, scoped_array<C>& p2) {
michael@0:   p1.swap(p2);
michael@0: }
michael@0: 
michael@0: template <class C>
michael@0: bool operator==(C* p1, const scoped_array<C>& p2) {
michael@0:   return p1 == p2.get();
michael@0: }
michael@0: 
michael@0: template <class C>
michael@0: bool operator!=(C* p1, const scoped_array<C>& p2) {
michael@0:   return p1 != p2.get();
michael@0: }
michael@0: 
michael@0: // This class wraps the c library function free() in a class that can be
michael@0: // passed as a template argument to scoped_ptr_malloc below.
michael@0: class ScopedPtrMallocFree {
michael@0:  public:
michael@0:   inline void operator()(void* x) const {
michael@0:     free(x);
michael@0:   }
michael@0: };
michael@0: 
michael@0: // scoped_ptr_malloc<> is similar to scoped_ptr<>, but it accepts a
michael@0: // second template argument, the functor used to free the object.
michael@0: 
michael@0: template<class C, class FreeProc = ScopedPtrMallocFree>
michael@0: class scoped_ptr_malloc {
michael@0:  public:
michael@0: 
michael@0:   // The element type
michael@0:   typedef C element_type;
michael@0: 
michael@0:   // Constructor.  Defaults to intializing with NULL.
michael@0:   // There is no way to create an uninitialized scoped_ptr.
michael@0:   // The input parameter must be allocated with an allocator that matches the
michael@0:   // Free functor.  For the default Free functor, this is malloc, calloc, or
michael@0:   // realloc.
michael@0:   explicit scoped_ptr_malloc(C* p = NULL): ptr_(p) {}
michael@0: 
michael@0:   // Destructor.  If there is a C object, call the Free functor.
michael@0:   ~scoped_ptr_malloc() {
michael@0:     free_(ptr_);
michael@0:   }
michael@0: 
michael@0:   // Reset.  Calls the Free functor on the current owned object, if any.
michael@0:   // Then takes ownership of a new object, if given.
michael@0:   // this->reset(this->get()) works.
michael@0:   void reset(C* p = NULL) {
michael@0:     if (ptr_ != p) {
michael@0:       free_(ptr_);
michael@0:       ptr_ = p;
michael@0:     }
michael@0:   }
michael@0: 
michael@0:   // Get the current object.
michael@0:   // operator* and operator-> will cause an assert() failure if there is
michael@0:   // no current object.
michael@0:   C& operator*() const {
michael@0:     assert(ptr_ != NULL);
michael@0:     return *ptr_;
michael@0:   }
michael@0: 
michael@0:   C* operator->() const {
michael@0:     assert(ptr_ != NULL);
michael@0:     return ptr_;
michael@0:   }
michael@0: 
michael@0:   C* get() const {
michael@0:     return ptr_;
michael@0:   }
michael@0: 
michael@0:   // Comparison operators.
michael@0:   // These return whether a scoped_ptr_malloc and a plain pointer refer
michael@0:   // to the same object, not just to two different but equal objects.
michael@0:   // For compatibility wwith the boost-derived implementation, these
michael@0:   // take non-const arguments.
michael@0:   bool operator==(C* p) const {
michael@0:     return ptr_ == p;
michael@0:   }
michael@0: 
michael@0:   bool operator!=(C* p) const {
michael@0:     return ptr_ != p;
michael@0:   }
michael@0: 
michael@0:   // Swap two scoped pointers.
michael@0:   void swap(scoped_ptr_malloc & b) {
michael@0:     C* tmp = b.ptr_;
michael@0:     b.ptr_ = ptr_;
michael@0:     ptr_ = tmp;
michael@0:   }
michael@0: 
michael@0:   // Release a pointer.
michael@0:   // The return value is the current pointer held by this object.
michael@0:   // If this object holds a NULL pointer, the return value is NULL.
michael@0:   // After this operation, this object will hold a NULL pointer,
michael@0:   // and will not own the object any more.
michael@0:   C* release() {
michael@0:     C* tmp = ptr_;
michael@0:     ptr_ = NULL;
michael@0:     return tmp;
michael@0:   }
michael@0: 
michael@0:  private:
michael@0:   C* ptr_;
michael@0: 
michael@0:   // no reason to use these: each scoped_ptr_malloc should have its own object
michael@0:   template <class C2, class GP>
michael@0:   bool operator==(scoped_ptr_malloc<C2, GP> const& p) const;
michael@0:   template <class C2, class GP>
michael@0:   bool operator!=(scoped_ptr_malloc<C2, GP> const& p) const;
michael@0: 
michael@0:   static FreeProc const free_;
michael@0: 
michael@0:   // Disallow evil constructors
michael@0:   scoped_ptr_malloc(const scoped_ptr_malloc&);
michael@0:   void operator=(const scoped_ptr_malloc&);
michael@0: };
michael@0: 
michael@0: template<class C, class FP>
michael@0: FP const scoped_ptr_malloc<C, FP>::free_ = FP();
michael@0: 
michael@0: template<class C, class FP> inline
michael@0: void swap(scoped_ptr_malloc<C, FP>& a, scoped_ptr_malloc<C, FP>& b) {
michael@0:   a.swap(b);
michael@0: }
michael@0: 
michael@0: template<class C, class FP> inline
michael@0: bool operator==(C* p, const scoped_ptr_malloc<C, FP>& b) {
michael@0:   return p == b.get();
michael@0: }
michael@0: 
michael@0: template<class C, class FP> inline
michael@0: bool operator!=(C* p, const scoped_ptr_malloc<C, FP>& b) {
michael@0:   return p != b.get();
michael@0: }
michael@0: 
michael@0: #endif  // BASE_SCOPED_PTR_H_