1//// 2Copyright 2002, 2003, 2015, 2017 Peter Dimov 3 4Distributed under the Boost Software License, Version 1.0. 5 6See accompanying file LICENSE_1_0.txt or copy at 7http://www.boost.org/LICENSE_1_0.txt 8//// 9 10[#enable_shared_from_this] 11# enable_shared_from_this 12:toc: 13:toc-title: 14:idprefix: enable_shared_from_this_ 15 16## Description 17 18The class template `enable_shared_from_this` is used as a base class that allows 19a `shared_ptr` or a `weak_ptr` to the current object to be obtained from within a 20member function. 21 22`enable_shared_from_this<T>` defines two member functions called `shared_from_this` 23that return a `shared_ptr<T>` and `shared_ptr<T const>`, depending on constness, to 24`this`. It also defines two member functions called `weak_from_this` that return a 25corresponding `weak_ptr`. 26 27## Example 28 29``` 30#include <boost/enable_shared_from_this.hpp> 31#include <boost/shared_ptr.hpp> 32#include <cassert> 33 34class Y: public boost::enable_shared_from_this<Y> 35{ 36public: 37 38 boost::shared_ptr<Y> f() 39 { 40 return shared_from_this(); 41 } 42}; 43 44int main() 45{ 46 boost::shared_ptr<Y> p(new Y); 47 boost::shared_ptr<Y> q = p->f(); 48 assert(p == q); 49 assert(!(p < q || q < p)); // p and q must share ownership 50} 51``` 52 53## Synopsis 54 55`enable_shared_from_this` is defined in `<boost/smart_ptr/enable_shared_from_this.hpp>`. 56 57``` 58namespace boost { 59 60 template<class T> class enable_shared_from_this { 61 private: 62 63 // exposition only 64 weak_ptr<T> weak_this_; 65 66 protected: 67 68 enable_shared_from_this() = default; 69 ~enable_shared_from_this() = default; 70 71 enable_shared_from_this(const enable_shared_from_this&) noexcept; 72 enable_shared_from_this& operator=(const enable_shared_from_this&) noexcept; 73 74 public: 75 76 shared_ptr<T> shared_from_this(); 77 shared_ptr<T const> shared_from_this() const; 78 79 weak_ptr<T> weak_from_this() noexcept; 80 weak_ptr<T const> weak_from_this() const noexcept; 81 } 82} 83``` 84 85## Members 86 87``` 88enable_shared_from_this(enable_shared_from_this const &) noexcept; 89``` 90[none] 91* {blank} 92+ 93Effects:: Default-constructs `weak_this_`. 94 95NOTE: `weak_this_` is _not_ copied from the argument. 96 97``` 98enable_shared_from_this& operator=(enable_shared_from_this const &) noexcept; 99``` 100[none] 101* {blank} 102+ 103Returns:: `*this`. 104 105NOTE: `weak_this_` is unchanged. 106 107``` 108template<class T> shared_ptr<T> shared_from_this(); 109``` 110``` 111template<class T> shared_ptr<T const> shared_from_this() const; 112``` 113[none] 114* {blank} 115+ 116Returns:: `shared_ptr<T>(weak_this_)`. 117 118NOTE: These members throw `bad_weak_ptr` when `*this` is not owned by a `shared_ptr`. 119 120[NOTE] 121==== 122`weak_this_` is initialized by `shared_ptr` to a copy of itself when it's constructed by a pointer to `*this`. 123For example, in the following code: 124``` 125class Y: public boost::enable_shared_from_this<Y> {}; 126 127int main() 128{ 129 boost::shared_ptr<Y> p(new Y); 130} 131``` 132the construction of `p` will automatically initialize `p\->weak_this_` to `p`. 133==== 134 135``` 136template<class T> weak_ptr<T> weak_from_this() noexcept; 137``` 138``` 139template<class T> weak_ptr<T const> weak_from_this() const noexcept; 140``` 141[none] 142* {blank} 143+ 144Returns:: `weak_this_`. 145 146NOTE: Unlike `shared_from_this()`, `weak_from_this()` is valid in a destructor 147 and returns a `weak_ptr` that is `expired()` but still shares ownership 148 with other `weak_ptr` instances (if any) that refer to the object. 149