Template Class Reference

Inheritance Relationships

Derived Types

Class Documentation

template<typename DELEGATE>
class Reference

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.

Subclassed by dds::core::TEntity< detail::Subscriber >, dds::core::TEntity< detail::Publisher >, dds::core::TEntity< detail::DomainParticipant >, dds::core::TEntity< detail::DataReader >, dds::core::TEntity< detail::Topic >, dds::core::xtypes::TDynamicType< detail::DynamicType >, dds::core::xtypes::TUnionCase< T, detail::UnionCase >, dds::core::TEntity< DELEGATE >, dds::core::TQosProvider< DELEGATE >, dds::core::cond::TCondition< DELEGATE >, dds::core::cond::TWaitSet< DELEGATE >, dds::core::xtypes::TAnnotation< DELEGATE >, dds::core::xtypes::TDynamicData< DELEGATE, DELEGATE_TYPE >, dds::core::xtypes::TDynamicType< DELEGATE >, dds::core::xtypes::TMemberType< DELEGATE, OTHER_DELEGATE >

Public Functions

inline  DECLARE_TYPE_TRAITS (DELEGATE) explicit Reference(dds

Creates a “null” Reference.

Parameters

null –

inline explicit Reference(const Reference &ref)

Creates a Reference from another.

Parameters

ref – the other reference

inline Reference &operator=(const Reference &ref)

Assign a Reference from another.

Parameters

ref – the other reference

template<typename D>
inline explicit Reference(const Reference<D> &ref)

Creates a Reference from other Reference type safely.

Parameters

ref – the other reference

inline ~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.

template<typename R>
inline bool 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

ref – the other Reference object

Returns

true when equal

template<typename R>
inline bool 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

ref – the other Reference object

Returns

true when not equal

template<typename D>
inline Reference &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.

template<typename R>
inline Reference &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.

inline Reference &operator=(const null_type nil)

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.

inline bool 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.

inline bool 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.

inline bool operator!=(const null_type) 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.

inline 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.

inline const 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.

template<typename DELEGATE>
Reference(null_type&)
template<typename DELEGATE>
Reference(DELEGATE_T *p)
template<typename DELEGATE>
Reference(const DELEGATE_REF_T &p)
template<typename D>
Reference<DELEGATE> &operator=(const Reference<D> &that)
template<typename R>
Reference<DELEGATE> &operator=(const R &rhs)

Protected Functions

inline Reference()
inline void set_ref(DELEGATE_T *p)

Protected Attributes

DELEGATE_REF_T impl_