pcl::ReferenceCounter Class Reference

Thread-safe reference counter for copy-on-write data structures. More...

#include <ReferenceCounter.h>

Inherited by pcl::GenericString< T, R, A >::Data, and pcl::RGBColorSystem::Data.

Public Member Functions
	ReferenceCounter ()=default
	ReferenceCounter (const ReferenceCounter &)
	~ReferenceCounter ()
void	Attach ()
bool	Detach ()
bool	IsUnique () const
bool	IsUniqueAtomic () const
ReferenceCounter &	operator= (const ReferenceCounter &)=delete
int	RefCount () const
int	RefCountAtomic () const

Detailed Description

ReferenceCounter is used internally by most PCL container and image classes to implement reference-counted, copy-on-write shared data.

ReferenceCounter is a thread-safe reference counter because it implements its internal counter as an instance of the AtomicInt class. This means that counter increment and decrement are implemented as atomic operations.

Copy-on-write is a fundamental technique for optimization of resources and execution speed by preventing unnecessary duplication of data, especially when objects are copied and aliased frequently but seldom modified. Basically, a set of objects can share the same data with the condition that the data remains unmodified. In this case, the set of objects is said to be referencing a single data item, and all objects in the set are considered as aliases of the data. When an alias object tries to modify its referenced data, a new copy is generated on-demand and the object uniquely references the newly generated data, which can then be freely modified. This mechanism works in a completely automatic and transparent way, and ReferenceCounter just provides a thread-safe counter to keep track of the number of aliased objects that reference the same data structure at a given time, plus a number of useful related functions.

See also

AtomicInt

Definition at line 99 of file ReferenceCounter.h.

Constructor & Destructor Documentation

ReferenceCounter() [1/2]

pcl::ReferenceCounter::ReferenceCounter ( )

default

Constructs a new ReferenceCounter object. The reference counter is initialized to one, which means that only one object (the caller) is referencing the data associated with this object.

~ReferenceCounter()

pcl::ReferenceCounter::~ReferenceCounter ( )

inline

Destroys a ReferenceCounter object.

Definition at line 113 of file ReferenceCounter.h.

ReferenceCounter() [2/2]

pcl::ReferenceCounter::ReferenceCounter ( const ReferenceCounter &  )

inline

Copy constructor. This constructor is equivalent to the default constructor because reference counters are unique objects. In other words, the reference counter is always initialized to one for newly constructed ReferenceCounter objects.

This constructor exists and is not disabled to allow reference-counted data structures to have copy constructors.

Definition at line 126 of file ReferenceCounter.h.

Member Function Documentation

Attach()

void pcl::ReferenceCounter::Attach ( )

inline

Increments the reference counter by one unit. This happens when a new object references the data being controlled with this counter.

Note

This attachment operation is thread-safe: the internal increment operation is atomic.

See also

Detach()

Definition at line 146 of file ReferenceCounter.h.

Detach()

bool pcl::ReferenceCounter::Detach ( )

inline

Decrements the reference counter by one unit. This happens when an object ceases to reference the data being controlled with this counter.

Returns true if the reference counter is greater than zero after the decrement; false if the reference counter becomes zero. When the reference counter is zero, the data being controlled with this counter is no longer referenced by any object and thus can be safely destroyed.

Note

This detachment operation is thread-safe: the internal dereference operation is atomic.

See also

Attach()

Definition at line 165 of file ReferenceCounter.h.

IsUnique()

bool pcl::ReferenceCounter::IsUnique ( ) const

inline

Returns true iff the data being controlled with this counter is not being referenced by more than one object.

See also

IsUniqueAtomic(), Attach(), Detach()

Definition at line 200 of file ReferenceCounter.h.

IsUniqueAtomic()

bool pcl::ReferenceCounter::IsUniqueAtomic ( ) const

inline

Returns true iff the data being controlled with this counter is not being referenced by more than one object.

Note

This operation is thread-safe: the integer comparison has been implemented as an atomic operation.

See also

IsUnique(), Attach(), Detach()

Definition at line 214 of file ReferenceCounter.h.

operator=()

ReferenceCounter& pcl::ReferenceCounter::operator= ( const ReferenceCounter &  )

delete

Copy assignment. This operator is disabled because reference counters are unique objects.

RefCount()

int pcl::ReferenceCounter::RefCount ( ) const

inline

Returns the current value of this reference counter.

See also

RefCountAtomic(), IsUnique()

Definition at line 176 of file ReferenceCounter.h.

RefCountAtomic()

int pcl::ReferenceCounter::RefCountAtomic ( ) const

inline

Returns the current value of this reference counter.

Note

This operation is thread-safe: the integer load has been implemented as an atomic operation.

See also

RefCount(), IsUniqueAtomic()

Definition at line 189 of file ReferenceCounter.h.

---

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

• ReferenceCounter.h