subscription.hpp File Reference

rclcpp::Subscription<M> — the typed DISPATCH subscriber: the arena owns it and the executor calls your handler. More...

#include <cstdint>
#include <cstddef>
#include <string.h>
#include "rclcpp/detail/traits.hpp"
#include "rclcpp/detail/config.hpp"
#include "rclcpp/detail/entity_name.hpp"
#include "rclcpp/executor.hpp"
#include "rclcpp/result.hpp"
#include "rclcpp/subscription_handle.hpp"
#include "rclcpp/inplace_fn.hpp"
#include "rclcpp/size_bound.hpp"
#include "rclcpp/detail/serialization_format.hpp"
#include "rclcpp/stream.hpp"
#include "rclcpp/detail/std_detect.hpp"
#include "rclcpp/detail/nros_cpp_ffi.h"
#include "rclcpp/qos.hpp"
#include "rclcpp/node.hpp"

Include dependency graph for subscription.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	rclcpp::Subscription< M >

Namespaces
namespace	rclcpp
namespace	rclcpp::detail

Typedefs
using	rclcpp::IntegrityStatus = ::nros_cpp_integrity_status_t
typedef void(*	nros_cpp_subscription_message_callback_t) (const uint8_t *data, size_t len, void *ctx)
typedef void(*	nros_cpp_subscription_message_info_callback_t) (const uint8_t *data, size_t len, const uint8_t *attachment, size_t attachment_len, void *ctx)

Functions
nros_cpp_ret_t	nros_cpp_subscription_register (const nros_cpp_node_t *node, const char *topic, const char *type_name, const char *type_hash, nros_cpp_qos_t qos, nros_cpp_subscription_message_callback_t callback, void *context, size_t *out_handle_id, const nros_cpp_subscription_options_t *options)
nros_cpp_ret_t	nros_cpp_subscription_register_capturing (const nros_cpp_node_t *node, const char *topic, const char *type_name, const char *type_hash, nros_cpp_qos_t qos, nros_cpp_subscription_message_callback_t callback, const uint8_t *capture, size_t capture_len, void(*capture_drop)(void *capture), size_t *out_handle_id, const nros_cpp_subscription_options_t *options)
nros_cpp_ret_t	nros_cpp_subscription_register_with_info (const nros_cpp_node_t *node, const char *topic, const char *type_name, const char *type_hash, nros_cpp_qos_t qos, nros_cpp_subscription_message_info_callback_t callback, void *context, size_t *out_handle_id, const nros_cpp_subscription_options_t *options)

Variables
static constexpr size_t	rclcpp::SUBSCRIPTION_TOPIC_NAME_MAX = 256

Detailed Description

rclcpp::Subscription<M> — the typed DISPATCH subscriber: the arena owns it and the executor calls your handler.

The taking subscriber is rclcpp::PollSubscription<M> in rclcpp/polling_subscription.hpp (phase-456 W2b).

Typedef Documentation

nros_cpp_subscription_message_callback_t

typedef void(* nros_cpp_subscription_message_callback_t) (const uint8_t *data, size_t len, void *ctx)

nros_cpp_subscription_message_info_callback_t

typedef void(* nros_cpp_subscription_message_info_callback_t) (const uint8_t *data, size_t len, const uint8_t *attachment, size_t attachment_len, void *ctx)

Function Documentation

nros_cpp_subscription_register()

nros_cpp_ret_t nros_cpp_subscription_register	(	const nros_cpp_node_t *	node,
		const char *	topic,
		const char *	type_name,
		const char *	type_hash,
		nros_cpp_qos_t	qos,
		nros_cpp_subscription_message_callback_t	callback,
		void *	context,
		size_t *	out_handle_id,
		const nros_cpp_subscription_options_t *	options
	)

nros_cpp_subscription_register_capturing()

nros_cpp_ret_t nros_cpp_subscription_register_capturing	(	const nros_cpp_node_t *	node,
		const char *	topic,
		const char *	type_name,
		const char *	type_hash,
		nros_cpp_qos_t	qos,
		nros_cpp_subscription_message_callback_t	callback,
		const uint8_t *	capture,
		size_t	capture_len,
		void(*)(void *capture)	capture_drop,
		size_t *	out_handle_id,
		const nros_cpp_subscription_options_t *	options
	)

phase-456 W1 — the same registration, with the callback's CAPTURE held by the ARENA rather than by the caller.

The difference is the lifetime, not the dispatch. ..._register above passes context through untouched, so the caller must keep whatever it points at alive AND unmoved for as long as the executor runs — which is why a callback-style entity was immovable after registration, and why the returning create_subscription had to heap-allocate a cell to give a capturing lambda a stable address.

Here the first capture_len bytes at capture are COPIED into the arena entry and the dispatch context becomes the entry's own copy. Nothing of the caller's is referenced after the call returns, so the caller may keep nothing at all — which is what lets the C++ object become a handle.

capture_len is a LENGTH, not a budget — phase-456 W8. W1 copied the capture into a fixed [u8; CALLBACK_CAPTURE_BYTES] and refused anything longer, where that constant had to equal NROS_CPP_CALLBACK_CAPACITY by construction — so the refusal was reachable only when the two languages had drifted apart about a number. The runtime now allocates exactly capture_len bytes from the arena, and the only bound left is the arena every other entry already shares.

nros_cpp_subscription_register_with_info()

nros_cpp_ret_t nros_cpp_subscription_register_with_info	(	const nros_cpp_node_t *	node,
		const char *	topic,
		const char *	type_name,
		const char *	type_hash,
		nros_cpp_qos_t	qos,
		nros_cpp_subscription_message_info_callback_t	callback,
		void *	context,
		size_t *	out_handle_id,
		const nros_cpp_subscription_options_t *	options
	)