DDS::LoanableSequence< E > Class Template Reference
[Sequence Support]

A sequence implementation used internally by the middleware to efficiently manage memory during DDS::TypedDataReader::read and DDS::TypedDataReader::take operations. More...

#include <managed_sequence.h>

Inheritance diagram for DDS::LoanableSequence< E >:

List of all members.

Public Member Functions
virtual E	get_at (System::Int32 i) overridesealed
	Get the i-th element for a const sequence.
virtual System::Boolean	copy_from_no_alloc (Sequence< E >^src) overridesealed
	Copy elements from another sequence, only if the destination sequence has enough capacity.
virtual void	unloan () overridesealed
	Return the loaned buffer in the sequence and set the maximum to 0.
Properties
virtual System::Int32	maximum [set]
	The current maximum number of elements that can be stored in this sequence.

---

Detailed Description

template<typename E>
class DDS::LoanableSequence< E >

A sequence implementation used internally by the middleware to efficiently manage memory during DDS::TypedDataReader::read and DDS::TypedDataReader::take operations.

Applications are not expected to use this type directly.

---

Member Function Documentation

template<typename E>

virtual E DDS::LoanableSequence< E >::get_at

(

System::Int32

i

)

[override, sealed, virtual]

Get the i-th element for a const sequence.

Parameters:

i

index of element to access, must be >= 0 and less than DDS::Sequence::length

Returns:

the i-th element

Reimplemented from DDS::Sequence< E >.

template<typename E>

virtual System::Boolean DDS::LoanableSequence< E >::copy_from_no_alloc

(

Sequence< E >^

src_seq

)

[override, sealed, virtual]

Copy elements from another sequence, only if the destination sequence has enough capacity.

Fill the elements in this sequence by copying the corresponding elements in src_seq. The original contents in this sequence are replaced via the element assignment operation (Foo_copy() function). By default, elements are discarded; 'delete' is not invoked on the discarded elements.

Precondition:

this::maximum >= src_seq::length

this::owned == true

Postcondition:

this::length == src_seq::length

this[i] == src_seq[i] for 0 <= i < target_seq::length

this::owned == true

Parameters:

src_seq

<<in>> the sequence from which to copy

Returns:

true if the sequence was successfully copied; false otherwise.

Note:

If the pre-conditions are not met, the operator will print a message to stdout and leave this sequence unchanged.

See also:

DDS::Sequence::copy_from_no_alloc(DDS::Sequence<T>^)

Reimplemented from DDS::Sequence< E >.

template<typename E>

virtual void DDS::LoanableSequence< E >::unloan

(

)

[override, sealed, virtual]

Return the loaned buffer in the sequence and set the maximum to 0.

This method affects only the state of this sequence; it does not change the contents of the buffer in any way.

Only the user who originally loaned a buffer should return that loan, as the user may have dependencies on that memory known only to them. Unloaning someone else's buffer may cause unspecified problems. For example, suppose a sequence is loaning memory from a custom memory pool. A user of the sequence likely has no way to release the memory back into the pool, so unloaning the sequence buffer would result in a resource leak. If the user were to then re-loan a different buffer, the original creator of the sequence would have no way to discover, when freeing the sequence, that the loan no longer referred to its own memory and would thus not free the user's memory properly, exacerbating the situation and leading to undefined behavior.

Precondition:

owned == false

Postcondition:

owned == true

maximum == 0

Returns:

true if the preconditions were met. Otherwise false. The function only fails if the pre-conditions are not met, in which case it leaves the sequence unmodified.

See also:

DDS::Sequence<T>::loan(array<T>^, System::Int32), DDS::Sequence::loan_discontiguous, DDS::Sequence::maximum

Reimplemented from DDS::Sequence< E >.

---

Property Documentation

template<typename E>

virtual System:: Int32 DDS::LoanableSequence< E >::maximum [set]

The current maximum number of elements that can be stored in this sequence.

Getting the property:

The maximum of the sequence represents the maximum number of elements that the underlying buffer can hold. It does not represent the current number of elements.

The maximum is a non-negative number. It is initialized when the sequence is first created.

maximum can only be changed with the DDS::Sequence::maximum operation.

See also:

DDS::Sequence::length

Setting the property:

Resize this sequence to a new desired maximum. This operation does nothing if the new desired maximum matches the current maximum.

If this sequence owns its buffer and the new maximum is not equal to the old maximum, then the existing buffer will be freed and re-allocated.

Precondition:

owned == true

Postcondition:

owned == true

length == MINIMUM(original length, new_max)

Parameters:

new_max

Must be >= 0.

Reimplemented from DDS::Sequence< E >.