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.
external &	operator= (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

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

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

p	The pointer to manage
locked	Should 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::PreconditionNotMetError

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

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