Sequence Support

Defines sequence interface and primitive data types sequences. More...

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

Macros
#define	DDS_SEQUENCE_INITIALIZER(_t)
	An initializer for new sequence instances.

Functions
DDS_Boolean	FooSeq_initialize (struct FooSeq *self)
	Initialize sequence instances.
DDS_Boolean	FooSeq_finalize (struct FooSeq *self)
	Finalize sequence instances.
DDS_Long	FooSeq_get_maximum (const struct FooSeq *self)
	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.
DDS_Boolean	FooSeq_set_maximum (struct FooSeq *self, DDS_Long new_max)
	Resize this sequence to a new desired maximum.
DDS_Long	FooSeq_get_length (const struct FooSeq *self)
	Get the logical length of this sequence. Get the length that was last set, or zero if the length has never been set.
DDS_Boolean	FooSeq_set_length (struct FooSeq *self, DDS_Long new_length)
	Change the length of this sequence.
Foo *	FooSeq_get_reference (const struct FooSeq *self, DDS_Long i)
	Get the pointer to the i-th element of this sequence.
struct FooSeq *	FooSeq_copy (struct FooSeq *self, const struct FooSeq *src_seq)
	Copy elements from another sequence, resizing the sequence if necessary.This method invokes copies the content of the specified sequence, after ensuring that this sequence has enough capacity to hold the elements to be copied.
DDS_Boolean	FooSeq_is_equal (struct FooSeq *self, struct FooSeq *other)
	Checks whether two sequences have the same contents.
DDS_Boolean	FooSeq_loan_contiguous (struct FooSeq *self, void *buffer, DDS_Long new_length, DDS_Long new_max)
	Loan a contiguous buffer to this sequence.
DDS_Boolean	FooSeq_loan_discontiguous (struct FooSeq *self, void *buffer, DDS_Long new_length, DDS_Long new_max)
	Loan a discontiguous buffer to this sequence.
DDS_Boolean	FooSeq_unloan (struct FooSeq *self)
	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.
DDS_Boolean	FooSeq_has_ownership (const struct FooSeq *self)
	Return the value of the owned flag.
Foo *	FooSeq_get_buffer (struct FooSeq *self)
	Access the internal buffer of a sequence.
DDS_Boolean	FooSeq_set_buffer (struct FooSeq *self, Foo *buffer)
	Set the internal buffer of a sequence.
DDS_Boolean	FooSeq_has_discontiguous_buffer (const struct FooSeq *self)
	Check whether a sequence uses a contiguous or discontiguous buffer for its elements.

---

Detailed Description

Defines sequence interface and primitive data types sequences.

---

Macro Definition Documentation

#define DDS_SEQUENCE_INITIALIZER

(

_t

)

An initializer for new sequence instances.

This constant will initialize a new sequence to a valid empty state. C language users should assign it to uninitialized sequence instances before using them, at the time they are declared, or use FooSeq_initialize as an alternative method to initialize new sequences.

---

Function Documentation

DDS_Boolean FooSeq_initialize

(

struct FooSeq *

self

)

Initialize sequence instances.

Use this function to initialize new sequences to a valid emptu state. C users should initialize sequences before using them.

See also:

DDS_SEQUENCE_INITIALIZER

DDS_Boolean FooSeq_finalize

(

struct FooSeq *

self

)

Finalize sequence instances.

Use this function to finalize sequences by releasing any resource claimed during initialization. C users should always finalize sequences before discarding references to them.

DDS_Long FooSeq_get_maximum

(

const struct FooSeq *

self

)

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 and can only be changed by mean of the FooSeq_set_maximum operation.

Returns:

the current maximum of the sequence.

See also:

FooSeq_get_length

DDS_Boolean FooSeq_set_maximum	(	struct FooSeq *	self,
		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

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.

DDS_Long FooSeq_get_length

(

const struct FooSeq *

self

)

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

DDS_Boolean FooSeq_set_length	(	struct FooSeq *	self,
		DDS_Long	new_length
	)

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 FooSeq_get_maximum operation. (Note that, if necessary, the maximum of this sequence can be increased manually by using the FooSeq_set_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

Returns:

DDS_BOOLEAN_TRUE on sucess or DDS_BOOLEAN_FALSE on failure

Foo* FooSeq_get_reference	(	const struct FooSeq *	self,
		DDS_Long	i
	)

Get the pointer to the i-th element of this sequence.

Parameters:

i	index of element to access, must be >= 0 and less than FooSeq_get_length

Returns:

the i-th element

struct FooSeq* FooSeq_copy ( struct FooSeq *  self, const struct FooSeq *  src_seq  )

read

Copy elements from another sequence, resizing the sequence if necessary.This method invokes copies the content of the specified sequence, after ensuring that this sequence has enough capacity to hold the elements to be copied.

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

DDS_Boolean FooSeq_is_equal	(	struct FooSeq *	self,
		struct FooSeq *	other
	)

Checks whether two sequences have the same contents.

Parameters:

other

<<in>>. Sequence that will be compared to this one.

Returns:

DDS_BOOLEAN_TRUE if the two sequences have the same contents, DDS_BOOLEAN_FALSE otherwise or if an error occurred.

DDS_Boolean FooSeq_loan_contiguous	(	struct FooSeq *	self,
		void *	buffer,
		DDS_Long	new_length,
		DDS_Long	new_max
	)

Loan a contiguous buffer to this sequence.

                  This operation changes the \p 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. <P>                     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_set_maximum. <P>                   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:                 <P>                  <P>                     

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 Micro 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 Micro 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_get_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_get_length == new_length

FooSeq_get_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

DDS_Boolean FooSeq_loan_discontiguous	(	struct FooSeq *	self,
		void *	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

DDS_Boolean FooSeq_unloan

(

struct FooSeq *

self

)

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_set_maximum

DDS_Boolean FooSeq_has_ownership

(

const struct FooSeq *

self

)

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.

Foo* FooSeq_get_buffer

(

struct FooSeq *

self

)

Access the internal buffer of a sequence.

Use this function to access the memory buffer that a sequence uses to store the values of its elements.

DDS_Boolean FooSeq_set_buffer	(	struct FooSeq *	self,
		Foo *	buffer
	)

Set the internal buffer of a sequence.

Use this function to replace the internal memory buffer that a sequence uses to store the values of its elements.

DDS_Boolean FooSeq_has_discontiguous_buffer

(

const struct FooSeq *

self

)

Check whether a sequence uses a contiguous or discontiguous buffer for its elements.