<<interface>> <<generic>> A type-safe, ordered collection of elements. The type of these elements is referred to in this documentation as Foo. More...

#include <managed_sequence.h>

Inheritance diagram for DDS::Sequence< T >:

Public Member Functions
System::Boolean	ensure_length (System::Int32 length, System::Int32 max)
	Set the sequence to the desired length, and resize the sequence if necessary.

virtual T	get_at (System::Int32 i)
	Get the `i-th` element for a `const` sequence.

virtual void	set_at (System::Int32 i, T val)
	Set the `i-th` element of the sequence.

void	loan (array< T >^buffer, System::Int32 new_length)
	Loan a contiguous buffer to this sequence.

virtual void	unloan ()
	Return the loaned buffer in the sequence and set the maximum to 0.

void	from_array (array< T >^arr)
	Copy elements from an array of elements, resizing the sequence if necessary. The original contents of the sequence (if any) are replaced.

void	to_array (array< T >^arr)
	Copy elements to an array of elements. The original contents of the array (if any) are replaced.

System::Boolean	copy_from (Sequence< T >^src_seq)
	Copy elements from another sequence, resizing the sequence if necessary.

virtual System::Boolean	copy_from_no_alloc (Sequence< T >^src_seq)
	Copy elements from another sequence, only if the destination sequence has enough capacity.

Properties
System::Int32	length `[get, set]`
	The logical length of this sequence.

virtual System::Int32	maximum `[get, set]`
	The current maximum number of elements that can be stored in this sequence.

array< T >^	buffer `[get]`
	Return the contiguous buffer of the sequence.

System::Boolean	has_ownership `[get]`
	Return the value of the owned flag.

Detailed Description

template<typename T>
class DDS::Sequence< T >

<<interface>> <<generic>> A type-safe, ordered collection of elements. The type of these elements is referred to in this documentation as Foo.

For users who define data types in OMG IDL, this type corresponds to the IDL express sequence<Foo>.

For any user-data type Foo that an application defines for the purpose of data-distribution with RTI Connext, a FooSeq is generated. We refer to an IDL sequence<Foo> as FooSeq.

The state of a sequence is described by the properties 'maximum', 'length' and 'owned'.

The 'maximum' represents the size of the underlying buffer; this is the maximum number of elements it can possibly hold. It is returned by the DDS::Sequence::maximum operation.

The 'length' represents the actual number of elements it currently holds. It is returned by the DDS::Sequence::length operation.

The 'owned' flag represents whether the sequence owns the underlying buffer. It is returned by the DDS::Sequence::has_ownership operation. If the sequence does not own the underlying buffer, the underlying buffer is loaned from somewhere else. This flag influences the lifecycle of the sequence and what operations are allowed on it. The general guidelines are provided below and more details are described in detail as pre-conditions and post-conditions of each of the sequence's operations:
- If owned == true, the sequence has ownership on the buffer. It is then responsible for destroying the buffer when the sequence is destroyed.
- If the owned == false, the sequence does not have ownership on the buffer. This implies that the sequence is loaning the buffer. The sequence cannot be destroyed until the loan is returned.
- A sequence with a zero maximum always has owned == true

See Also: DDS::TypedDataWriter, DDS::TypedDataReader, FooTypeSupport, rtiddsgen

Member Function Documentation

template<typename T>

System::Boolean DDS::Sequence< T >::ensure_length	(	System::Int32	length,
		System::Int32	max
	)

Set the sequence to the desired length, and resize the sequence if necessary.

If the current maximum is greater than the desired length, then sequence is not resized.

Otherwise if this sequence owns its buffer, the sequence is resized to the new maximum by freeing and re-allocating the buffer. However, if the sequence does not own its buffer, this operation will fail.

This function allows user to avoid unnecessary buffer re-allocation.

Precondition: length <= max; owned == true if sequence needs to be resized

Postcondition: length == length; maximum == max if resized

Parameters

length	<<in>> The new length that should be set. Must be >= 0.
max	<<in>> If sequence need to be resized, this is the maximum that should be set. `max` >= `length`

Returns: true on success, false if the preconditions are not met. In that case the sequence is not modified.

template<typename T>

virtual T DDS::Sequence< T >::get_at ( System::Int32 i )

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 in DDS::LoanableSequence< E >, DDS::LoanableSequence< TopicBuiltinTopicData^ >, DDS::LoanableSequence< ParticipantBuiltinTopicData^ >, DDS::LoanableSequence< SubscriptionBuiltinTopicData^ >, DDS::LoanableSequence< M^ >, DDS::LoanableSequence< SampleInfo^ >, DDS::LoanableSequence< Foo^ >, and DDS::LoanableSequence< PublicationBuiltinTopicData^ >.

template<typename T>

virtual void DDS::Sequence< T >::set_at	(	System::Int32	i,
		T	val
	)

virtual

Set the i-th element of the sequence.

Parameters

i	index of element to access, must be >= 0 and less than DDS::Sequence::length
val	<<in>> value to be set

template<typename T>

void DDS::Sequence< T >::loan	(	array< T >^	buffer,
		System::Int32	new_length
	)

Loan a contiguous buffer to this sequence.

This operation changes the owned flag of the sequence to false and also sets the underlying buffer used by the sequence. See the User's Manual for more information about sequences and memory ownership.

Use this method if you want to manage the memory used by the sequence yourself. You must provide an array of elements and integers indicating how many elements are allocated in that array (i.e. the maximum) and how many elements are valid (i.e. the length). The sequence will subsequently use the memory you provide and will not permit it to be freed by a call to DDS::Sequence::maximum.

By default, a sequence you create owns its memory unless you explicitly loan memory of your own to it. In a very few cases, RTI Connext will return a sequence to you that has a loan; those cases are documented as such. For example, if you call DDS::TypedDataReader::read or DDS::TypedDataReader::take and pass in sequences with no loan and no memory allocated, RTI Connext will loan memory to your sequences which must be unloaned with DDS::TypedDataReader::return_loan. See the documentation of those methods for more information.

Precondition: DDS::Sequence::maximum == 0; i.e. the sequence has no memory allocated to it.; DDS::Sequence::has_ownership == true; i.e. the sequence does not already have an outstanding loan

Postcondition: The sequence will store its elements in the buffer provided.; DDS::Sequence::has_ownership == false; DDS::Sequence::length == new_length; DDS::Sequence::maximum == new_max

Parameters

buffer	The new buffer that the sequence will use. Must point to enough memory to hold new_max elements of type Foo. It may be NULL if new_max == 0.
new_length	The desired new length for the sequence.

Returns: true if buffer is successfully loaned to this sequence or false otherwise. Failure only occurs due to failing to meet the pre-conditions. Upon failure the sequence remains unmodified.

See Also: DDS::Sequence::unloan, ::DDS::Sequence::loan_discontiguous

template<typename T>

virtual void DDS::Sequence< T >::unloan ( )

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 in DDS::LoanableSequence< E >, DDS::LoanableSequence< TopicBuiltinTopicData^ >, DDS::LoanableSequence< ParticipantBuiltinTopicData^ >, DDS::LoanableSequence< SubscriptionBuiltinTopicData^ >, DDS::LoanableSequence< M^ >, DDS::LoanableSequence< SampleInfo^ >, DDS::LoanableSequence< Foo^ >, and DDS::LoanableSequence< PublicationBuiltinTopicData^ >.

template<typename T>

void DDS::Sequence< T >::from_array ( array< T >^ arr )

Copy elements from an array of elements, resizing the sequence if necessary. The original contents of the sequence (if any) are replaced.

Fill the elements in this sequence by copying the corresponding elements in array. 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::owned == true

Postcondition: this::length == length; this[i] == array[i] for 0 <= i < length; this::owned == true

Parameters

arr	<<in>> The array of elements to be copy elements from

Returns: true if the array was successfully copied; false otherwise.

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

template<typename T>

void DDS::Sequence< T >::to_array ( array< T >^ arr )

Copy elements to an array of elements. The original contents of the array (if any) are replaced.

Copy the elements of this sequence to the corresponding elements in the array. The original contents of the array are replaced via the element assignment operation (Foo_copy() function). By default, elements are discarded; 'delete' is not invoked on the discarded elements.

Parameters

arr	<<in>> The array of elements to be filled with elements from this sequence

Returns: true if the elements of the sequence were successfully copied; false otherwise.

template<typename T>

System::Boolean DDS::Sequence< T >::copy_from ( Sequence< T >^ src_seq )

Copy elements from another sequence, resizing the sequence if necessary.

This method invokes DDS::Sequence::copy_from(DDS::Sequence<T>^) after ensuring that the sequence has enough capacity to hold the elements to be copied.

Parameters

src_seq <<in>> the sequence from which to copy

See Also: DDS::Sequence::copy_from(DDS::Sequence<T>^)

template<typename T>

virtual System::Boolean DDS::Sequence< T >::copy_from_no_alloc ( Sequence< T >^ src_seq )

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 in DDS::LoanableSequence< E >, DDS::LoanableSequence< TopicBuiltinTopicData^ >, DDS::LoanableSequence< ParticipantBuiltinTopicData^ >, DDS::LoanableSequence< SubscriptionBuiltinTopicData^ >, DDS::LoanableSequence< M^ >, DDS::LoanableSequence< SampleInfo^ >, DDS::LoanableSequence< Foo^ >, and DDS::LoanableSequence< PublicationBuiltinTopicData^ >.

Property Documentation

template<typename T>

System:: Int32 DDS::Sequence< T >::length

getset

The logical length of this sequence.

Getting the property:

Get the length that was last set, or zero if the length has never been set.

Setting the property:

Change the length of this sequence.

This method does not allocate/deallocate memory.

The new length must not exceed the maximum of this sequence as returned by the DDS::Sequence::maximum operation. (Note that, if necessary, the maximum of this sequence can be increased manually by using the DDS::Sequence::maximum operation.)

The elements of the sequence are not modified by this operation. If the new length is larger than the original length, the new elements will be uninitialized; if the length is decreased, the old elements that are beyond the new length will physically remain in the sequence but will not be accessible.

Postcondition: length = new_length.

Parameters

new_length the new desired length. This value must be non-negative and cannot exceed maximum of the sequence. In other words 0 <= new_length <= maximum

template<typename T>

virtual System:: Int32 DDS::Sequence< T >::maximum

getset

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.

template<typename T>

array< T>^ DDS::Sequence< T >::buffer

get

Return the contiguous buffer of the sequence.

Get the underlying buffer where contiguous elements of the sequence are stored. The size of the buffer matches the maximum of the sequence, but only the elements up to the DDS::Sequence::length of the sequence are valid.

This property is real-only.

This method provides almost no encapsulation of the sequence's underlying implementation. Certain operations, such as DDS::Sequence::maximum, may render the buffer invalid. In light of these caveats, this operation should be used with care.

Returns: buffer that stores contiguous elements in sequence.

template<typename T>

System:: Boolean DDS::Sequence< T >::has_ownership

get

Return the value of the owned flag.

This property is real-only.

Returns: true if sequence owns the underlying buffer, or false if it has an outstanding loan.

Public Member Functions

Properties

Detailed Description

template<typename T> class DDS::Sequence< T >

Member Function Documentation

Property Documentation

template<typename T>
class DDS::Sequence< T >