toast unintrusive pointer

---

Detailed Description

Introduction

Performance

Using the library

Introduction

toast::unintrusive_ptr is designed to be a shared_ptr replacement. It will not work in every situation that shared_ptr does, but for those situations where it is suitable it offers superior performance.

Performance

For some applications, smart pointer overhead can become a bottleneck, especially working with large collections of smart pointers. unintrusive_ptr offers superior performance to shared_ptr in 2 ways:

1. Better cache performance. unintrusive_ptr stores the pointed to object adjacent in memory to the reference count. This means that there's a better chance that both will be in cache simultaneously. As of Boost 1.39, you can get this benefit with shared_ptr through use of make_shared. But you can't get benefit #2...

2. Half the size of shared_ptr, thus offering superior assignment performance and heap allocation. shared_ptr keeps two pointers internally, one to the pointed to object and one to the reference count. unintrusive_ptr uses only one pointer internally, so assignment is twice as fast. Also, being half the size means heap allocation of large numbers of unintrusive_ptrs will be faster since a free memory block of half the size has a higher chance of being found.

Using the library

To use unintrusive_ptr, simply pass it a toast::typed_factory or a boost::in_place factory. Unlike shared_ptr, unintrusive_ptr is responsible for creating the object that will be pointed to. This is what enables it to store the object adjacent to its internal reference count.

There are two circumstances where shared_ptr is more appropriate. If you don't control allocation of the object and are using a custom deleter, unintrusive_ptr does not support this. unintrusive_ptr depends on being able to allocate the object itself.

Second, unintrusive_ptr has special rules for base class pointers to derived class objects when multiple inheritance is involved. With an unintrusive_ptr<Base>, you cannot point to an unintrusive_ptr<Derived> if Derived has multiple base classes, or if on the path between Base and Derived in the class hierarchy there is a class with multiple base classes. Base itself may have multiple base classes without issue, just not any classes between Base and Derived in the class hierarchy or Derived itself. For a more detailed explanation see the class docs.

Files
file	enable_unintrusive_from_this.hpp
	enable_unintrusive_from_this.hpp contains the enable_unintrusive_from_this template class.
file	unintrusive_ptr.hpp
	unintrusive_ptr.hpp contains the unintrusive_ptr template class.
file	weak_unintrusive_ptr.hpp
	weak_unintrusive_ptr.hpp contains the weak_unintrusive_ptr template class.
Classes
class	toast::enable_unintrusive_from_this< T >
	Allows you to return an unintrusive_ptr to *this. More...
class	toast::unintrusive_ptr< T >
	An unintrusive smart pointer that is faster than boost::shared_ptr. More...
class	toast::weak_unintrusive_ptr< T >
	Weak unintrusive smart pointer. More...
Functions
template<class X, class Y>
bool	toast::operator== (unintrusive_ptr< X > const &a, unintrusive_ptr< Y > const &b)
template<class X, class Y>
bool	toast::operator!= (unintrusive_ptr< X > const &a, unintrusive_ptr< Y > const &b)
template<class X, class Y>
bool	toast::operator< (unintrusive_ptr< X > const &a, unintrusive_ptr< Y > const &b)
template<class T>
void	toast::swap (unintrusive_ptr< T > &a, unintrusive_ptr< T > &b)
template<class T>
T *	toast::get_pointer (unintrusive_ptr< T > const &p)
template<class T, class U>
unintrusive_ptr< T >	toast::static_pointer_cast (unintrusive_ptr< U > const &r)
template<class T, class U>
unintrusive_ptr< T >	toast::const_pointer_cast (unintrusive_ptr< U > const &r)
template<class T, class U>
unintrusive_ptr< T >	toast::dynamic_pointer_cast (unintrusive_ptr< U > const &r)
template<class T, class U>
bool	toast::operator< (weak_unintrusive_ptr< T > const &a, weak_unintrusive_ptr< U > const &b)
template<class T>
void	toast::swap (weak_unintrusive_ptr< T > &a, weak_unintrusive_ptr< T > &b)