PCL
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 ()
 
 ReferenceCounter (const ReferenceCounter &)
 
 ~ReferenceCounter ()
 
void Attach ()
 
bool Detach ()
 
bool IsUnique () const
 
bool IsUniqueAtomic () const
 
ReferenceCounteroperator= (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 ( )
inline

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.

Definition at line 108 of file ReferenceCounter.h.

◆ ~ReferenceCounter()

pcl::ReferenceCounter::~ReferenceCounter ( )
inline

Destroys a ReferenceCounter object.

Definition at line 115 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 128 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 147 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 166 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 201 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 215 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 177 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 190 of file ReferenceCounter.h.


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