rclcpp  master
C++ ROS Client Library API
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
rclcpp::LoanedMessage< MessageT, AllocatorT > Class Template Reference

#include <loaned_message.hpp>

Collaboration diagram for rclcpp::LoanedMessage< MessageT, AllocatorT >:
Collaboration graph
[legend]

Public Member Functions

 LoanedMessage (const rclcpp::PublisherBase &pub, std::allocator< MessageT > allocator)
 Constructor of the LoanedMessage class. More...
 
 LoanedMessage (const rclcpp::PublisherBase *pub, std::shared_ptr< std::allocator< MessageT >> allocator)
 Constructor of the LoanedMessage class. More...
 
 LoanedMessage (LoanedMessage< MessageT > &&other)
 Move semantic for RVO. More...
 
virtual ~LoanedMessage ()
 Destructor of the LoanedMessage class. More...
 
bool is_valid () const
 Validate if the message was correctly allocated. More...
 
MessageT & get () const
 Access the ROS message instance. More...
 
std::unique_ptr< MessageT, std::function< void(MessageT *)> > release ()
 Release ownership of the ROS message instance. More...
 

Protected Member Functions

 LoanedMessage (const LoanedMessage< MessageT > &other)=delete
 Deleted copy constructor to preserve memory integrity. More...
 

Protected Attributes

const rclcpp::PublisherBasepub_
 
MessageT * message_
 
MessageAllocator message_allocator_
 

Constructor & Destructor Documentation

◆ LoanedMessage() [1/4]

template<typename MessageT , typename AllocatorT = std::allocator<void>>
rclcpp::LoanedMessage< MessageT, AllocatorT >::LoanedMessage ( const rclcpp::PublisherBase pub,
std::allocator< MessageT >  allocator 
)
inline

Constructor of the LoanedMessage class.

The constructor of this class allocates memory for a given message type and associates this with a given publisher.

Given the publisher instance, a case differentiation is being performaned which decides whether the underlying middleware is able to allocate the appropriate memory for this message type or not. In the case that the middleware can not loan messages, the passed in allocator instance is being used to allocate the message within the scope of this class. Otherwise, the allocator is being ignored and the allocation is solely performaned in the underlying middleware with its appropriate allocation strategy. The need for this arises as the user code can be written explicitly targeting a middleware capable of loaning messages. However, this user code is ought to be usable even when dynamically linked against a middleware which doesn't support message loaning in which case the allocator will be used.

Parameters
[in]pubrclcpp::Publisher instance to which the memory belongs
[in]allocatorAllocator instance in case middleware can not allocate messages
Exceptions
anythingrclcpp::exceptions::throw_from_rcl_error can throw.

◆ LoanedMessage() [2/4]

template<typename MessageT , typename AllocatorT = std::allocator<void>>
rclcpp::LoanedMessage< MessageT, AllocatorT >::LoanedMessage ( const rclcpp::PublisherBase pub,
std::shared_ptr< std::allocator< MessageT >>  allocator 
)
inline

Constructor of the LoanedMessage class.

The constructor of this class allocates memory for a given message type and associates this with a given publisher.

Given the publisher instance, a case differentiation is being performaned which decides whether the underlying middleware is able to allocate the appropriate memory for this message type or not. In the case that the middleware can not loan messages, the passed in allocator instance is being used to allocate the message within the scope of this class. Otherwise, the allocator is being ignored and the allocation is solely performaned in the underlying middleware with its appropriate allocation strategy. The need for this arises as the user code can be written explicitly targeting a middleware capable of loaning messages. However, this user code is ought to be usable even when dynamically linked against a middleware which doesn't support message loaning in which case the allocator will be used.

Parameters
[in]pubrclcpp::Publisher instance to which the memory belongs
[in]allocatorAllocator instance in case middleware can not allocate messages
Exceptions
anythingrclcpp::exceptions::throw_from_rcl_error can throw.

◆ LoanedMessage() [3/4]

template<typename MessageT , typename AllocatorT = std::allocator<void>>
rclcpp::LoanedMessage< MessageT, AllocatorT >::LoanedMessage ( LoanedMessage< MessageT > &&  other)
inline

Move semantic for RVO.

◆ ~LoanedMessage()

template<typename MessageT , typename AllocatorT = std::allocator<void>>
virtual rclcpp::LoanedMessage< MessageT, AllocatorT >::~LoanedMessage ( )
inlinevirtual

Destructor of the LoanedMessage class.

The destructor has the explicit task to return the allocated memory for its message instance. If the message was previously allocated via the middleware, the message is getting returned to the middleware to cleanly destroy the allocation. In the case that the local allocator instance was used, the same instance is then being used to destroy the allocated memory.

The contract here is that the memory for this message is valid as long as this instance of the LoanedMessage class is alive.

◆ LoanedMessage() [4/4]

template<typename MessageT , typename AllocatorT = std::allocator<void>>
rclcpp::LoanedMessage< MessageT, AllocatorT >::LoanedMessage ( const LoanedMessage< MessageT > &  other)
protecteddelete

Deleted copy constructor to preserve memory integrity.

Member Function Documentation

◆ is_valid()

template<typename MessageT , typename AllocatorT = std::allocator<void>>
bool rclcpp::LoanedMessage< MessageT, AllocatorT >::is_valid ( ) const
inline

Validate if the message was correctly allocated.

The allocated memory might not be always consistent and valid. Reasons why this could fail is that an allocation step was failing, e.g. just like malloc could fail or a maximum amount of previously allocated messages is exceeded in which case the loaned messages have to be returned to the middleware prior to be able to allocate a new one.

◆ get()

template<typename MessageT , typename AllocatorT = std::allocator<void>>
MessageT& rclcpp::LoanedMessage< MessageT, AllocatorT >::get ( ) const
inline

Access the ROS message instance.

A call to get() will return a mutable reference to the underlying ROS message instance. This allows a user to modify the content of the message prior to publishing it.

If this reference is copied, the memory for this copy is no longer managed by the LoanedMessage instance and has to be cleanup individually.

◆ release()

template<typename MessageT , typename AllocatorT = std::allocator<void>>
std::unique_ptr<MessageT, std::function<void(MessageT *)> > rclcpp::LoanedMessage< MessageT, AllocatorT >::release ( )
inline

Release ownership of the ROS message instance.

A call to release() will unmanage the memory for the ROS message. That means that the destructor of this class will not free the memory on scope exit. If the message is loaned from the middleware but not be published, the user needs to call rcl_return_loaned_message_from_publisher manually. If the memory is from the local allocator, the memory is freed when the unique pointer goes out instead.

Returns
std::unique_ptr to the message instance.

Member Data Documentation

◆ pub_

template<typename MessageT , typename AllocatorT = std::allocator<void>>
const rclcpp::PublisherBase& rclcpp::LoanedMessage< MessageT, AllocatorT >::pub_
protected

◆ message_

template<typename MessageT , typename AllocatorT = std::allocator<void>>
MessageT* rclcpp::LoanedMessage< MessageT, AllocatorT >::message_
protected

◆ message_allocator_

template<typename MessageT , typename AllocatorT = std::allocator<void>>
MessageAllocator rclcpp::LoanedMessage< MessageT, AllocatorT >::message_allocator_
protected

The documentation for this class was generated from the following file: