RTI Connext DDS Micro C++ API
Version 3.0.3
|
<<interface>> <<generic>> <<cert>> A type-safe, ordered collection of elements. The type of these elements is referred to in this documentation as "Foo"
.
More...
#include <dds_cpp_sequence_defn.hxx>
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) |
Get 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 |
<<cert>> Get the logical length of this sequence. | |
bool | length (DDS_Long new_length) |
<<cert>> Change the length of this sequence. | |
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 |
<<cert>> Get the current maximum number of elements that can be stored in this sequence. | |
bool | maximum (DDS_Long new_max) |
<<cert>> 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 | unloan () |
Return the loaned buffer in the sequence and set the maximum to 0. | |
Foo * | get_contiguous_buffer () const |
Access the internal buffer of a 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. |
Public Attributes | |
Foo * | _contiguous_buffer |
Pointer to array of contiguous or discontiguous data. | |
DDS_UnsignedLong | _maximum |
Maximum size of the sequence. | |
DDS_UnsignedLong | _length |
Actual length of the sequence that contains data. | |
DDS_Long | _element_size |
Size of data element in the sequence. | |
void * | _token1 |
Reserved for internal use. | |
void * | _token2 |
Reserved for internal use. | |
DDS_UnsignedLong | max_alloc_size |
The maximum allocation for pointer elements (string,wstring) Only in debug librarires. | |
DDS_Char | _flags |
Reserved for internal use. |
<<interface>> <<generic>> <<cert>> A type-safe, ordered collection of elements. The type of these elements is referred to in this documentation as "Foo"
.
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>
asFooSeq
.
The state of a sequence is described by the properties 'maximum', and 'length'.
FooSeq::~FooSeq | ( | ) |
Deallocate this sequence's buffer.
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:
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:
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.
NOTE: If this method 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().
This operator is invoked when the following expression appears in the code:
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.
src_seq | <<in>> the sequence from which to copy |
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.
src_seq | <<in>> the sequence from which to copy |
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.
array | <<in>> The array of elements to be copy elements from |
length | <<in>> The length of the array. |
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.
array | <<in>> The array of elements to be filled with elements from this sequence |
length | <<in>> The number of elements to be copied. |
Foo& FooSeq::operator[] | ( | DDS_Long | i | ) |
Get the i-th
element of the sequence.
This is the operator that is invoked when the application indexes into a non-const sequence:
i | index of element to access, must be >= 0 and less than FooSeq::length() |
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:
i | index of element to access, must be >= 0 and less than FooSeq::length() |
i-th
element DDS_Long FooSeq::length | ( | ) | const |
<<cert>> Get the logical length of this sequence.
Get the length that was last set, or zero if the length has never been set.
bool FooSeq::length | ( | DDS_Long | new_length | ) |
<<cert>> 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::maximum() operation. (Note that, if necessary, the maximum of this sequence can be increased manually by using the FooSeq::maximum(DDS_Long) 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.
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 |
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.
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_Long FooSeq::maximum | ( | ) | const |
<<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::maximum(DDS_Long) operation.
bool FooSeq::maximum | ( | 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.
new_max | Must be >= 0. |
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:
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 DDS 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 DDS Micro will loan memory to your sequences which must be unloaned with FooDataReader::return_loan. See the documentation of those methods for more information.
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. 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.
Foo* FooSeq::get_contiguous_buffer | ( | ) | const |
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.
bool FooSeq::has_ownership | ( | ) |
Return the value of the owned flag.
Foo* FooSeq::_contiguous_buffer |
Pointer to array of contiguous or discontiguous data.
DDS_UnsignedLong FooSeq::_maximum |
Maximum size of the sequence.
The allocated length of this sequence. It applies to whichever of the above buffers is non-NULL, if any. If both a NULL, its value must be 0.
If _maximum == 0, _owned == true.
DDS_UnsignedLong FooSeq::_length |
Actual length of the sequence that contains data.
The current logical length of this seqeunce, i.e. the number of valid elements it contains. It applies to whichever of the above buffers is non-null, if any. If both are NULL, its value must be 0.
DDS_Long FooSeq::_element_size |
Size of data element in the sequence.
Each element in the sequence has this size.
void* FooSeq::_token1 |
Reserved for internal use.
void* FooSeq::_token2 |
Reserved for internal use.
DDS_UnsignedLong FooSeq::max_alloc_size |
The maximum allocation for pointer elements (string,wstring) Only in debug librarires.
DDS_Char FooSeq::_flags |
Reserved for internal use.