diff --git a/doc/smart_ptr.adoc b/doc/smart_ptr.adoc index 216f477..7b854da 100644 --- a/doc/smart_ptr.adoc +++ b/doc/smart_ptr.adoc @@ -33,6 +33,8 @@ include::smart_ptr/make_shared.adoc[] include::smart_ptr/enable_shared_from_this.adoc[] +include::smart_ptr/enable_shared_from.adoc[] + include::smart_ptr/make_unique.adoc[] include::smart_ptr/intrusive_ptr.adoc[] diff --git a/doc/smart_ptr/changelog.adoc b/doc/smart_ptr/changelog.adoc index a10239a..eac7d0b 100644 --- a/doc/smart_ptr/changelog.adoc +++ b/doc/smart_ptr/changelog.adoc @@ -17,3 +17,4 @@ http://www.boost.org/LICENSE_1_0.txt * Added aliasing constructors to `weak_ptr` * Added `weak_ptr::empty()` +* Added `enable_shared_from`, `shared_from`, and `weak_from` diff --git a/doc/smart_ptr/enable_shared_from.adoc b/doc/smart_ptr/enable_shared_from.adoc new file mode 100644 index 0000000..5810679 --- /dev/null +++ b/doc/smart_ptr/enable_shared_from.adoc @@ -0,0 +1,89 @@ +//// +Copyright 2002, 2003, 2015, 2017, 2019 Peter Dimov + +Distributed under the Boost Software License, Version 1.0. + +See accompanying file LICENSE_1_0.txt or copy at +http://www.boost.org/LICENSE_1_0.txt +//// + +[#enable_shared_from] +# enable_shared_from +:toc: +:toc-title: +:idprefix: enable_shared_from_ + +## Description + +`enable_shared_from` is used as a base class that allows a `shared_ptr` or a +`weak_ptr` to be obtained given a raw pointer to the object, by using the +functions `shared_from` and `weak_from`. + +`enable_shared_from` differs from `enable_shared_from_this` by the fact +that it's not a template, and is its recommended replacement for new code. + +## Example + +``` +#include +#include +#include + +class Y: public boost::enable_shared_from +{ +public: + + boost::shared_ptr f() + { + return boost::shared_from( this ); + } +}; + +int main() +{ + boost::shared_ptr p(new Y); + boost::shared_ptr q = p->f(); + assert(p == q); + assert(!(p < q || q < p)); // p and q must share ownership +} +``` + +## Synopsis + +`enable_shared_from` is defined in ``. + +``` +namespace boost { + + class enable_shared_from: public enable_shared_from_this + { + }; + + template shared_ptr shared_from( T * p ); + template weak_ptr weak_from( T * p ) noexcept; +} +``` + +## Functions + +``` +template shared_ptr shared_from( T * p ); +``` +[none] +* {blank} ++ +Returns:: `shared_ptr( p\->enable_shared_from::shared_from_this(), p )`. + +NOTE: Throws `bad_weak_ptr` when `p` is not owned by a `shared_ptr`. + +``` +template weak_ptr weak_from( T * p ) noexcept; +``` +[none] +* {blank} ++ +Returns:: `weak_ptr( p\->enable_shared_from::weak_from_this(), p )`. + +NOTE: Unlike `shared_from(this)`, `weak_from(this)` is valid in a destructor + and returns a `weak_ptr` that is `expired()` but still shares ownership + with other `weak_ptr` instances (if any) that refer to the object. diff --git a/doc/smart_ptr/enable_shared_from_this.adoc b/doc/smart_ptr/enable_shared_from_this.adoc index 757c1d4..0b8298d 100644 --- a/doc/smart_ptr/enable_shared_from_this.adoc +++ b/doc/smart_ptr/enable_shared_from_this.adoc @@ -142,3 +142,7 @@ template weak_ptr weak_from_this() const noexcept; * {blank} + Returns:: `weak_this_`. + +NOTE: Unlike `shared_from_this()`, `weak_from_this()` is valid in a destructor + and returns a `weak_ptr` that is `expired()` but still shares ownership + with other `weak_ptr` instances (if any) that refer to the object.