/* * Copyright (c) 2013 The WebRTC project authors. All Rights Reserved. * * Use of this source code is governed by a BSD-style license * that can be found in the LICENSE file in the root of the source * tree. An additional intellectual property rights grant can be found * in the file PATENTS. All contributing project authors may * be found in the AUTHORS file in the root of the source tree. */ // Borrowed from Chromium's src/base/memory/scoped_ptr.h. // Scopers help you manage ownership of a pointer, helping you easily manage the // a pointer within a scope, and automatically destroying the pointer at the // end of a scope. There are two main classes you will use, which correspond // to the operators new/delete and new[]/delete[]. // // Example usage (scoped_ptr): // { // scoped_ptr foo(new Foo("wee")); // } // foo goes out of scope, releasing the pointer with it. // // { // scoped_ptr foo; // No pointer managed. // foo.reset(new Foo("wee")); // Now a pointer is managed. // foo.reset(new Foo("wee2")); // Foo("wee") was destroyed. // foo.reset(new Foo("wee3")); // Foo("wee2") was destroyed. // foo->Method(); // Foo::Method() called. // foo.get()->Method(); // Foo::Method() called. // SomeFunc(foo.release()); // SomeFunc takes ownership, foo no longer // // manages a pointer. // foo.reset(new Foo("wee4")); // foo manages a pointer again. // foo.reset(); // Foo("wee4") destroyed, foo no longer // // manages a pointer. // } // foo wasn't managing a pointer, so nothing was destroyed. // // Example usage (scoped_ptr): // { // scoped_ptr foo(new Foo[100]); // foo.get()->Method(); // Foo::Method on the 0th element. // foo[10].Method(); // Foo::Method on the 10th element. // } // // These scopers also implement part of the functionality of C++11 unique_ptr // in that they are "movable but not copyable." You can use the scopers in // the parameter and return types of functions to signify ownership transfer // in to and out of a function. When calling a function that has a scoper // as the argument type, it must be called with the result of an analogous // scoper's Pass() function or another function that generates a temporary; // passing by copy will NOT work. Here is an example using scoped_ptr: // // void TakesOwnership(scoped_ptr arg) { // // Do something with arg // } // scoped_ptr CreateFoo() { // // No need for calling Pass() because we are constructing a temporary // // for the return value. // return scoped_ptr(new Foo("new")); // } // scoped_ptr PassThru(scoped_ptr arg) { // return arg.Pass(); // } // // { // scoped_ptr ptr(new Foo("yay")); // ptr manages Foo("yay"). // TakesOwnership(ptr.Pass()); // ptr no longer owns Foo("yay"). // scoped_ptr ptr2 = CreateFoo(); // ptr2 owns the return Foo. // scoped_ptr ptr3 = // ptr3 now owns what was in ptr2. // PassThru(ptr2.Pass()); // ptr2 is correspondingly NULL. // } // // Notice that if you do not call Pass() when returning from PassThru(), or // when invoking TakesOwnership(), the code will not compile because scopers // are not copyable; they only implement move semantics which require calling // the Pass() function to signify a destructive transfer of state. CreateFoo() // is different though because we are constructing a temporary on the return // line and thus can avoid needing to call Pass(). // // Pass() properly handles upcast in initialization, i.e. you can use a // scoped_ptr to initialize a scoped_ptr: // // scoped_ptr foo(new Foo()); // scoped_ptr parent(foo.Pass()); // // PassAs<>() should be used to upcast return value in return statement: // // scoped_ptr CreateFoo() { // scoped_ptr result(new FooChild()); // return result.PassAs(); // } // // Note that PassAs<>() is implemented only for scoped_ptr, but not for // scoped_ptr. This is because casting array pointers may not be safe. #ifndef WEBRTC_SYSTEM_WRAPPERS_INTERFACE_SCOPED_PTR_H_ #define WEBRTC_SYSTEM_WRAPPERS_INTERFACE_SCOPED_PTR_H_ // This is an implementation designed to match the anticipated future TR2 // implementation of the scoped_ptr class and scoped_ptr_malloc (deprecated). #include #include #include #include // For std::swap(). #include "webrtc/system_wrappers/interface/compile_assert.h" #include "webrtc/system_wrappers/interface/constructor_magic.h" #include "webrtc/system_wrappers/interface/template_util.h" #include "webrtc/system_wrappers/source/move.h" #include "webrtc/typedefs.h" namespace webrtc { // Function object which deletes its parameter, which must be a pointer. // If C is an array type, invokes 'delete[]' on the parameter; otherwise, // invokes 'delete'. The default deleter for scoped_ptr. template struct DefaultDeleter { DefaultDeleter() {} template DefaultDeleter(const DefaultDeleter& other) { // IMPLEMENTATION NOTE: C++11 20.7.1.1.2p2 only provides this constructor // if U* is implicitly convertible to T* and U is not an array type. // // Correct implementation should use SFINAE to disable this // constructor. However, since there are no other 1-argument constructors, // using a COMPILE_ASSERT() based on is_convertible<> and requiring // complete types is simpler and will cause compile failures for equivalent // misuses. // // Note, the is_convertible check also ensures that U is not an // array. T is guaranteed to be a non-array, so any U* where U is an array // cannot convert to T*. enum { T_must_be_complete = sizeof(T) }; enum { U_must_be_complete = sizeof(U) }; COMPILE_ASSERT((webrtc::is_convertible::value), U_ptr_must_implicitly_convert_to_T_ptr); } inline void operator()(T* ptr) const { enum { type_must_be_complete = sizeof(T) }; delete ptr; } }; // Specialization of DefaultDeleter for array types. template struct DefaultDeleter { inline void operator()(T* ptr) const { enum { type_must_be_complete = sizeof(T) }; delete[] ptr; } private: // Disable this operator for any U != T because it is undefined to execute // an array delete when the static type of the array mismatches the dynamic // type. // // References: // C++98 [expr.delete]p3 // http://cplusplus.github.com/LWG/lwg-defects.html#938 template void operator()(U* array) const; }; template struct DefaultDeleter { // Never allow someone to declare something like scoped_ptr. COMPILE_ASSERT(sizeof(T) == -1, do_not_use_array_with_size_as_type); }; // Function object which invokes 'free' on its parameter, which must be // a pointer. Can be used to store malloc-allocated pointers in scoped_ptr: // // scoped_ptr foo_ptr( // static_cast(malloc(sizeof(int)))); struct FreeDeleter { inline void operator()(void* ptr) const { free(ptr); } }; namespace internal { // Minimal implementation of the core logic of scoped_ptr, suitable for // reuse in both scoped_ptr and its specializations. template class scoped_ptr_impl { public: explicit scoped_ptr_impl(T* p) : data_(p) { } // Initializer for deleters that have data parameters. scoped_ptr_impl(T* p, const D& d) : data_(p, d) {} // Templated constructor that destructively takes the value from another // scoped_ptr_impl. template scoped_ptr_impl(scoped_ptr_impl* other) : data_(other->release(), other->get_deleter()) { // We do not support move-only deleters. We could modify our move // emulation to have webrtc::subtle::move() and webrtc::subtle::forward() // functions that are imperfect emulations of their C++11 equivalents, // but until there's a requirement, just assume deleters are copyable. } template void TakeState(scoped_ptr_impl* other) { // See comment in templated constructor above regarding lack of support // for move-only deleters. reset(other->release()); get_deleter() = other->get_deleter(); } ~scoped_ptr_impl() { if (data_.ptr != NULL) { // Not using get_deleter() saves one function call in non-optimized // builds. static_cast(data_)(data_.ptr); } } void reset(T* p) { // This is a self-reset, which is no longer allowed: http://crbug.com/162971 if (p != NULL && p == data_.ptr) abort(); // Note that running data_.ptr = p can lead to undefined behavior if // get_deleter()(get()) deletes this. In order to pevent this, reset() // should update the stored pointer before deleting its old value. // // However, changing reset() to use that behavior may cause current code to // break in unexpected ways. If the destruction of the owned object // dereferences the scoped_ptr when it is destroyed by a call to reset(), // then it will incorrectly dispatch calls to |p| rather than the original // value of |data_.ptr|. // // During the transition period, set the stored pointer to NULL while // deleting the object. Eventually, this safety check will be removed to // prevent the scenario initially described from occuring and // http://crbug.com/176091 can be closed. T* old = data_.ptr; data_.ptr = NULL; if (old != NULL) static_cast(data_)(old); data_.ptr = p; } T* get() const { return data_.ptr; } D& get_deleter() { return data_; } const D& get_deleter() const { return data_; } void swap(scoped_ptr_impl& p2) { // Standard swap idiom: 'using std::swap' ensures that std::swap is // present in the overload set, but we call swap unqualified so that // any more-specific overloads can be used, if available. using std::swap; swap(static_cast(data_), static_cast(p2.data_)); swap(data_.ptr, p2.data_.ptr); } T* release() { T* old_ptr = data_.ptr; data_.ptr = NULL; return old_ptr; } private: // Needed to allow type-converting constructor. template friend class scoped_ptr_impl; // Use the empty base class optimization to allow us to have a D // member, while avoiding any space overhead for it when D is an // empty class. See e.g. http://www.cantrip.org/emptyopt.html for a good // discussion of this technique. struct Data : public D { explicit Data(T* ptr_in) : ptr(ptr_in) {} Data(T* ptr_in, const D& other) : D(other), ptr(ptr_in) {} T* ptr; }; Data data_; DISALLOW_COPY_AND_ASSIGN(scoped_ptr_impl); }; } // namespace internal // A scoped_ptr is like a T*, except that the destructor of scoped_ptr // automatically deletes the pointer it holds (if any). // That is, scoped_ptr owns the T object that it points to. // Like a T*, a scoped_ptr may hold either NULL or a pointer to a T object. // Also like T*, scoped_ptr is thread-compatible, and once you // dereference it, you get the thread safety guarantees of T. // // The size of scoped_ptr is small. On most compilers, when using the // DefaultDeleter, sizeof(scoped_ptr) == sizeof(T*). Custom deleters will // increase the size proportional to whatever state they need to have. See // comments inside scoped_ptr_impl<> for details. // // Current implementation targets having a strict subset of C++11's // unique_ptr<> features. Known deficiencies include not supporting move-only // deleteres, function pointers as deleters, and deleters with reference // types. template > class scoped_ptr { WEBRTC_MOVE_ONLY_TYPE_FOR_CPP_03(scoped_ptr, RValue) public: // The element and deleter types. typedef T element_type; typedef D deleter_type; // Constructor. Defaults to initializing with NULL. scoped_ptr() : impl_(NULL) { } // Constructor. Takes ownership of p. explicit scoped_ptr(element_type* p) : impl_(p) { } // Constructor. Allows initialization of a stateful deleter. scoped_ptr(element_type* p, const D& d) : impl_(p, d) { } // Constructor. Allows construction from a scoped_ptr rvalue for a // convertible type and deleter. // // IMPLEMENTATION NOTE: C++11 unique_ptr<> keeps this constructor distinct // from the normal move constructor. By C++11 20.7.1.2.1.21, this constructor // has different post-conditions if D is a reference type. Since this // implementation does not support deleters with reference type, // we do not need a separate move constructor allowing us to avoid one // use of SFINAE. You only need to care about this if you modify the // implementation of scoped_ptr. template scoped_ptr(scoped_ptr other) : impl_(&other.impl_) { COMPILE_ASSERT(!webrtc::is_array::value, U_cannot_be_an_array); } // Constructor. Move constructor for C++03 move emulation of this type. scoped_ptr(RValue rvalue) : impl_(&rvalue.object->impl_) { } // operator=. Allows assignment from a scoped_ptr rvalue for a convertible // type and deleter. // // IMPLEMENTATION NOTE: C++11 unique_ptr<> keeps this operator= distinct from // the normal move assignment operator. By C++11 20.7.1.2.3.4, this templated // form has different requirements on for move-only Deleters. Since this // implementation does not support move-only Deleters, we do not need a // separate move assignment operator allowing us to avoid one use of SFINAE. // You only need to care about this if you modify the implementation of // scoped_ptr. template scoped_ptr& operator=(scoped_ptr rhs) { COMPILE_ASSERT(!webrtc::is_array::value, U_cannot_be_an_array); impl_.TakeState(&rhs.impl_); return *this; } // Reset. Deletes the currently owned object, if any. // Then takes ownership of a new object, if given. void reset(element_type* p = NULL) { impl_.reset(p); } // Accessors to get the owned object. // operator* and operator-> will assert() if there is no current object. element_type& operator*() const { assert(impl_.get() != NULL); return *impl_.get(); } element_type* operator->() const { assert(impl_.get() != NULL); return impl_.get(); } element_type* get() const { return impl_.get(); } // Access to the deleter. deleter_type& get_deleter() { return impl_.get_deleter(); } const deleter_type& get_deleter() const { return impl_.get_deleter(); } // Allow scoped_ptr to be used in boolean expressions, but not // implicitly convertible to a real bool (which is dangerous). // // Note that this trick is only safe when the == and != operators // are declared explicitly, as otherwise "scoped_ptr1 == // scoped_ptr2" will compile but do the wrong thing (i.e., convert // to Testable and then do the comparison). private: typedef webrtc::internal::scoped_ptr_impl scoped_ptr::*Testable; public: operator Testable() const { return impl_.get() ? &scoped_ptr::impl_ : NULL; } // Comparison operators. // These return whether two scoped_ptr refer to the same object, not just to // two different but equal objects. bool operator==(const element_type* p) const { return impl_.get() == p; } bool operator!=(const element_type* p) const { return impl_.get() != p; } // Swap two scoped pointers. void swap(scoped_ptr& p2) { impl_.swap(p2.impl_); } // Release a pointer. // The return value is the current pointer held by this object. // If this object holds a NULL pointer, the return value is NULL. // After this operation, this object will hold a NULL pointer, // and will not own the object any more. element_type* release() WARN_UNUSED_RESULT { return impl_.release(); } // C++98 doesn't support functions templates with default parameters which // makes it hard to write a PassAs() that understands converting the deleter // while preserving simple calling semantics. // // Until there is a use case for PassAs() with custom deleters, just ignore // the custom deleter. template scoped_ptr PassAs() { return scoped_ptr(Pass()); } private: // Needed to reach into |impl_| in the constructor. template friend class scoped_ptr; webrtc::internal::scoped_ptr_impl impl_; // Forbidden for API compatibility with std::unique_ptr. explicit scoped_ptr(int disallow_construction_from_null); // Forbid comparison of scoped_ptr types. If U != T, it totally // doesn't make sense, and if U == T, it still doesn't make sense // because you should never have the same object owned by two different // scoped_ptrs. template bool operator==(scoped_ptr const& p2) const; template bool operator!=(scoped_ptr const& p2) const; }; template class scoped_ptr { WEBRTC_MOVE_ONLY_TYPE_FOR_CPP_03(scoped_ptr, RValue) public: // The element and deleter types. typedef T element_type; typedef D deleter_type; // Constructor. Defaults to initializing with NULL. scoped_ptr() : impl_(NULL) { } // Constructor. Stores the given array. Note that the argument's type // must exactly match T*. In particular: // - it cannot be a pointer to a type derived from T, because it is // inherently unsafe in the general case to access an array through a // pointer whose dynamic type does not match its static type (eg., if // T and the derived types had different sizes access would be // incorrectly calculated). Deletion is also always undefined // (C++98 [expr.delete]p3). If you're doing this, fix your code. // - it cannot be NULL, because NULL is an integral expression, not a // pointer to T. Use the no-argument version instead of explicitly // passing NULL. // - it cannot be const-qualified differently from T per unique_ptr spec // (http://cplusplus.github.com/LWG/lwg-active.html#2118). Users wanting // to work around this may use implicit_cast(). // However, because of the first bullet in this comment, users MUST // NOT use implicit_cast() to upcast the static type of the array. explicit scoped_ptr(element_type* array) : impl_(array) { } // Constructor. Move constructor for C++03 move emulation of this type. scoped_ptr(RValue rvalue) : impl_(&rvalue.object->impl_) { } // operator=. Move operator= for C++03 move emulation of this type. scoped_ptr& operator=(RValue rhs) { impl_.TakeState(&rhs.object->impl_); return *this; } // Reset. Deletes the currently owned array, if any. // Then takes ownership of a new object, if given. void reset(element_type* array = NULL) { impl_.reset(array); } // Accessors to get the owned array. element_type& operator[](size_t i) const { assert(impl_.get() != NULL); return impl_.get()[i]; } element_type* get() const { return impl_.get(); } // Access to the deleter. deleter_type& get_deleter() { return impl_.get_deleter(); } const deleter_type& get_deleter() const { return impl_.get_deleter(); } // Allow scoped_ptr to be used in boolean expressions, but not // implicitly convertible to a real bool (which is dangerous). private: typedef webrtc::internal::scoped_ptr_impl scoped_ptr::*Testable; public: operator Testable() const { return impl_.get() ? &scoped_ptr::impl_ : NULL; } // Comparison operators. // These return whether two scoped_ptr refer to the same object, not just to // two different but equal objects. bool operator==(element_type* array) const { return impl_.get() == array; } bool operator!=(element_type* array) const { return impl_.get() != array; } // Swap two scoped pointers. void swap(scoped_ptr& p2) { impl_.swap(p2.impl_); } // Release a pointer. // The return value is the current pointer held by this object. // If this object holds a NULL pointer, the return value is NULL. // After this operation, this object will hold a NULL pointer, // and will not own the object any more. element_type* release() WARN_UNUSED_RESULT { return impl_.release(); } private: // Force element_type to be a complete type. enum { type_must_be_complete = sizeof(element_type) }; // Actually hold the data. webrtc::internal::scoped_ptr_impl impl_; // Disable initialization from any type other than element_type*, by // providing a constructor that matches such an initialization, but is // private and has no definition. This is disabled because it is not safe to // call delete[] on an array whose static type does not match its dynamic // type. template explicit scoped_ptr(U* array); explicit scoped_ptr(int disallow_construction_from_null); // Disable reset() from any type other than element_type*, for the same // reasons as the constructor above. template void reset(U* array); void reset(int disallow_reset_from_null); // Forbid comparison of scoped_ptr types. If U != T, it totally // doesn't make sense, and if U == T, it still doesn't make sense // because you should never have the same object owned by two different // scoped_ptrs. template bool operator==(scoped_ptr const& p2) const; template bool operator!=(scoped_ptr const& p2) const; }; } // namespace webrtc // Free functions template void swap(webrtc::scoped_ptr& p1, webrtc::scoped_ptr& p2) { p1.swap(p2); } template bool operator==(T* p1, const webrtc::scoped_ptr& p2) { return p1 == p2.get(); } template bool operator!=(T* p1, const webrtc::scoped_ptr& p2) { return p1 != p2.get(); } namespace webrtc { // DEPRECATED: Use scoped_ptr instead. // TODO(ajm): Remove scoped_array. // // scoped_array extends scoped_ptr to arrays. Deletion of the array pointed to // is guaranteed, either on destruction of the scoped_array or via an explicit // reset(). Use shared_array or std::vector if your needs are more complex. template class scoped_array { private: T* ptr; scoped_array(scoped_array const &); scoped_array & operator=(scoped_array const &); public: typedef T element_type; explicit scoped_array(T* p = NULL) : ptr(p) {} ~scoped_array() { typedef char type_must_be_complete[sizeof(T)]; delete[] ptr; } void reset(T* p = NULL) { typedef char type_must_be_complete[sizeof(T)]; if (ptr != p) { T* arr = ptr; ptr = p; // Delete last, in case arr destructor indirectly results in ~scoped_array delete [] arr; } } T& operator[](ptrdiff_t i) const { assert(ptr != NULL); assert(i >= 0); return ptr[i]; } T* get() const { return ptr; } void swap(scoped_array & b) { T* tmp = b.ptr; b.ptr = ptr; ptr = tmp; } T* release() { T* tmp = ptr; ptr = NULL; return tmp; } T** accept() { if (ptr) { delete [] ptr; ptr = NULL; } return &ptr; } }; template inline void swap(scoped_array& a, scoped_array& b) { a.swap(b); } // DEPRECATED: Use scoped_ptr instead. // TODO(ajm): Remove scoped_ptr_malloc. // // scoped_ptr_malloc<> is similar to scoped_ptr<>, but it accepts a // second template argument, the function used to free the object. template class scoped_ptr_malloc { private: T* ptr; scoped_ptr_malloc(scoped_ptr_malloc const &); scoped_ptr_malloc & operator=(scoped_ptr_malloc const &); public: typedef T element_type; explicit scoped_ptr_malloc(T* p = 0): ptr(p) {} ~scoped_ptr_malloc() { FF(static_cast(ptr)); } void reset(T* p = 0) { if (ptr != p) { FF(static_cast(ptr)); ptr = p; } } T& operator*() const { assert(ptr != 0); return *ptr; } T* operator->() const { assert(ptr != 0); return ptr; } T* get() const { return ptr; } void swap(scoped_ptr_malloc & b) { T* tmp = b.ptr; b.ptr = ptr; ptr = tmp; } T* release() { T* tmp = ptr; ptr = 0; return tmp; } T** accept() { if (ptr) { FF(static_cast(ptr)); ptr = 0; } return &ptr; } }; template inline void swap(scoped_ptr_malloc& a, scoped_ptr_malloc& b) { a.swap(b); } } // namespace webrtc #endif // WEBRTC_SYSTEM_WRAPPERS_INTERFACE_SCOPED_PTR_H_