OpenSplice ISO C++ 2 DCPS  v6.x
ISO C++ 2 OpenSplice Data Distribution Service Data-Centric Publish-Subscribe API
Public Member Functions | List of all members
dds::core::Reference< DELEGATE > Class Template Reference

Base class for reference-counted objects. More...

#include "Reference.hpp"

Inheritance diagram for dds::core::Reference< DELEGATE >:
Inheritance graph

Public Member Functions

template<typename DELEGATE >
 Reference (DELEGATE_T *p)
 
template<typename DELEGATE >
 Reference (const DELEGATE_REF_T &p)
 
 Reference (dds::core::null_type &)
 
 Reference (const Reference &ref)
 
template<typename D >
 Reference (const Reference< D > &ref)
 
 ~Reference ()
 
bool is_nil () const
 
template<typename R >
bool operator!= (const R &ref) const
 
bool operator!= (const null_type nil) const
 
DELEGATE * operator-> ()
 
const DELEGATE * operator-> () const
 
template<typename D >
dds::core::Reference< DELEGATE > & operator= (const Reference< D > &that)
 
template<typename R >
dds::core::Reference< DELEGATE > & operator= (const R &rhs)
 
template<typename D >
Reference & operator= (const Reference< D > &that)
 
template<typename R >
Reference & operator= (const R &rhs)
 
Reference & operator= (const null_type)
 
template<typename R >
bool operator== (const R &ref) const
 
bool operator== (const null_type) const
 

Detailed Description

template<typename DELEGATE>
class dds::core::Reference< DELEGATE >

Base class for reference-counted objects.

All objects that have a reference-type have an associated shallow (polymorphic) assignment operator that simply changes the value of the reference. Furthermore, reference-types are safe, meaning that under no circumstances can a reference point to an invalid object. At any single point in time a reference can either refer to the null object or to a valid object.

The semantics for Reference types is defined by the DDS-PSM-Cxx class dds::core::Reference. In the context of this specification the semantics implied by the ReferenceType is mandatory, yet the implementation supplied as part of this standard is provided to show one possible way of implementing this semantics.

List of reference types:

  • Entity
  • Condition
  • GuardCondition
  • ReadCondition
  • QueryCondition
  • Waitset
  • DomainParticipant
  • AnyDataWriter
  • Publisher
  • DataWriter
  • AnyDataReader
  • Subscriber
  • DataReader
  • SharedSamples
  • AnyTopic
  • Topic

Instances of reference types are created using C++ constructors. The trivial constructor is not defined for reference types; the only alternative to properly constructing a reference is to initialize it to a null reference by assigning dds::core::null.

Resource management for some reference types might involve relatively heavyweight operating-system resources (such as threads, mutexes, and network sockets) in addition to memory. These objects therefore provide a function close() that shall halt network communication (in the case of entities) and dispose of any appropriate operating-system resources.

Users of this PSM are recommended to call close on objects of all reference types once they are finished using them. In addition, implementations may automatically close objects that they deem to be no longer in use, subject to the following restrictions:

  • Any object to which the application has a direct reference (not including a WeakReference) is still in use.
  • Any object that has been explicitly retained is still in use.
  • The creator of any object that is still in use is itself still in use.

Definition at line 94 of file Reference.hpp.

Constructor & Destructor Documentation

◆ Reference() [1/5]

template<typename DELEGATE >
dds::core::Reference< DELEGATE >::Reference ( dds::core::null_type &  )
explicit

Creates a "null" Reference.

Parameters
null

Definition at line 36 of file ReferenceImpl.hpp.

◆ Reference() [2/5]

template<typename DELEGATE >
dds::core::Reference< DELEGATE >::Reference ( const Reference< DELEGATE > &  ref)
explicit

Creates a Reference from another.

Parameters
refthe other reference

Definition at line 41 of file ReferenceImpl.hpp.

◆ Reference() [3/5]

template<typename DELEGATE >
template<typename D >
dds::core::Reference< DELEGATE >::Reference ( const Reference< D > &  ref)
explicit

Creates a Reference from other Reference type safely.

Parameters
refthe other reference

Definition at line 47 of file ReferenceImpl.hpp.

◆ ~Reference()

template<typename DELEGATE >
dds::core::Reference< DELEGATE >::~Reference ( )

Destroys a Reference.

There might be an associated garbage collection activity when the current reference is not empty. When the underlaying delegate is referenced by another Reference object as well, then that delegate will not be destroyed.

Definition at line 68 of file ReferenceImpl.hpp.

◆ Reference() [4/5]

template<typename DELEGATE>
template<typename DELEGATE >
dds::core::Reference< DELEGATE >::Reference ( DELEGATE_T *  p)

Definition at line 57 of file ReferenceImpl.hpp.

◆ Reference() [5/5]

template<typename DELEGATE>
template<typename DELEGATE >
dds::core::Reference< DELEGATE >::Reference ( const DELEGATE_REF_T &  p)

Definition at line 62 of file ReferenceImpl.hpp.

Member Function Documentation

◆ is_nil()

template<typename DELEGATE >
bool dds::core::Reference< DELEGATE >::is_nil ( ) const

Check if the referenced object is nil.

In other words, check if the reference is pointing to a null object.

Returns
true if the referenced object is null.

Definition at line 143 of file ReferenceImpl.hpp.

◆ operator!=() [1/2]

template<typename DELEGATE >
template<typename R >
bool dds::core::Reference< DELEGATE >::operator!= ( const R &  ref) const

Compares two Reference objects and returns true if they are not equal.

Inequality is based on the referential inequality of the object being pointed to.

Parameters
refthe other Reference object
Returns
true when not equal

Definition at line 100 of file ReferenceImpl.hpp.

◆ operator!=() [2/2]

template<typename DELEGATE >
bool dds::core::Reference< DELEGATE >::operator!= ( const null_type  nil) const

Special operator!= used to check if this reference object does not equal the dds::core::null reference.

The non-null-check can be done like this:

if (r != dds::core::null) {
// Use the dds reference object r
}
Returns
true if this reference is not null.

Definition at line 157 of file ReferenceImpl.hpp.

◆ operator->() [1/2]

template<typename DELEGATE >
DELEGATE * dds::core::Reference< DELEGATE >::operator-> ( )

The operator->() is provided to be able to directly invoke functions on the delegate.

The decision to provide direct access to the delegate was motivated by the need for providing a way that was not invasive with respect to the CXXDDS API and yet would allow for vendor-specific extension. Thus vendor-specific extensions can be invoked on the Reference and on all its subclasses as follows:

my_dds_entity.standard_function();
my_dds_entity->vendor_specific_extension();
Returns
a reference to delegate.

Definition at line 180 of file ReferenceImpl.hpp.

◆ operator->() [2/2]

template<typename DELEGATE >
const DELEGATE * dds::core::Reference< DELEGATE >::operator-> ( ) const

The operator->() is provided to be able to directly invoke functions on the delegate.

The decision to provide direct access to the delegate was motivated by the need for providing a way that was not invasive with respect to the CXXDDS API and yet would allow for vendor-specific extension. Thus vendor-specific extensions can be invoked on the Reference and on all its subclasses as follows:

my_dds_entity.standard_function();
my_dds_entity->vendor_specific_extension();
Returns
a reference to delegate.

Definition at line 188 of file ReferenceImpl.hpp.

◆ operator=() [1/5]

template<typename DELEGATE>
template<typename D >
dds::core::Reference<DELEGATE>& dds::core::Reference< DELEGATE >::operator= ( const Reference< D > &  that)

Definition at line 109 of file ReferenceImpl.hpp.

◆ operator=() [2/5]

template<typename DELEGATE>
template<typename R >
dds::core::Reference<DELEGATE>& dds::core::Reference< DELEGATE >::operator= ( const R &  rhs)

Definition at line 122 of file ReferenceImpl.hpp.

◆ operator=() [3/5]

template<typename DELEGATE>
template<typename D >
Reference& dds::core::Reference< DELEGATE >::operator= ( const Reference< D > &  that)

Assign new referenced object to this dds reference.

There might be an associated garbage collection activity when the current reference is not empty.

Returns
reference pointing to the new object.

◆ operator=() [4/5]

template<typename DELEGATE>
template<typename R >
Reference& dds::core::Reference< DELEGATE >::operator= ( const R &  rhs)

Assign new referenced object to this dds reference.

There might be an associated garbage collection activity when the current reference is not empty.

Returns
reference pointing to the new object.

◆ operator=() [5/5]

template<typename DELEGATE >
dds::core::Reference< DELEGATE > & dds::core::Reference< DELEGATE >::operator= ( const null_type  )

Special assignment operators that takes care of assigning dds::core::null to this reference.

When assigning null, there might be an associated garbage collection activity.

Returns
reference pointing to a null object.

Definition at line 134 of file ReferenceImpl.hpp.

◆ operator==() [1/2]

template<typename DELEGATE >
template<typename R >
bool dds::core::Reference< DELEGATE >::operator== ( const R &  ref) const

Compares two Reference objects and returns true if they are equal.

Equality is based on the referential equality of the object being pointed.

Parameters
refthe other Reference object
Returns
true when equal

Definition at line 83 of file ReferenceImpl.hpp.

◆ operator==() [2/2]

template<typename DELEGATE >
bool dds::core::Reference< DELEGATE >::operator== ( const null_type  ) const

Special operator== used to check if this reference object equals the dds::core::null reference.

The null-check can be done like this:

if (r == dds::core::null) {
// Do not use the dds reference object r in its current state
}
Returns
true if this reference is null.

Definition at line 150 of file ReferenceImpl.hpp.

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