Smart pointer class similar to boost::intrusive_ptr. More...

#include "ptr.h"

Collaboration diagram for ns3::Ptr< T >:

Public Member Functions
	Ptr ()
	Create an empty smart pointer. More...

	Ptr (const Ptr &o)
	Copy by referencing the same underlying object. More...

template<typename U >
	Ptr (const Ptr< U > &o)
	Copy, removing `const` qualifier. More...

	Ptr (T *ptr)
	Create a smart pointer which points to the object pointed to by the input raw pointer ptr. More...

	Ptr (T *ptr, bool ref)
	Create a smart pointer which points to the object pointed to by the input raw pointer ptr. More...

	~Ptr ()
	Destructor. More...

	operator bool () const
	Test for non-NULL pointer. More...

T &	operator* ()
	A dereference. More...

T &	operator* () const
	A `const` dereference. More...

T *	operator-> ()
	An lvalue member access. More...

T *	operator-> () const
	An rvalue member access. More...

Ptr< T > &	operator= (const Ptr &o)
	Assignment operator by referencing the same underlying object. More...

Private Member Functions
void	Acquire () const
	Mark this as a a reference by incrementing the reference count. More...

Private Attributes
T *	m_ptr
	The pointer. More...

Friends
template<typename U >
U *	GetPointer (const Ptr< U > &p)
	Get a permanent pointer to the underlying object. More...

template<typename U >
U *	PeekPointer (const Ptr< U > &p)
	Get a temporary pointer to the underlying object. More...

class	Ptr< const T >
	Interoperate with const instances. More...

Detailed Description

template<typename T>
class ns3::Ptr< T >

Smart pointer class similar to boost::intrusive_ptr.

This smart-pointer class assumes that the underlying type provides a pair of Ref() and Unref() methods which are expected to increment and decrement the internal reference count of the object instance. You can add Ref() and Unref() to a class simply by inheriting from ns3::SimpleRefCount<> using the CRTP (class Foo : public SimpleRefCount<Foo>)

This implementation allows you to manipulate the smart pointer as if it was a normal pointer: you can test if it is non-null, compare it to other pointers of the same type, etc.

It is possible to extract the raw pointer from this smart pointer with the GetPointer() and PeekPointer() methods.

If you want to store a new Object() into a smart pointer, we recommend you to use the CreateObject<>() template function to create the Object and store it in a smart pointer to avoid memory leaks. These functions are really small convenience functions and their goal is just is save you a small bit of typing. If the Object does not inherit from Object (or ObjectBase) there is also a convenience wrapper Create<>()

Template Parameters

T	[explicit] The type of the underlying object.

Definition at line 76 of file ptr.h.

Constructor & Destructor Documentation

◆ Ptr() [1/5]

template<typename T >

ns3::Ptr< T >::Ptr

Create an empty smart pointer.

Definition at line 641 of file ptr.h.

◆ Ptr() [2/5]

template<typename T >

ns3::Ptr< T >::Ptr ( T * ptr )

Create a smart pointer which points to the object pointed to by the input raw pointer ptr.

This method creates its own reference to the pointed object. The caller is responsible for Unref()'ing its own reference, and the smart pointer will eventually do the same, so that object is deleted if no more references to it remain.

Parameters

[in] ptr Raw pointer to manage

Definition at line 647 of file ptr.h.

References ns3::Ptr< T >::Acquire().

Here is the call graph for this function:

◆ Ptr() [3/5]

template<typename T >

ns3::Ptr< T >::Ptr	(	T *	ptr,
		bool	ref
	)

Create a smart pointer which points to the object pointed to by the input raw pointer ptr.

Parameters

[in]	ptr	Raw pointer to manage
[in]	ref	if set to true, this method calls Ref, otherwise, it does not call Ref.

Definition at line 654 of file ptr.h.

References ns3::Ptr< T >::Acquire().

Here is the call graph for this function:

◆ Ptr() [4/5]

template<typename T >

ns3::Ptr< T >::Ptr ( const Ptr< T > & o )

Copy by referencing the same underlying object.

Parameters

[in] o The other Ptr instance.

Definition at line 664 of file ptr.h.

References ns3::Ptr< T >::Acquire(), ns3::Ptr< T >::m_ptr, and ns3::Ptr< T >::PeekPointer.

Here is the call graph for this function:

◆ Ptr() [5/5]

template<typename T >

template<typename U >

ns3::Ptr< T >::Ptr ( const Ptr< U > & o )

Copy, removing const qualifier.

Template Parameters

U	[deduced] The type underlying the Ptr being copied.

Parameters

[in] o The Ptr to copy.

Definition at line 677 of file ptr.h.

References ns3::Ptr< T >::Acquire().

Here is the call graph for this function:

◆ ~Ptr()

template<typename T >

ns3::Ptr< T >::~Ptr

Destructor.

Definition at line 684 of file ptr.h.

Member Function Documentation

◆ Acquire()

template<typename T >

void ns3::Ptr< T >::Acquire

inlineprivate

Mark this as a a reference by incrementing the reference count.

Definition at line 632 of file ptr.h.

Referenced by ns3::Ptr< T >::Ptr().

Here is the caller graph for this function:

◆ operator bool()

template<typename T >

ns3::Ptr< T >::operator bool

explicit

Test for non-NULL pointer.

This enables simple pointer checks like

Ptr<...> p = ...;
if (p) ...
if (!p) ...

The same construct works in the NS_ASSERT... and NS_ABORT... macros.

Note: Explicit tests against 0, NULL or nullptr are not supported. All these cases will fail to compile:
if (p != nullptr {...} // Should be `if (p)`

if (p != NULL) {...}

if (p != 0) {...}

if (p == nullptr {...} // Should be `if (!p)`

if (p == NULL) {...}

if (p == 0) {...}

Just use if (p) or if (!p) as indicated.; NS_TEST... invocations should be written as follows:
// p should be non-NULL

NS_TEST...NE... (p, nullptr, ...);

// p should be NULL

NS_TEST...EQ... (p, nullptr, ...);; Unfortunately return values are not "contextual conversion expression" contexts, so you need to explicitly cast return values to bool:
bool f (...)

{

Ptr<...> p = ...;

return (bool)(p);

}

f
double f(double x, void *params)
Definition: 80211b.c:70

Returns: true if the underlying pointer is non-NULL.

Definition at line 742 of file ptr.h.

◆ operator*() [1/2]

template<typename T >

T & ns3::Ptr< T >::operator*

A dereference.

Returns: A pointer to the underlying object.

Definition at line 735 of file ptr.h.

References NS_ASSERT_MSG.

◆ operator*() [2/2]

template<typename T >

T & ns3::Ptr< T >::operator*

A const dereference.

Returns: A pointer to the underlying object.

Definition at line 727 of file ptr.h.

References NS_ASSERT_MSG.

◆ operator->() [1/2]

template<typename T >

T * ns3::Ptr< T >::operator->

An lvalue member access.

Returns: A pointer to the underlying object.

Definition at line 711 of file ptr.h.

References NS_ASSERT_MSG.

◆ operator->() [2/2]

template<typename T >

T * ns3::Ptr< T >::operator->

An rvalue member access.

Returns: A pointer to the underlying object.

Definition at line 719 of file ptr.h.

References NS_ASSERT_MSG.

◆ operator=()

template<typename T >

Ptr< T > & ns3::Ptr< T >::operator= ( const Ptr< T > & o )

Assignment operator by referencing the same underlying object.

Parameters

[in] o The other Ptr instance.

Returns: A reference to self.

Definition at line 694 of file ptr.h.

References ns3::Ptr< T >::m_ptr.

Friends And Related Function Documentation

◆ GetPointer

template<typename T >

template<typename U >

U* GetPointer ( const Ptr< U > & p )

friend

Get a permanent pointer to the underlying object.

The underlying refcount is incremented prior to returning to the caller so the caller is responsible for calling Unref himself.

Template Parameters

U	[deduced] The actual type of the argument and return pointer.

Parameters

[in] p Smart pointer

Returns: The pointer managed by this smart pointer.

Definition at line 456 of file ptr.h.

◆ PeekPointer

template<typename T >

template<typename U >

U* PeekPointer ( const Ptr< U > & p )

friend

Get a temporary pointer to the underlying object.

The underlying refcount is not incremented prior to returning to the caller so the caller is not responsible for calling Unref himself.

Template Parameters

U	[deduced] The actual type of the argument and return pointer.

Parameters

[in] p Smart pointer

Returns: The pointer managed by this smart pointer.

Definition at line 449 of file ptr.h.

Referenced by ns3::Ptr< T >::Ptr().

◆ Ptr< const T >

template<typename T >

friend class Ptr< const T >

friend

Interoperate with const instances.

Definition at line 80 of file ptr.h.

Member Data Documentation

◆ m_ptr

template<typename T >

T* ns3::Ptr< T >::m_ptr

private

The pointer.

Definition at line 80 of file ptr.h.

Referenced by ns3::Ptr< T >::Ptr(), and ns3::Ptr< T >::operator=().

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

src/core/model/ptr.h

Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

template<typename T> class ns3::Ptr< T >

Constructor & Destructor Documentation

◆ Ptr() [1/5]

◆ Ptr() [2/5]

◆ Ptr() [3/5]

◆ Ptr() [4/5]

◆ Ptr() [5/5]

◆ ~Ptr()

Member Function Documentation

◆ Acquire()

◆ operator bool()

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ operator->() [1/2]

◆ operator->() [2/2]

◆ operator=()

Friends And Related Function Documentation

◆ GetPointer

◆ PeekPointer

◆ Ptr< const T >

Member Data Documentation

◆ m_ptr

template<typename T>
class ns3::Ptr< T >