FooSeq Struct Reference

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

Public Member Functions
FooSeq &	operator= (const struct FooSeq &src_seq)
	Copy elements from another sequence, resizing the sequence if necessary.
bool	copy_no_alloc (const struct FooSeq &src_seq)
	Copy elements from another sequence, only if the destination sequence has enough capacity.
bool	from_array (const Foo array[], DDS_Long length)
	Copy elements from an array of elements, resizing the sequence if necessary. The original contents of the sequence (if any) are replaced.
bool	to_array (Foo array[], DDS_Long length)
	Copy elements to an array of elements. The original contents of the array (if any) are replaced.
Foo &	operator[] (DDS_Long i)
	Set the i-th element of the sequence.
const Foo &	operator[] (DDS_Long i) const
	Get the i-th element for a const sequence.
DDS_Long	length () const
	Get the logical length of this sequence.
bool	length (DDS_Long new_length)
	Set the sequence to the desired length, and resize the sequence if necessary.
bool	ensure_length (DDS_Long length, DDS_Long max)
	Set the sequence to the desired length, and resize the sequence if necessary.
DDS_Long	maximum () const
	Get the current maximum number of elements that can be stored in this sequence.
bool	maximum (DDS_Long new_max)
	Resize this sequence to a new desired maximum.
bool	loan_contiguous (Foo *buffer, DDS_Long new_length, DDS_Long new_max)
	Loan a contiguous buffer to this sequence.
bool	loan_discontiguous (Foo **buffer, DDS_Long new_length, DDS_Long new_max)
	Loan a discontiguous buffer to this sequence.
bool	unloan ()
	Return the loaned buffer in the sequence and set the maximum to 0.
Foo *	get_contiguous_buffer () const
	Return the contiguous buffer of the sequence.
Foo **	get_discontiguous_buffer () const
	Return the discontiguous buffer of the sequence.
bool	has_ownership ()
	Return the value of the owned flag.
	~FooSeq ()
	Deallocate this sequence's buffer.
	FooSeq (DDS_Long new_max=0)
	Create a sequence with the given maximum.
	FooSeq (const struct FooSeq &foo_seq)
	Create a sequence by copying from an existing sequence.

Detailed Description

<<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. The sequence offers a subset of the methods defined by the standard OMG IDL to C++ mapping for sequences. 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 FooSeq::maximum() operation.

• The 'length' represents the actual number of elements it currently holds. It is returned by the FooSeq::length() operation.

• The 'owned' flag represents whether the sequence owns the underlying buffer. It is returned by the FooSeq::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 == DDS_BOOLEAN_TRUE, the sequence has ownership on the buffer. It is then responsible for destroying the buffer when the sequence is destroyed.

  • If the owned == DDS_BOOLEAN_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 == DDS_BOOLEAN_TRUE

See Also

FooDataWriter, FooDataReader, FooTypeSupport, rtiddsgen

Constructor & Destructor Documentation

FooSeq::~FooSeq

(

)

Deallocate this sequence's buffer.

Precondition

(owned == DDS_BOOLEAN_TRUE). If this precondition is not met, no memory will be freed and an error will be logged.

Postcondition

maximum == 0 and the underlying buffer is freed.

See Also

FooSeq::maximum(), FooSeq::unloan

FooSeq::FooSeq

(

DDS_Long

new_max = 0

)

Create a sequence with the given maximum.

This is a constructor for the sequence. The constructor will automatically allocate memory to hold new_max elements of type Foo.

This constructor will be used when the application creates a sequence using one of the following:

FooSeq mySeq(5);
 // or
 FooSeq mySeq;
 // or
 FooSeq* mySeqPtr = new FooSeq(5);

Postcondition

maximum == new_max

length == 0

owned == DDS_BOOLEAN_TRUE,

Parameters

new_max

Must be >= 0. Otherwise the sequence will be initialized to a new_max=0.

FooSeq::FooSeq

(

const struct FooSeq &

foo_seq

)

Create a sequence by copying from an existing sequence.

This is a constructor for the sequence. The constructor will automatically allocate memory to hold foo_seq::maximum() elements of type Foo and will copy the current contents of foo_seq into the new sequence.

This constructor will be used when the application creates a sequence using one of the following:

FooSeq mySeq(foo_seq);
 // or
 FooSeq mySeq = foo_seq;
 // or
 FooSeq *mySeqPtr = new FooSeq(foo_seq);

Postcondition

this::maximum == foo_seq::maximum

this::length == foo_seq::length

this[i] == foo_seq[i] for 0 <= i < foo_seq::length

this::owned == DDS_BOOLEAN_TRUE

Note

If the pre-conditions are not met, the constructor will initialize the new sequence to a maximum of zero.

Member Function Documentation

FooSeq& FooSeq::operator=

(

const struct FooSeq &

src_seq

)

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

This method invokes FooSeq::copy_no_alloc after ensuring that the sequence has enough capacity to hold the elements to be copied.

This operator is invoked when the following expression appears in the code:

target_seq = src_seq                     

Important: This method will allocate memory if this::maximum < src_seq::length.

Therefore, to programatically detect the successful completion of the operator it is recommended that the application first sets the length of this sequence to zero, makes the assignment, and then checks that the length of this sequence matches that of src_seq.

Parameters

src_seq

<<in>> the sequence from which to copy

See Also

FooSeq::copy_no_alloc

bool FooSeq::copy_no_alloc

(

const struct FooSeq &

src_seq

)

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 == DDS_BOOLEAN_TRUE

Postcondition

this::length == src_seq::length

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

this::owned == DDS_BOOLEAN_TRUE

Parameters

src_seq

<<in>> the sequence from which to copy

Returns

DDS_BOOLEAN_TRUE if the sequence was successfully copied; DDS_BOOLEAN_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

FooSeq::operator=

bool FooSeq::from_array	(	const Foo	array[],
		DDS_Long	length
	)

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 == DDS_BOOLEAN_TRUE

Postcondition

this::length == length

this[i] == array[i] for 0 <= i < length

this::owned == DDS_BOOLEAN_TRUE

Parameters

array	<<in>> The array of elements to be copy elements from
length	<<in>> The length of the array.

Returns

DDS_BOOLEAN_TRUE if the array was successfully copied; DDS_BOOLEAN_FALSE otherwise.

Note

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

bool FooSeq::to_array	(	Foo	array[],
		DDS_Long	length
	)

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

array	<<in>> The array of elements to be filled with elements from this sequence
length	<<in>> The number of elements to be copied.

Returns

DDS_BOOLEAN_TRUE if the elements of the sequence were successfully copied; DDS_BOOLEAN_FALSE otherwise.

Foo& FooSeq::operator[]

(

DDS_Long

i

)

Set the i-th element of the sequence.

This is the operator that is invoked when the application indexes into a non- const sequence:

myElement = mySequence[i];
 mySequence[i] = myElement;

Note that a reference to the i-th element is returned (and not a copy).

Parameters

i	index of element to access, must be >= 0 and less than FooSeq::length()

Returns

the i-th element

const Foo& FooSeq::operator[]

(

DDS_Long

i

)

const

Get the i-th element for a const sequence.

This is the operator that is invoked when the application indexes into a const sequence:

myElement = mySequence[i];

Note that a reference to the i-th element is returned (and not a copy).

Parameters

i	index of element to access, must be >= 0 and less than FooSeq::length()

Returns

the i-th element

DDS_Long FooSeq::length

(

)

const

Get the logical length of this sequence.

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

Returns

the length of the sequence

bool FooSeq::length

(

DDS_Long

new_length

)

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 lengh by freeing and re-allocating the buffer. However, if the sequence does not own its buffer, this operation will fail.

For sequences that are part of a type declared in IDL, the length must not exceed the maximum established for the sequence in the IDL.

Parameters

new_length

the new desired length. This value must be non-negative. Must be >= 0.

Returns

DDS_BOOLEAN_TRUE on sucess or DDS_BOOLEAN_FALSE on failure

bool FooSeq::ensure_length	(	DDS_Long	length,
		DDS_Long	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

max <= maximum size for IDL bounded sequences

owned == DDS_BOOLEAN_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

DDS_BOOLEAN_TRUE on success, DDS_BOOLEAN_FALSE if the preconditions are not met. In that case the sequence is not modified.

DDS_Long FooSeq::maximum

(

)

const

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

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 FooSeq::maximum(DDS_Long) operation.

Returns

the current maximum of the sequence.

See Also

FooSeq::length()

bool FooSeq::maximum

(

DDS_Long

new_max

)

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 == DDS_BOOLEAN_TRUE

new_max <= maximum size for IDL bounded sequences.

Postcondition

owned == DDS_BOOLEAN_TRUE

length == MINIMUM(original length, new_max)

Parameters

new_max

Must be >= 0.

Returns

DDS_BOOLEAN_TRUE on success, DDS_BOOLEAN_FALSE if the preconditions are not met. In that case the sequence is not modified.

bool FooSeq::loan_contiguous	(	Foo *	buffer,
		DDS_Long	new_length,
		DDS_Long	new_max
	)

Loan a contiguous buffer to this sequence.

This operation changes the owned flag of the sequence to DDS_BOOLEAN_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 FooSeq::maximum(DDS_Long).

Once you have loaned a buffer to a sequence, make sure that you don't free it before calling FooSeq::unloan: the next time you access the sequence, you will be accessing freed memory!

You can use this method to wrap stack memory with a sequence interface, thereby avoiding dynamic memory allocation. Create a FooSeq and an array of type Foo and then loan the array to the sequence:

::Foo fooArray[10];
 ::FooSeq fooSeq;
 fooSeq.loan_contiguous(fooArray, 0, 10); 

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 FooDataReader::read or FooDataReader::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 FooDataReader::return_loan. See the documentation of those methods for more information.

Precondition

FooSeq::maximum() == 0; i.e. the sequence has no memory allocated to it.

FooSeq::has_ownership == DDS_BOOLEAN_TRUE; i.e. the sequence does not already have an outstanding loan

Postcondition

The sequence will store its elements in the buffer provided.

FooSeq::has_ownership == DDS_BOOLEAN_FALSE

FooSeq::length() == new_length

FooSeq::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. It must be the case that that 0 <= new_length <= new_max.
new_max	The allocated number of elements that could fit in the loaned buffer.

Returns

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

See Also

FooSeq::unloan , FooSeq::loan_discontiguous

bool FooSeq::loan_discontiguous	(	Foo **	buffer,
		DDS_Long	new_length,
		DDS_Long	new_max
	)

Loan a discontiguous buffer to this sequence.

This method is exactly like FooSeq::loan_contiguous except that the buffer loaned is an array of Foo pointers, not an array of Foo.

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. It must be the case that that 0 <= new_length <= new_max.
new_max	The allocated number of elements that could fit in the loaned buffer.

See Also

FooSeq::unloan, FooSeq::loan_contiguous

bool FooSeq::unloan

(

)

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 == DDS_BOOLEAN_FALSE

Postcondition

owned == DDS_BOOLEAN_TRUE

maximum == 0

Returns

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

See Also

FooSeq::loan_contiguous, FooSeq::loan_discontiguous, FooSeq::maximum(DDS_Long)

Foo* FooSeq::get_contiguous_buffer

(

)

const

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 FooSeq::length() of the sequence are valid.

This method provides almost no encapsulation of the sequence's underlying implementation. Certain operations, such as FooSeq::maximum(DDS_Long), 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.

Foo** FooSeq::get_discontiguous_buffer

(

)

const

Return the discontiguous buffer of the sequence.

This operation returns the underlying buffer where discontiguous elements of the sequence are stored. The size of the buffer matches the maximum of this sequence, but only the elements up to the FooSeq::length() of the sequence are valid.

The same caveats apply to this method as to FooSeq::get_contiguous_buffer.

The sequence will dereference pointers in the discontiguous buffer to provide access to its elements by value in C and by reference in C++. If you access the discontiguous buffer directly by means of this method, do not store any NULL values into it, as acessing those values will result in a segmentation fault.

Returns

buffer that stores discontiguous elements in sequence.

bool FooSeq::has_ownership

(

)

Return the value of the owned flag.

Returns

DDS_BOOLEAN_TRUE if sequence owns the underlying buffer, or DDS_BOOLEAN_FALSE if it has an outstanding loan.