RTI Connext Micro C API
2.4.14.2
|
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 |
An initializer for new sequence instances. |
Functions | |
DDS_Boolean | FooSeq_initialize (struct FooSeq *self) |
<<cert>> Initialize sequence instances. | |
DDS_Boolean | FooSeq_finalize (struct FooSeq *self) |
Finalize sequence instances. | |
DDS_Long | FooSeq_get_maximum (const struct FooSeq *self) |
<<cert>> 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) |
<<cert>> Resize this sequence to a new desired maximum. | |
DDS_Boolean | FooSeq_set_maximum_w_max (struct FooSeq *self, DDS_Long new_max, DDS_UnsignedLong max_size) |
<<cert>> Resize this sequence to a new desired maximum and allocate max_size + 1 bytes for each pointer element. | |
DDS_Long | FooSeq_get_length (const struct FooSeq *self) |
<<cert>> Get the logical length of this sequence. | |
DDS_Boolean | FooSeq_set_length (struct FooSeq *self, DDS_Long new_length) |
<<cert>> Change the length of this sequence. | |
Foo * | FooSeq_get_reference (const struct FooSeq *self, DDS_Long i) |
<<cert>> 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. | |
struct FooSeq * | FooSeq_copy_w_max (struct FooSeq *self, const struct FooSeq *src_seq, DDS_UnsignedLong max_size) |
Copy elements from another sequence, resizing the sequence if necessary. | |
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. | |
DDS_Boolean | FooSeq_has_ownership (const struct FooSeq *self) |
Return the value of the owned flag. | |
Foo * | FooSeq_get_contiguous_buffer (struct FooSeq *self) |
Access the internal buffer of a sequence. | |
DDS_Boolean | FooSeq_set_contiguous_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. | |
DDS_Boolean | FooSeq_set_token (const struct FooSeq *self, void *token1, void *token2) |
Sets tokens on a sequence. | |
DDS_Boolean | FooSeq_get_token (const struct FooSeq *self, void **token1, void **token2) |
Gets tokens of a 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. | |
DDS_Boolean | FooSeq_ensure_length_w_max (struct FooSeq *self, DDS_Long length, DDS_Long max, DDS_UnsignedLong max_size) |
Set the sequence to the desired length, and resize the sequence if necessary, and allocate each pointer element to max_size + 1 bytes. | |
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_from_array_w_max (struct FooSeq *self, const Foo array[], DDS_Long length, DDS_UnsignedLong max_size) |
Copy elements from an array of pointer elements, resizing the sequence if necessary, where each pointer elements has been preallocated to max_size. The original contents of the sequence (if any) are replaced. | |
DDS_Boolean | FooSeq_to_array (struct FooSeq *self, const 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_to_array_w_max (struct FooSeq *self, const Foo array[], RTI_INT32 length, DDS_UnsignedLong max_size) |
Copy elements to an array of pointer elements, where each pointer element is pre-allocated. The original contents of the array (if any) are replaced. |
Defines sequence interface and primitive data types sequences.
#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.
DDS_Boolean FooSeq_initialize | ( | struct FooSeq * | self | ) |
<<cert>> Initialize sequence instances.
Use this function to initialize new sequences to a valid emptu state. C users should initialize sequences before using them.
self | <<in>> Cannot be NULL. |
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.
self | <<in>> Cannot be NULL. |
<<cert>> 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.
self | <<in>> Cannot be NULL. |
DDS_Boolean FooSeq_set_maximum | ( | struct FooSeq * | self, |
DDS_Long | new_max | ||
) |
<<cert>> 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.
self | <<in>> Cannot be NULL. |
new_max | Must be >= 0. |
DDS_Boolean FooSeq_set_maximum_w_max | ( | struct FooSeq * | self, |
DDS_Long | new_max, | ||
DDS_UnsignedLong | max_size | ||
) |
<<cert>> Resize this sequence to a new desired maximum and allocate max_size + 1 bytes for each pointer element.
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.
self | <<in>> Cannot be NULL. |
new_max | Must be >= 0. |
max_size | <<in>> Each pointer element is allocated to to max_size + 1 bytes. |
DDS_Boolean FooSeq_set_length | ( | struct FooSeq * | self, |
DDS_Long | new_length | ||
) |
<<cert>> 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.
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 |
<<cert>> Get the pointer to the i-th
element of this sequence.
self | <<in>> Cannot be NULL. |
i | index of element to access, must be >= 0 and less than FooSeq_get_length |
i-th
element Copy elements from another sequence, resizing the sequence if necessary.
This function invokes copies the content of the specified sequence, after ensuring that this sequence has enough capacity to hold the elements to be copied.
It is important to know that no check for overlapping memory regions is performed, and copying sequences with overlapping memory regions has undefined behavior. For example, copying two string sequences where the strings are overlapping has undefined behavior.
RTI Connext Micro does not create overlapping memory regions.
NOTE: If this function is called on a sequence that has been created with set_maxium_w_max or ensure_length_w_max, it will automatically call copy_w_max().
self
, this sequence
|
read |
Copy elements from another sequence, resizing the sequence if necessary.
This function invokes copies the content of the specified sequence, after ensuring that this sequence has enough capacity to hold the elements to be copied.
self | <<in>> Cannot be NULL. |
src_seq | <<in>> the sequence from which to copy |
max_size | <<in>> Each element is a pointer to max_size + 1 bytes. |
self
, this sequence DDS_Boolean FooSeq_is_equal | ( | struct FooSeq * | self, |
struct FooSeq * | other | ||
) |
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 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:
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 functions for more information.
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. |
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. 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 function is exactly like FooSeq_loan_contiguous except that the buffer loaned is an array of Foo pointers, not an array of Foo.
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. |
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.
self | <<in>> Cannot be NULL. |
DDS_Boolean FooSeq_has_ownership | ( | const struct FooSeq * | self | ) |
Return the value of the owned flag.
self | <<in>> Cannot be NULL. |
Foo* FooSeq_get_contiguous_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.
self | <<in>> Cannot be NULL. |
DDS_Boolean FooSeq_set_contiguous_buffer | ( | struct FooSeq * | self, |
Foo * | buffer | ||
) |
DDS_Boolean FooSeq_has_discontiguous_buffer | ( | const struct FooSeq * | self | ) |
Check whether a sequence uses a contiguous or discontiguous buffer for its elements.
DDS_Boolean FooSeq_set_token | ( | const struct FooSeq * | self, |
void * | token1, | ||
void * | token2 | ||
) |
Sets tokens on a sequence.
A token is an opaque pointer stored in the sequence. It has no meaning to the sequence and is not considered part of the content.
self | <<in>> Cannot be NULL. |
token1 | The first token to associate with the sequence. |
token2 | The second token to associate with the sequence. |
DDS_Boolean FooSeq_get_token | ( | const struct FooSeq * | self, |
void ** | token1, | ||
void ** | token2 | ||
) |
Gets tokens of a sequence.
A token is an opaque pointer stored in the sequence. It has no meaning to the sequence and is not considered part of the content.
self | <<in>> Cannot be NULL. |
token1 | The first token associated with the sequence |
token2 | The second token associated with the 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.
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.
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 |
DDS_Boolean FooSeq_ensure_length_w_max | ( | struct FooSeq * | self, |
DDS_Long | length, | ||
DDS_Long | max, | ||
DDS_UnsignedLong | max_size | ||
) |
Set the sequence to the desired length, and resize the sequence if necessary, and allocate each pointer element to max_size + 1 bytes.
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.
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 |
max_size | <<in>> Each pointer element is allocated to to max_size + 1 bytes. |
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.
self | <<in>> Cannot be NULL. |
array | <<in>> The array of elements to be copy elements from |
length | <<in>> The length of the array. |
DDS_Boolean FooSeq_from_array_w_max | ( | struct FooSeq * | self, |
const Foo | array[], | ||
DDS_Long | length, | ||
DDS_UnsignedLong | max_size | ||
) |
Copy elements from an array of pointer elements, resizing the sequence if necessary, where each pointer elements has been preallocated to max_size. 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.
self | <<in>> Cannot be NULL. |
array | <<in>> The array of elements to be copy elements from |
length | <<in>> The length of the array. |
max_size | <<in>> The allocation size for each pointer element. |
DDS_Boolean FooSeq_to_array | ( | struct FooSeq * | self, |
const 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.
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. |
DDS_Boolean FooSeq_to_array_w_max | ( | struct FooSeq * | self, |
const Foo | array[], | ||
RTI_INT32 | length, | ||
DDS_UnsignedLong | max_size | ||
) |
Copy elements to an array of pointer elements, where each pointer element is pre-allocated. 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.
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. |
max_size | <<in>> The allocation size for each pointer element. |