autoware_agnocast_wrapper

The purpose of this package is to integrate Agnocast, a zero-copy middleware, into each topic in Autoware with minimal side effects. Agnocast is a library designed to work alongside ROS 2, enabling true zero-copy publish/subscribe communication for all ROS 2 message types, including unsized message types.

• Agnocast Repository: https://github.com/autowarefoundation/agnocast
• Agnocast Documentation: https://autowarefoundation.github.io/agnocast_doc/main/
• Discussion on Agnocast Integration into Autoware: https://github.com/orgs/autowarefoundation/discussions/5835
• Review Guide for Agnocast Wrapper PRs

This package provides macros that wrap functions for publish/subscribe operations and smart pointer types for handling ROS 2 messages. When Autoware is built using the default build command, Agnocast is not enabled. However, setting the environment variable ENABLE_AGNOCAST=1 enables Agnocast and results in a build that includes its integration. This design ensures backward compatibility for users who are unaware of Agnocast, minimizing disruption.

Two Integration Approaches

This package provides two approaches for integrating Agnocast. Both will coexist for the foreseeable future.

1. Node Wrapper (agnocast_wrapper::Node)

Use this when you want the entire node to transparently switch between rclcpp::Node and agnocast::Node at runtime. The node wrapper automatically selects the correct underlying implementation based on the ENABLE_AGNOCAST environment variable.

agnocast_wrapper::Node does not publicly derive from rclcpp::Node. It exposes a curated subset of the rclcpp::Node surface and forwards each member to the underlying implementation (rclcpp::Node or agnocast::Node). The member names and argument lists are identical in both builds (ENABLE_AGNOCAST=0 and =1), so a node written against it compiles unchanged either way — provided you spell the handle, options and message types with the AUTOWARE_* macros (see Type spellings). If you need an API that is not listed below, extend the wrapper, or reach the underlying node via get_rclcpp_node() (declared in both builds, but it throws when the node is in Agnocast mode — see the build-modes table).

Supported API surface

The following members / free functions are provided. Unless noted, signatures mirror their rclcpp::Node counterparts.

OnSetParametersCallbackType is aliased in this namespace and resolves to the correct rclcpp type for both Humble (rclcpp 16.x) and Jazzy (rclcpp 28+).

Polling subscribers are not a Node member. Use the free function polling::create_polling_subscriber<MessageT>(node, topic, qos) — see Polling Subscriber.

Reading another node’s parameters is not a Node member either. Use autoware::agnocast_wrapper::AsyncParametersClient, which takes a Method 2 node. Of the parameter service calls it exposes only get_parameters(), alongside wait_for_service() and service_is_ready(); the setter, descriptor and listing calls are not wrapped yet, and on_parameter_event() has no Agnocast counterpart. On the Agnocast backend the response arrives over an Agnocast subscription, so get_parameters() resolves its future only while an Agnocast executor spins the node.

create_client() and create_service() also accept an rmw_qos_profile_t. This is not part of the supported surface: it exists so that Humble-era call sites passing rmw_qos_profile_services_default keep compiling, and it will be removed. Pass an rclcpp::QoS.

Type spellings

The member names and argument lists above are the same in both builds, but the handle, options and message types they use are not the same C++ types. Always spell them with the AUTOWARE_* macros so the same source compiles in both builds:

A subscription callback may also take the plain MessageT::ConstSharedPtr; it needs no macro because it is spelled the same in both builds.

On the Agnocast path an owning handle must not outlive the subscription that delivered it. This covers AUTOWARE_MESSAGE_CONST_SHARED_PTR, a callback taking MessageT::ConstSharedPtr, the pointer returned by polling::take_data(), and AUTOWARE_CLIENT_RESPONSE_PTR, which the client delivers through a response subscription of its own and which therefore must not outlive the client. Reading it afterwards can return recycled memory, and releasing it can abort the process. Members are destroyed in reverse declaration order, so declare the subscription before any member that caches a message:

AUTOWARE_SUBSCRIPTION_PTR(PointCloud2) sub_;   // declared first -> destroyed last
std::shared_ptr<const PointCloud2> latest_;    // destroyed first -> safe

AUTOWARE_CLIENT_PTR(SrvT) client_;             // same rule for a cached client response
std::shared_ptr<const SrvT::Response> cached_;

The DDS path lets the same pointer be held indefinitely, so a node validated only with ENABLE_AGNOCAST=0 will not show the problem.

AUTOWARE_CLIENT_PTR(S) / AUTOWARE_SERVICE_PTR(S) and the AUTOWARE_CLIENT_*FUTURE* macros resolve to the wrapper’s own Client<S> / Service<S> types in both builds, so client and service code needs no

File truncated at 100 lines see the full file

Changelog for package autoware_agnocast_wrapper

1.9.0 (2026-06-24)

• Merge remote-tracking branch 'origin/main' into tmp/bot/bump_version_base

• refactor(autoware_agnocast_wrapper): split service ptr macros into server/client variants (#1205)

  * refactor(autoware_agnocast_wrapper): split service ptr macros into server/client variants

  • Apply feedback review

  * Remove const from is_shared_ptr_service_callback_v ---------

• feat(autoware_agnocast_wrapper): add overload for service (#1203)

  • add create_service overload
  • add assert

  * fix copilot review ---------

• feat(autoware_agnocast_wrapper): add service and client support (#1074)

  • Add service and client support to agnocast wrapper
  • Mark service and client support as experimental in README
  • Add missing macros
  • Fix colcon flag typo in README
  • fix
  • style(pre-commit): autofix
  • fix
  • style(pre-commit): autofix
  • Add a comment
  • Adjust create_service/create_client calls depending on rclcpp version
  • fix cpplint errors
  • style(pre-commit): autofix
  • Fix type deduction in create_client and create_service
  • Add functional header
  • Fix cpplint errors
  • Remove experimental tag
  • Add RCLCPP version check for client and service macros

  * Propagate exception in client async callbacks ---------Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Koichi Imai <<koichi.imai.2@tier4.jp>> Co-authored-by: Koichi Imai <<45482193+Koichi98@users.noreply.github.com>>

• feat(autoware_agnocast_wrapper): support more args for synchronizer (#1104) support 8 args

• feat(autoware_agnocast_wrapper): adopt glog to agnocast main templete (#1180) feat(autoware_agnocast_wrapper): use glog (#88)

  • feat: use glog
  • fix: tag name
  • feat: link glog
  • fix

  * fix: add ament auto library ---------

• fix(autoware_agnocast_wrapper): get_name,namespace,get_fully_qualified_name (#1178) fix get_name,namespace,get_fully_qualified_name

• feat(autoware_agnocast_wrapper): spawn agnocast_discovery_agent from launch wrapper (#1084) Spawn exactly one agnocast_discovery_agent per ros2 launch tree from agnocast_env.launch.{py,xml} when ENABLE_AGNOCAST=1, deduplicated tree-wide via the LaunchContext globals and pinned to namespace="/".

• feat(autoware_agnocast_wrapper): add ON_NODE macros (#1170)

• feat(autoware_agnocast_wrapper): update [agnocast_env.launch]{.title-ref} to enable override [use_agnocast]{.title-ref} (#1123)

  • update agnocast_env.launch to override use_agnocast
  • style(pre-commit): autofix

  * more description in README ---------Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

File truncated at 100 lines see the full file