RTI Connext Modern C++ API  Version 6.0.0
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
dds::core::external< T > Class Template Reference

A managed reference to an object. More...

#include <dds/core/External.hpp>

Public Types

typedef std::shared_ptr< T > shared_ptr
 The smart pointer that external<T> uses.
 

Public Member Functions

 external () OMG_NOEXCEPT
 Creates an empty shared object.
 
 external (T *p, bool locked=false)
 Creates a new shared object with the managed object p.
 
 external (shared_ptr p)
 Creates an external instance that shares the managed object and reference counting with an existing shared_ptr.
 
 external (const external &other)
 Creates a shared object from an existing shared object.
 
 ~external ()
 Destroys the managed object if this is the last shared object pointing to it.
 
externaloperator= (const external &other)
 Assigns another external, depending on the locked state.
 
T & operator* () OMG_NOEXCEPT
 Obtains a reference to the managed object.
 
const T & operator* () const OMG_NOEXCEPT
 Obtains a const reference to the managed object.
 
T * get () OMG_NOEXCEPT
 Obtains a pointer to the managed object.
 
const T * get () const OMG_NOEXCEPT
 Obtains a const pointer to the managed object.
 
shared_ptr get_shared_ptr ()
 Obtains a shared_ptr to the managed object.
 
T * operator-> () OMG_NOEXCEPT
 Allows accessing members of the managed object.
 
const T * operator-> () const OMG_NOEXCEPT
 Allows accessing members of the managed object.
 
bool operator== (const external< T > &other) const OMG_NOEXCEPT
 Returns whether two shared objects manage the same object or are both empty.
 
bool operator!= (const external< T > &other) const
 Returns whether two shared objects do not manage the same object.
 
 operator bool () const OMG_NOEXCEPT
 Checks if there is a managed object (is not null) or not (is null)
 
bool is_locked () const
 Indicates whether the managed object is locked or not.
 

Friends

void swap (external< T > &a, external< T > &b) OMG_NOEXCEPT
 Swaps the managed objects and the locked state.
 

Detailed Description

template<typename T>
class dds::core::external< T >

A managed reference to an object.

Template Parameters
TThe type of the object this external<T> manages

Members of an IDL type marked with the @Shared or @external tag map to this C++ type. External members can share the same object when publishing different data samples. This can make more efficient the publication of large objects by saving extra copies.

This class behaves like a std::shared_ptr, except when the object is in "locked" state.

Objects of this class created with any of the constructors documented here behave like a std::shared_ptr<T>. Objects that the middleware returns in a LoanedSample (for example, from dds::sub::DataReader::take) are in a "locked" state and its contents can't be shared or modified. When assigning a sample with locked external members into another one where those members are not locked, the contents are copied, not shared. Modifying a locked object is not allowed. This special behavior prevents applications from corrupting loaned memory.

See Also
Working with IDL types

Constructor & Destructor Documentation

template<typename T >
dds::core::external< T >::external ( )
inline

Creates an empty shared object.

template<typename T >
dds::core::external< T >::external ( T *  p,
bool  locked = false 
)
inline

Creates a new shared object with the managed object p.

Parameters
pThe pointer to manage
lockedShould always be false except in objects created internally by the middleware.
template<typename T >
dds::core::external< T >::external ( shared_ptr  p)
inline

Creates an external instance that shares the managed object and reference counting with an existing shared_ptr.

This constructor is implicit to allow the direct usage of shared_ptr.

For example:

shared_ptr<MyResource> resource(new MyResource);
// pass resource directly to a data-type with a my_resource external
// member whose setter expects an external<MyResource>.
sample1.my_resource(resource);
sample2.my_resource(resource);
// ...
writer.write(sample1);
writer.write(sample2);
template<typename T >
dds::core::external< T >::external ( const external< T > &  other)
inline

Creates a shared object from an existing shared object.

In general, the new shared object shares ownership with other. Only if other.is_locked(), then the new shared object is allocated and its contents copied from other.

Postcondition
if !other.is_locked(), then *this == other. If other.is_locked, then *(*this) == *other but *this != other.
template<typename T >
dds::core::external< T >::~external ( )
inline

Destroys the managed object if this is the last shared object pointing to it.

Member Function Documentation

template<typename T >
external& dds::core::external< T >::operator= ( const external< T > &  other)
inline

Assigns another external, depending on the locked state.

Depending on whether this or other are locked the behavior varies:

  • If this->is_locked() this operation throws dds::core::PreconditionNotMetError
  • If other.is_locked() it performs a deep copy of *other
  • In any other case, after the assignment, *this and other share the same reference to the underlying object, that is, a shared_ptr assignment.
Exceptions
dds::core::PreconditionNotMetErrorif this->is_locked()
template<typename T >
T& dds::core::external< T >::operator* ( )
inline

Obtains a reference to the managed object.

template<typename T >
const T& dds::core::external< T >::operator* ( ) const
inline

Obtains a const reference to the managed object.

template<typename T >
T* dds::core::external< T >::get ( )
inline

Obtains a pointer to the managed object.

Warning
The returned pointer may become invalid if this is destroyed
template<typename T >
const T* dds::core::external< T >::get ( ) const
inline

Obtains a const pointer to the managed object.

Warning
The returned pointer may become invalid if this is destroyed
template<typename T >
shared_ptr dds::core::external< T >::get_shared_ptr ( )
inline

Obtains a shared_ptr to the managed object.

The returned shared_ptr shares the same reference count.

Exceptions
dds::core::IllegalOperationErrorif is_locked().
template<typename T >
T* dds::core::external< T >::operator-> ( )
inline

Allows accessing members of the managed object.

template<typename T >
const T* dds::core::external< T >::operator-> ( ) const
inline

Allows accessing members of the managed object.

template<typename T >
bool dds::core::external< T >::operator== ( const external< T > &  other) const
inline

Returns whether two shared objects manage the same object or are both empty.

template<typename T >
bool dds::core::external< T >::operator!= ( const external< T > &  other) const
inline

Returns whether two shared objects do not manage the same object.

template<typename T >
dds::core::external< T >::operator bool ( ) const
inline

Checks if there is a managed object (is not null) or not (is null)

template<typename T >
bool dds::core::external< T >::is_locked ( ) const
inline

Indicates whether the managed object is locked or not.

Friends And Related Function Documentation

template<typename T >
void swap ( external< T > &  a,
external< T > &  b 
)
friend

Swaps the managed objects and the locked state.


RTI Connext Modern C++ API Version 6.0.0 Copyright © Sun Mar 3 2019 Real-Time Innovations, Inc