pw::SharedPtr< T > Class Template Reference

Overview

template<typename T>
class pw::SharedPtr< T >

A std::shared_ptr<T>-like type that integrates with pw::Allocator.

This is a RAII smart pointer that deallocates any memory it points to when every pointer to the same object has gone out of scope.

Notable differences from std::shared_ptr<T> include:

• It cannot be constructed from a T*. Use Allocator::MakeShared<T>(...) instead.
• Aliasing constructors are not supported to encourage memory safety.
• Constructing a SharedPtr from a UniquePtr takes an lvalue-reference, and is fallible..

Template Parameters

T	The type being pointed to. This may be an array type, e.g. pw::SharedPtr<T[]>.

Inheritance diagram for pw::SharedPtr< T >:

Public Types
using	element_type = typename Base::element_type
using	weak_type = WeakPtr< T >

Public Member Functions
	~SharedPtr ()
	Releases any currently-held value.
constexpr	SharedPtr () noexcept=default
constexpr	SharedPtr (element_type *value, ControlBlock *control_block)
constexpr	SharedPtr (std::nullptr_t) noexcept
constexpr	SharedPtr (const SharedPtr &other) noexcept
	Copy-constructs a SharedPtr<T> from a SharedPtr<T>.
template<typename U , typename = std::enable_if_t<std::is_assignable_v<T*&, U*>>>
constexpr	SharedPtr (const SharedPtr< U > &other) noexcept
template<typename U , typename = std::enable_if_t<std::is_assignable_v<T*&, U*>>>
	SharedPtr (SharedPtr< U > &&other) noexcept
	SharedPtr (UniquePtr< T > &owned) noexcept
constexpr SharedPtr &	operator= (const SharedPtr &other) noexcept
template<typename U , typename = std::enable_if_t<std::is_assignable_v<T*&, U*>>>
constexpr SharedPtr &	operator= (const SharedPtr< U > &other) noexcept
template<typename U , typename = std::enable_if_t<std::is_assignable_v<T*&, U*>>>
SharedPtr &	operator= (SharedPtr< U > &&other) noexcept
SharedPtr &	operator= (std::nullptr_t) noexcept
template<typename U >
constexpr	operator SharedPtr< U > () const
constexpr size_t	size () const
constexpr int32_t	use_count () const
template<typename PtrType >
bool	owner_before (const PtrType &other) const noexcept
void	reset () noexcept
void	swap (SharedPtr &other) noexcept
	Swaps the managed pointer and deallocator of this and another object.
Allocator *	allocator () const
ControlBlock *	GetControlBlock (const ControlBlockHandle &) const
template<typename... Args>
SharedPtr< T >	Create (Allocator *allocator, Args &&... args)
template<typename U , typename >
constexpr SharedPtr< T > &	operator= (const SharedPtr< U > &other) noexcept
template<typename U , typename >
SharedPtr< T > &	operator= (SharedPtr< U > &&other) noexcept

Static Public Member Functions
template<typename... Args>
static SharedPtr	Create (Allocator *allocator, Args &&... args)
static SharedPtr	Create (Allocator *allocator, size_t count, size_t alignment)

Friends
template<typename >
class	WeakPtr
template<typename To , typename From >
constexpr SharedPtr< To >	static_pointer_cast (const SharedPtr< From > &p) noexcept
template<typename To , typename From >
constexpr SharedPtr< To >	const_pointer_cast (const SharedPtr< From > &p) noexcept
constexpr bool	operator== (const SharedPtr &lhs, std::nullptr_t)
constexpr bool	operator== (std::nullptr_t, const SharedPtr &rhs)
constexpr bool	operator== (const SharedPtr &lhs, const SharedPtr &rhs)
constexpr bool	operator!= (const SharedPtr &lhs, std::nullptr_t)
constexpr bool	operator!= (std::nullptr_t, const SharedPtr &rhs)
constexpr bool	operator!= (const SharedPtr &lhs, const SharedPtr &rhs)

Constructor & Destructor Documentation

SharedPtr() [1/6]

template<typename T >

constexpr pw::SharedPtr< T >::SharedPtr ( )

constexprdefaultnoexcept

Creates an empty (nullptr) instance.

NOTE: Instances of this type are most commonly constructed using Allocator::MakeShared.

SharedPtr() [2/6]

template<typename T >

constexpr pw::SharedPtr< T >::SharedPtr ( element_type *  value, ControlBlock *  control_block  )

inlineconstexpr

Constructs a SharedPtr from an already-allocated value.

NOTE: Instances of this type are most commonly constructed using Allocator::MakeShared.

SharedPtr() [3/6]

template<typename T >

constexpr pw::SharedPtr< T >::SharedPtr ( std::nullptr_t  )

inlineconstexprnoexcept

Creates an empty (nullptr) instance.

NOTE: Instances of this type are most commonly constructed using Allocator::MakeShared.

SharedPtr() [4/6]

template<typename T >

template<typename U , typename = std::enable_if_t<std::is_assignable_v<T*&, U*>>>

constexpr pw::SharedPtr< T >::SharedPtr ( const SharedPtr< U > &  other )

inlineconstexprnoexcept

Copy-constructs a SharedPtr<T> from a SharedPtr<U>.

This allows not only pure move construction where T == U, but also converting construction where T is a base class of U.

SharedPtr() [5/6]

template<typename T >

template<typename U , typename = std::enable_if_t<std::is_assignable_v<T*&, U*>>>

pw::SharedPtr< T >::SharedPtr ( SharedPtr< U > &&  other )

inlinenoexcept

Move-constructs a SharedPtr<T> from a SharedPtr<U>.

This allows not only pure move construction where T == U, but also converting construction where T is a base class of U, like SharedPtr<Base> base(deallocator.MakeShared<Child>());.

SharedPtr() [6/6]

template<typename T >

pw::SharedPtr< T >::SharedPtr ( UniquePtr< T > &  owned )

noexcept

Constructs a SharedPtr<T> from a UniquePtr<T>.

NOTE: This constructor differs from SharedPtr(std::unique_ptr&&) in that it takes an l-value reference to the UniquePtr. This constructor must allocate a shared pointer control block. If that allocation fails, the UniquePtr is unmodified and still retains ownership of its object, and an empty SharedPtr is returned. If the allocation succeeds, the UniquePtr will be reset and a SharedPtr to the object will be returned.

Member Function Documentation

allocator()

template<typename T >

Allocator * pw::SharedPtr< T >::allocator ( ) const

inline

Returns the allocator that owns this SharedPtr or nullptr if the SharedPtr is empty.

Create() [1/2]

template<typename T >

template<typename... Args>

static SharedPtr pw::SharedPtr< T >::Create ( Allocator *  allocator, Args &&...  args  )

static

Constructs and object of type T from the given args, and wraps it in a SharedPtr.

The returned value may contain null if allocating memory for the object fails. Callers must check for null before using the SharedPtr.

NOTE: Instances of this type are most commonly constructed using Allocator::MakeShared.

Parameters

[in]

args

Arguments passed to the object constructor.

Create() [2/2]

template<typename T >

SharedPtr< T > pw::SharedPtr< T >::Create ( Allocator *  allocator, size_t  count, size_t  alignment  )

static

Constructs an array of count objects, and wraps it in a UniquePtr

The returned value may contain null if allocating memory for the object fails. Callers must check for null before using the UniquePtr.

NOTE: Instances of this type are most commonly constructed using Allocator::MakeShared.

Parameters

[in]	allocator	Used to allocate memory.
[in]	count	Number of objects to allocate.
[in]	alignment	Alignment requirement for the array.

GetControlBlock()

template<typename T >

ControlBlock * pw::SharedPtr< T >::GetControlBlock ( const ControlBlockHandle &  ) const

inline

Returns the control block for this shared pointer.

Requires the caller to be able to construct a control block handle, which effectively restricts this to upstream Pigweed.

operator SharedPtr< U >()

template<typename T >

template<typename U >

constexpr pw::SharedPtr< T >::operator SharedPtr< U > ( ) const

inlineexplicitconstexpr

Explicit conversion operator for downcasting.

If an arbitrary type A derives from another type B, a shared pointer to A can be automatically upcast to one of type B. This operator performs the reverse operation with an explicit cast.

pw::SharedPtr<A> a1 = allocator.MakeShared<A>();
pw::SharedPtr<B> b = a1;
pw::SharedPtr<A> a2 = static_cast<pw::SharedPtr<A>>(b);

operator=() [1/4]

template<typename T >

constexpr SharedPtr & pw::SharedPtr< T >::operator= ( const SharedPtr< T > &  other )

inlineconstexprnoexcept

Copy-assigns a SharedPtr<T> from a SharedPtr<T>.

This operation releases the value currently stored in this.

operator=() [2/4]

template<typename T >

template<typename U , typename = std::enable_if_t<std::is_assignable_v<T*&, U*>>>

constexpr SharedPtr & pw::SharedPtr< T >::operator= ( const SharedPtr< U > &  other )

constexprnoexcept

Copy-assigns a SharedPtr<T> from a SharedPtr<U>.

This operation releases the value currently stored in this.

This allows not only pure copy assignment where T == U, but also converting assignment where T is a base class of U.

operator=() [3/4]

template<typename T >

template<typename U , typename = std::enable_if_t<std::is_assignable_v<T*&, U*>>>

SharedPtr & pw::SharedPtr< T >::operator= ( SharedPtr< U > &&  other )

noexcept

Move-assigns a SharedPtr<T> from a SharedPtr<U>.

This operation releases the value currently stored in this.

This allows not only pure move assignment where T == U, but also converting assignment where T is a base class of U.

operator=() [4/4]

template<typename T >

SharedPtr< T > & pw::SharedPtr< T >::operator= ( std::nullptr_t  )

noexcept

Sets this SharedPtr to null, releasing any currently-held value.

After this function returns, this SharedPtr will be in an "empty" (nullptr) state until a new value is assigned.

owner_before()

template<typename T >

template<typename PtrType >

bool pw::SharedPtr< T >::owner_before ( const PtrType &  other ) const

inlinenoexcept

Checks whether this precedes other based on an ordering of their control blocks.

reset()

template<typename T >

void pw::SharedPtr< T >::reset

noexcept

Resets this object to an empty state.

If this was the last shared pointer to the associated object, it is destroyed. If this is the last shared or weak pointer associated with the control block, it is deallocated.

size()

template<typename T >

constexpr size_t pw::SharedPtr< T >::size ( ) const

inlineconstexpr

Returns the number of elements allocated.

This will fail to compile if it is called on a non-array type SharedPtr.

use_count()

template<typename T >

constexpr int32_t pw::SharedPtr< T >::use_count ( ) const

inlineconstexpr

Returns the number of shared pointers to the associated object, or 0 if this object is empty.

Friends And Related Function Documentation

const_pointer_cast

template<typename T >

template<typename To , typename From >

constexpr SharedPtr< To > const_pointer_cast ( const SharedPtr< From > &  p )

friend

Creates a new SharedPtr by const casting the given shared pointer.

For an arbitrary type A, a shared pointer to A can be automatically converted to one of type const A. This function can perform the reverse operation.

pw::SharedPtr<const A> a1 = allocator.MakeShared<const A>();
pw::SharedPtr<A> a2 = const_pointer_cast<A>(a1);

static_pointer_cast

template<typename T >

template<typename To , typename From >

constexpr SharedPtr< To > static_pointer_cast ( const SharedPtr< From > &  p )

friend

Creates a new SharedPtr by static casting the given shared pointer.

If an arbitrary type A derives from another type B, a shared pointer to A can be automatically upcast to one of type B. This function can perform the reverse operation and allows specifying only the element type.

pw::SharedPtr<A> a1 = allocator.MakeShared<A>();
pw::SharedPtr<B> b = a1;
pw::SharedPtr<A> a2 = static_pointer_cast<A>(b);

---

The documentation for this class was generated from the following files:

• pw_allocator/public/pw_allocator/allocator.h
• pw_allocator/public/pw_allocator/shared_ptr.h