15.1.1.6. LoanableCollection

class eprosima::fastdds::dds::LoanableCollection

A collection of generic opaque pointers that can receive the buffer from outside (loan).

This is an abstract class. See LoanableSequence for details.

Subclassed by eprosima::fastdds::dds::LoanableSequence< T >, eprosima::fastdds::dds::StackAllocatedSequence< T, num_items >

Public Functions

const element_type *buffer() const

Get the pointer to the elements buffer.

The returned value may be nullptr if maximum() is 0. Otherwise it is guaranteed that up to maximum() elements can be accessed.

Return

the pointer to the elements buffer.

bool has_ownership() const

Get the ownership flag.

Return

whether the collection has ownership of the buffer.

size_type maximum() const

Get the maximum number of elements currently allocated.

Return

the maximum number of elements currently allocated.

size_type length() const

Get the number of elements currently accessible.

Return

the number of elements currently accessible.

bool length(size_type new_length)

Set the number of elements currently accessible.

This method tells the collection that a certain number of elements should be accessible. If the new length is greater than the current maximum() the collection should allocate space for the new elements. If this is the case and the collection does not own the buffer (i.e. has_ownership() is false) then no allocation will be performed, the length will remain unchanged, and false will be returned.

Pre

new_length >= 0

Return

true if the new length was correctly set.

Post

length() == new_length

Post

maximum() >= new_length

Parameters
  • [in] new_length: New number of elements to be accessible.

bool loan(element_type *buffer, size_type new_maximum, size_type new_length)

Loan a buffer to the collection.

Pre

(has_ownership() == false) || (maximum() == 0)

Pre

new_maximum > 0

Pre

new_maximum >= new_length

Pre

buffer != nullptr

Return

false if preconditions are not met.

Return

true if operation succeeds.

Post

buffer() == buffer

Post

has_ownership() == false

Post

maximum() == new_maximum

Post

length() == new_length

Parameters
  • [in] buffer: pointer to the buffer to be loaned.

  • [in] new_maximum: number of allocated elements in buffer.

  • [in] new_length: number of accessible elements in buffer.

element_type *unloan(size_type &maximum, size_type &length)

Remove the loan from the collection.

Pre

has_ownership() == false

Return

nullptr if preconditions are not met.

Return

pointer to the previously loaned buffer of elements.

Post

buffer() == nullptr

Post

has_ownership() == true

Post

length() == 0

Post

maximum() == 0

Parameters
  • [out] maximum: number of allocated elements on the returned buffer.

  • [out] length: number of accessible elements on the returned buffer.

element_type *unloan()

Remove the loan from the collection.

Pre

has_ownership() == false

Return

nullptr if preconditions are not met.

Return

pointer to the previously loaned buffer of elements.

Post

buffer() == nullptr

Post

has_ownership() == true

Post

length() == 0

Post

maximum() == 0