dds::core::external< T > Class Template Reference

A managed reference to an object. More...

#include <dds/core/External.hpp>

Public Types
using	shared_ptr = std::shared_ptr< T >
	The smart pointer that external<T> uses. More...

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

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

Detailed Description

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

A managed reference to an object.

Template Parameters

T	The 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

external() [1/4]

template<typename T >

dds::core::external< T >::external ( )

inline

Creates an empty shared object.

external() [2/4]

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

p	The pointer to manage
locked	Should always be false except in objects created internally by the middleware.

external() [3/4]

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);

external() [4/4]

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.

~external()

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

operator=()

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::PreconditionNotMetError

if this->is_locked()

References dds::core::external< T >::is_locked().

operator*() [1/2]

template<typename T >

T & dds::core::external< T >::operator* ( )

inline

Obtains a reference to the managed object.

operator*() [2/2]

template<typename T >

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

inline

Obtains a const reference to the managed object.

get() [1/2]

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

get() [2/2]

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

get_shared_ptr()

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::IllegalOperationError

if is_locked().

operator->() [1/2]

template<typename T >

T * dds::core::external< T >::operator-> ( )

inline

Allows accessing members of the managed object.

operator->() [2/2]

template<typename T >

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

inline

Allows accessing members of the managed object.

operator==()

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.

operator!=()

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.

operator bool()

template<typename T >

RTI_EXPLICIT_CONVERSION dds::core::external< T >::operator bool ( ) const

inline

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

is_locked()

template<typename T >

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

inline

Indicates whether the managed object is locked or not.

Referenced by dds::core::external< T >::operator=().

Friends And Related Function Documentation

swap

template<typename T >

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

friend

Swaps the managed objects and the locked state.