Sequence Support
[Infrastructure Module]

The FooSeq interface allows you to work with variable-length collections of homogeneous data. More...


Modules

 Built-in Sequences
 Defines sequences of primitive data type.

Data Structures

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

Defines

#define DDS_SEQUENCE_INITIALIZER
 An initializer for new sequence instances.

Functions

DDS_Boolean FooSeq_initialize (struct FooSeq *self)
 Initialize 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.
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.
DDS_Boolean FooSeq_set_length (struct FooSeq *self, DDS_Long new_length)
 Change the length of this sequence.
DDS_Boolean FooSeq_ensure_length (struct FooSeq *self, DDS_Long length, DDS_Long max)
 Set the sequence to the desired length, and resize the sequence if necessary.
Foo FooSeq_get (const struct FooSeq *self, DDS_Long i)
 Get the i-th element for a const sequence.
Foo * FooSeq_get_reference (const struct FooSeq *self, DDS_Long i)
 Get the pointer to the i-th element of this sequence.
DDS_Boolean FooSeq_copy_no_alloc (struct FooSeq *self, const struct FooSeq *src_seq)
 Copy elements from another sequence, only if the destination sequence has enough capacity.
FooSeq * FooSeq_copy (struct FooSeq *self, const struct FooSeq *src_seq)
 Copy elements from another sequence, resizing the sequence if necessary.
DDS_Boolean FooSeq_from_array (struct FooSeq *self, 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.
DDS_Boolean FooSeq_to_array (struct FooSeq *self, Foo array[], DDS_Long length)
 Copy elements to an array of elements. The original contents of the array (if any) are replaced.
DDS_Boolean FooSeq_loan_contiguous (struct FooSeq *self, Foo *buffer, DDS_Long new_length, DDS_Long new_max)
 Loan a contiguous buffer to this sequence.
DDS_Boolean FooSeq_loan_discontiguous (struct FooSeq *self, Foo **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.
Foo * FooSeq_get_contiguous_buffer (const struct FooSeq *self)
 Return the contiguous buffer of the sequence.
Foo ** FooSeq_get_discontiguous_buffer (const struct FooSeq *self)
 Return the discontiguous buffer of the sequence.
DDS_Boolean FooSeq_has_ownership (const struct FooSeq *self)
 Return the value of the owned flag.
DDS_Boolean FooSeq_finalize (struct FooSeq *self)
 Deallocate this sequence's buffer.

Detailed Description

The FooSeq interface allows you to work with variable-length collections of homogeneous data.

This interface is instantiated for each concrete element type in order to provide compile-time type safety to applications. The Built-in Sequences are pre-defined instantiations for the primitive data types.

When you use the rtiddsgen code generation tool, it will automatically generate concrete sequence instantiations for each of your own custom types.

Define Documentation

#define DDS_SEQUENCE_INITIALIZER

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 function to initialize new sequences.

Examples:
HelloWorld_subscriber.c.

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.

Parameters:
self <<in>> Cannot be NULL.
See also:
DDS_SEQUENCE_INITIALIZER

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.

maximum can only be changed with the FooSeq_set_maximum operation.

Parameters:
self <<in>> Cannot be NULL.
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:
self <<in>> Cannot be NULL.
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.

Parameters:
self <<in>> Cannot be NULL.
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 function 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:
self <<in>> Cannot be NULL.
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

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

owned == DDS_BOOLEAN_TRUE if sequence needs to be resized

Postcondition:
length == length

maximum == max if resized

Parameters:
self <<in>> Cannot be NULL.
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.

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

Get the i-th element for a const sequence.

Parameters:
self <<in>> Cannot be NULL.
i index of element to access, must be >= 0 and less than FooSeq_get_length
Returns:
the i-th element

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

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

This operation can used to modify the elements of the sequence in place. 

 struct DDS_LongSeq my_seq = DDS_SEQUENCE_INITIALIZER; 
  DDS_Long* first_element = NULL; 
  DDS_LongSeq_ensure_length(1, 1); 
  first_element = DDS_LongSeq_get_reference(&my_seq, 0); 
  *first_element = 5;

Parameters:
self <<in>> Cannot be NULL.
i index of element to access, must be >= 0 and less than FooSeq_get_length
Returns:
a pointer to the i-th element

DDS_Boolean FooSeq_copy_no_alloc ( struct FooSeq *  self,
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:
self <<in>> Cannot be NULL.
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_copy

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

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

This function invokes FooSeq_copy_no_alloc after ensuring that the sequence has enough capacity to hold the elements to be copied.

Parameters:
self <<in>> Cannot be NULL.
src_seq <<in>> the sequence from which to copy
Returns:
self, this sequence
See also:
FooSeq_copy_no_alloc

DDS_Boolean FooSeq_from_array ( struct FooSeq *  self,
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:
self <<in>> Cannot be NULL.
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 function will print a message to stdout and leave this sequence unchanged.

DDS_Boolean FooSeq_to_array ( struct FooSeq *  self,
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:
self <<in>> Cannot be NULL.
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.

DDS_Boolean FooSeq_loan_contiguous ( struct FooSeq *  self,
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 function 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.

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 function 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: 

 struct ::Foo fooArray[10];
  struct ::FooSeq fooSeq = ::DDS_SEQUENCE_INITIALIZER; 
  ::FooSeq_loan_contiguous(&fooSeq, 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 Data Distribution Service 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 Data Distribution Service will loan memory to your sequences which must be unloaned with FooDataReader_return_loan. See the documentation of those functions 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:
self <<in>> Cannot be NULL.
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,
Foo **  buffer,
DDS_Long  new_length,
DDS_Long  new_max 
)

Loan a discontiguous buffer to this sequence.

This function is exactly like FooSeq_loan_contiguous except that the buffer loaned is an array of Foo pointers, not an array of Foo.

Parameters:
self <<in>> Cannot be NULL.
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 function 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

Parameters:
self <<in>> Cannot be NULL.
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

Foo* FooSeq_get_contiguous_buffer ( const struct FooSeq *  self  ) 

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_get_length of the sequence are valid.

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

Parameters:
self <<in>> Cannot be NULL.
Returns:
buffer that stores contiguous elements in sequence.

Foo** FooSeq_get_discontiguous_buffer ( const struct FooSeq *  self  ) 

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_get_length of the sequence are valid.

The same caveats apply to this function as to FooSeq_get_contiguous_bufferI.

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 function, do not store any NULL values into it, as acessing those values will result in a segmentation fault.

Parameters:
self <<in>> Cannot be NULL.
Returns:
buffer that stores discontiguous elements in sequence.

DDS_Boolean FooSeq_has_ownership ( const struct FooSeq *  self  ) 

Return the value of the owned flag.

Parameters:
self <<in>> Cannot be NULL.
Returns:
DDS_BOOLEAN_TRUE if sequence owns the underlying buffer, or DDS_BOOLEAN_FALSE if it has an outstanding loan.

DDS_Boolean FooSeq_finalize ( struct FooSeq *  self  ) 

Deallocate this sequence's buffer.

Note that this function deletes this sequence's buffer, not this sequence itself. To avoid memory leaks, it should be called even on sequences declared on the stack. And after it has been called on a sequence located in dynamic memory, it is still necessary to call free().

Precondition:
(owned == DDS_BOOLEAN_TRUE). If this precondition is not met, no memory will be freed and an error will be logged.
Parameters:
self <<in>> Cannot be NULL.
Postcondition:
maximum == 0 and the underlying buffer is freed.
See also:
FooSeq_get_maximum, FooSeq_unloan

RTI Data Distribution Service C API Version 4.5e Copyright © 23 Oct 2011 Real-Time Innovations, Inc