connext::LoanedSamples< T > Class Template Reference

Provides access to a collection of middleware-loaned samples. More...

Classes
struct	LoanMemento
	A simple value-type for the internal representation of the a LoanedSamples object. More...

Public Types
typedef SampleIterator< T, false >	iterator
	The iterator type.
typedef SampleIterator< T, true >	const_iterator
	The const iterator type.

Public Member Functions
	LoanedSamples ()
	Creates an empty LoanedSamples object.
void	release (TDataReader *&reader_ptr, TSeq &data_seq, SampleInfoSeq &info_seq)
	Transfers the ownership of the underlying data and the DDS_SampleInfo sequences.
	LoanedSamples (LoanMemento loan_memento) throw ()
	Reconstruct a new LoanedSamples object from an internal representation of another.
	~LoanedSamples () throw ()
	Automatically returns the loan to the middleware.
value_type	operator[] (size_t index)
	Provides access to the underlying SampleRef object in array-like syntax.
const_value_type	operator[] (size_t index) const
	Provides access to the underlying SampleRef object in array-like syntax.
int	length () const
	Returns the number of samples.
void	return_loan ()
	Returns the loaned samples to the middleware.
	operator LoanMemento () throw ()
	Release the ownership of the underlying loaned data and SampleInfo and returns an internal representation object.
iterator	begin ()
	Provides an iterator to the first element in the container.
iterator	end ()
	Provides an iterator to the past-the-end element in the container.
const_iterator	begin () const
	Provides an iterator to the first element in the container.
const_iterator	end () const
	Provides an iterator to the past-the-end element in the container.

Static Public Member Functions
static LoanedSamples	move_construct_from_loans (TDataReader *reader, TSeq &data_seq, SampleInfoSeq &info_seq)
	Create a new LoanedSamples object by moving the ownership of the data sequence and the DDS_SampleInfo sequences.

Detailed Description

template<typename T>
class connext::LoanedSamples< T >

Provides access to a collection of middleware-loaned samples.

The samples in this container are loaned from the middleware and must be returned at some point.

The loan is automatically returned in the destructor. Alternatively return_loan can be used.

This is a move-only type. That is, The copy-construction and copy-assignment operations are explicitly disabled. Inspite of that the objects of LoanedSamples type can be passed to a function and returned from a function by-value very efficiently. The connext::details::move() should be used while passing LoanedSamples by value in and out of a function. Moreover, as assignments are disabled, connext::details::move() must be used to transfer the ownership of the loaned samples from one object to another. connext::details::move() ensures that there exists exactly one owner of the loan.

Due to its move-only nature, instances of LoanedSamples can't be stored in C++ standard library containers. There are two possible ways to achieve this. Both are not exception safe.

First, use dynamically allocated LoanedSamples<T> objects and the STL containers would store the pointers to the LoanedSamples<T> objects. The LoanedSamples objects returned by the middlware can be moved in to the dynamically allocated LoanedSamples<T> objects using connext::details::move() . Using smart pointers for automatic memory management is highly recommened if this approach is chosen.

Second alternative is to use the LoanMemento conversion operator. An STL container of LoanedSamples<T>::LoanMemento objects can be created from a LoanedSamples<T> object. LoanedSamples<T> object releases it ownership of the resources in this conversion. Therefore, when the LoanMemento object is no longer required, the underlying resources must be returned by first creating a LoanedSamples object from the LoanMemento. This technique does not require a dynamic allocation like the first alternative. However, this technique should be used very carefully because in case of exceptions, LoanMemento object will not free the resources like the LoanedSamples object does.

This container provides STL-compliant random-access iterators (begin and end).

The contained elements are of type connext::SampleRef Therfore, dereferencing a LoanedSamples iterator returns a connext::SampleRef object, which in turn refer to the data and DDS_SampleInfo.

The contents of this container should not be modified and references to the samples it contains are only valid before the loan is returned.

Template Parameters

T	The data type of the contained Samples

See Also

connext::Requester::take_replies(int)

connext::Replier::take_requests(int)

Taking loaned samples

Taking samples by copy

Member Typedef Documentation

template<typename T>

typedef SampleIterator<T, false> connext::LoanedSamples< T >::iterator

The iterator type.

template<typename T>

typedef SampleIterator<T, true> connext::LoanedSamples< T >::const_iterator

The const iterator type.

Constructor & Destructor Documentation

template<typename T>

connext::LoanedSamples< T >::LoanedSamples ( )

inline

Creates an empty LoanedSamples object.

Referenced by connext::LoanedSamples< T >::move_construct_from_loans().

template<typename T>

connext::LoanedSamples< T >::LoanedSamples ( LoanMemento  loan_memento ) throw ()

inline

Reconstruct a new LoanedSamples object from an internal representation of another.

   This constructor will regain the ownership of the underlying data and ::DDS_SampleInfo
   sequences. 

Parameters

loan_memento

The internal representation of another LoanedSamples object.

See Also

connext::LoanedSamples

template<typename T>

connext::LoanedSamples< T >::~LoanedSamples ( ) throw ()

inline

Automatically returns the loan to the middleware.

See Also

return_loan

References connext::LoanedSamples< T >::return_loan().

Member Function Documentation

template<typename T>

static LoanedSamples connext::LoanedSamples< T >::move_construct_from_loans ( TDataReader *  reader, TSeq &  data_seq, SampleInfoSeq &  info_seq  )

inlinestatic

Create a new LoanedSamples object by moving the ownership of the data sequence and the DDS_SampleInfo sequences.

Precondition

The data_seq and info_seq parameters must contained loaned sample from the same DataReader.

Parameters

reader	The DataReader from which the loan was taken.
data_seq	The FooSeq object containing the loaned samples. After the call this sequence will be empty.
info_seq	The DDS_SampleInfoSeq object containing the loaned SampleInfo. After this call the sequence will be empty.

Postcondition

The new LoanedSamples object will manage the ownership of the loans.

Returns

void

See Also

connext::LoanedSamples

References DDS_RETCODE_BAD_PARAMETER, and connext::LoanedSamples< T >::LoanedSamples().

template<typename T>

void connext::LoanedSamples< T >::release ( TDataReader *&  reader_ptr, TSeq &  data_seq, SampleInfoSeq &  info_seq  )

inline

Transfers the ownership of the underlying data and the DDS_SampleInfo sequences.

Precondition

The data_seq and info_seq parameters must be default initialized prior to this call.

Parameters

reader_ptr	The DataReader from which the loan was taken. After the call the pointer will be updated.
data_seq	The FooSeq object that will contain the loan previously held by the LoanedSamples object. After the call this sequence will loan the underlying data.
info_seq	The DDS_SampleInfoSeq object that will contain the SampleInfo loan previously held by the LoanedSamples object. After this call this sequence will loan the underlying DDS_SampleInfoSeq.

Postcondition

The data_seq and info_seq objects will contain the loan previously held by the LoanedSamples. The LoanedSamples object will release its ownership.

Returns

void

See Also

connext::LoanedSamples

References DDS_RETCODE_PRECONDITION_NOT_MET.

template<typename T>

value_type connext::LoanedSamples< T >::operator[] ( size_t  index )

inline

Provides access to the underlying SampleRef object in array-like syntax.

Parameters

index

The index of the Sample. Allowed values are from o to length()-1.

Returns

A connext::SampleRef object that refers to data and DDS_SampleInfo at the specified index.

See Also

connext::LoanedSamples

template<typename T>

const_value_type connext::LoanedSamples< T >::operator[] ( size_t  index ) const

inline

Provides access to the underlying SampleRef object in array-like syntax.

Parameters

index

The index of the Sample. Allowed values are from o to length()-1.

Returns

A connext::SampleRef object that refers to a constant data and constant DDS_SampleInfo at the specified index.

See Also

connext::LoanedSamples

template<typename T>

int connext::LoanedSamples< T >::length ( ) const

inline

Returns the number of samples.

template<typename T>

void connext::LoanedSamples< T >::return_loan ( )

inline

Returns the loaned samples to the middleware.

After calling this operation this object cannot be accessed again.

Calling this operation is optional, since the destructor will automatically do it.

See Also

FooDataReader::return_loan (for more information on how the middleware loans samples)

Referenced by connext::LoanedSamples< T >::~LoanedSamples().

template<typename T>

connext::LoanedSamples< T >::operator LoanMemento ( ) throw ()

inline

Release the ownership of the underlying loaned data and SampleInfo and returns an internal representation object.

LoanMemento object has trivial copy semantics. Therefore, it does not manage resources automatically like LoanedSamples does. This conversion function should be used very carefully. This conversion can be used to store LoanedSamples in a standard library containers. However, note that resource management must be handled manually.

See Also

connext::LoanedSamples

template<typename T>

iterator connext::LoanedSamples< T >::begin ( )

inline

Provides an iterator to the first element in the container.

Returns

A STL-compliant random-access iterator to the first element in this container

See Also

connext::SampleIterator

end

template<typename T>

iterator connext::LoanedSamples< T >::end ( )

inline

Provides an iterator to the past-the-end element in the container.

Returns

A STL-compliant random-access iterator indicating the end of the container.

See Also

connext::SampleIterator

begin

template<typename T>

const_iterator connext::LoanedSamples< T >::begin ( ) const

inline

Provides an iterator to the first element in the container.

Returns

A STL-compliant random-access iterator to the first element in this container

See Also

connext::SampleIterator

end

template<typename T>

const_iterator connext::LoanedSamples< T >::end ( ) const

inline

Provides an iterator to the past-the-end element in the container.

Returns

A STL-compliant random-access iterator indicating the end of the container.

See Also

connext::SampleIterator

begin