RTI Connext C++ API  Version 5.0.0
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::move(LoanedSamples<T>&) should be used while passing LoanedSamples by value in and out of a function. Moreover, as assignments are disabled, connext::move(LoanedSamples<T>&) must be used to transfer the ownership of the loaned samples from one object to another. connext::move(LoanedSamples<T>&) 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::move(LoanedSamples<T>&). 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
TThe 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.

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_mementoThe 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

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
readerThe DataReader from which the loan was taken.
data_seqThe FooSeq object containing the loaned samples. After the call this sequence will be empty.
info_seqThe 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
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_ptrThe DataReader from which the loan was taken. After the call the pointer will be updated.
data_seqThe FooSeq object that will contain the loan previously held by the LoanedSamples object. After the call this sequence will loan the underlying data.
info_seqThe 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
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
indexThe 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
indexThe 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)
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

RTI Connext C++ API Version 5.0.0 Copyright © Thu Aug 30 2012 Real-Time Innovations, Inc