agnocast

ROS 2 Agnocast

An rclcpp-compatible true zero-copy IPC middleware that supports all ROS message types, including message structs already generated by rosidl.

Agnocast is based on the following papers and the corresponding prototype. It also integrates CallbackIsolatedExecutor.

• T. Ishikawa-Aso, A. Yano, T. Azumi, and S. Kato, “Work in Progress: Middleware-Transparent Callback Enforcement in Commoditized Component-Oriented Real-time Systems,” in Proc. IEEE Real-Time and Embedded Technology and Applications Symposium (RTAS), 2025, pp. 78–81. IEEE Xplore (pdf).
• T. Ishikawa–Aso and S. Kato, “ROS 2 Agnocast: Supporting Unsized Message Types for True Zero-Copy Publish/Subscribe IPC,” in Proc. 28th Int. Symp. Real-Time Distributed Computing (ISORC), 2025, pp. 1–10. IEEE Xplore (pdf).
• T. Ishikawa–Aso, A. Yano, K. Imai, T. Azumi, and S. Kato, “ipc_shared_ptr: A Publish/Subscribe-Aware Smart Pointer for Cross-Process Object Lifetime Management,” in Proc. 29th Int. Symp. Real-Time Distributed Computing (ISORC), 2026 (to appear). arXiv:2605.04226 (pdf).

@inproceedings{ishikawa2025cie,
  title={Work in Progress: Middleware-Transparent Callback Enforcement in Commoditized Component-Oriented Real-time Systems},
  author={Ishikawa-Aso, Takahiro and Yano, Atsushi and Azumi, Takuya and Kato, Shinpei},
  booktitle={2025 IEEE Real-Time and Embedded Technology and Applications Symposium (RTAS)},
  pages={78--81},
  year={2025},
  organization={IEEE}
}

@inproceedings{ishikawa2025agnocast,
  title={ROS 2 Agnocast: Supporting Unsized Message Types for True Zero-Copy Publish/Subscribe IPC},
  author={Ishikawa-Aso, Takahiro and Kato, Shinpei},
  booktitle={2025 28th International Symposium on Real-Time Distributed Computing (ISORC)},
  pages={01--10},
  year={2025},
  organization={IEEE}
}

@inproceedings{ishikawa2026agnocast,
  title={ipc\_shared\_ptr: A Publish/Subscribe-Aware Smart Pointer for Cross-Process Object Lifetime Management},
  author={Ishikawa-Aso, Takahiro and Yano, Atsushi and Imai, Koichi and Azumi, Takuya and Kato, Shinpei},
  booktitle={2026 29th International Symposium on Real-Time Distributed Computing (ISORC)},
  year={2026},
  note={to appear},
  organization={IEEE}
}

Talks:

• ROSCon 2025, Singapore: “Agnocast: A ROS 2-Compatible Middleware Enabling True Zero-Copy IPC for Unsized Message Types” by Takahiro Ishikawa-Aso (video)
• ROSCon JP 2025, Nagoya: “CallbackIsolatedExecutor: 二重スケジューリングを不要にする新しいExecutorとスケジューリング理論” by Takahiro Ishikawa-Aso (video, in Japanese; an English summary is available on the TIER IV tech blog)

Table of Contents

• Supported Environments
• For Users
• For Developers
• Debug
• Troubleshooting
• Documents

Supported Environments

Agnocast is currently available in the following environments. This reflects the current status, and support is expected to expand in the future.

For Users

For installation, setup, and usage instructions, please refer to the Getting Started Guide.

For Developers

Clone the repository

Clone the latest main branch for development:

git clone https://github.com/autowarefoundation/agnocast.git
cd agnocast

Setup

Run the setup script to install dependencies:

bash scripts/dev/setup.bash

Setup pre-commit

The following command allows clang-format, markdownlint, and KUNIT Test to be run before each commit.

python3 -m pip install pre-commit
python3 -m pip install --upgrade pre-commit identify
pre-commit install

If you want to disable pre-commit, please run pre-commit uninstall.

Build and insert kmod

Build.

bash scripts/dev/build_all.bash

Check if there is a libagnocast_heaphook.so in install/agnocastlib/lib.

$ ls install/agnocastlib/lib | grep libagnocast_heaphook
libagnocast_heaphook.so

Insert kernel module.

cd agnocast_kmod
sudo insmod agnocast.ko
sudo lsmod

Test

You can build, test and generate the coverage report by following:

bash scripts/test/test_and_create_report.bash

Kernel Module Test

A custom kernel with the following CONFIG enabled is required to run KUnit Test and obtain the coverage report (sample custom kernel is placed here).

• CONFIG_KUNIT=y
• CONFIG_GCOV_KERNEL=y

If booting with the custom kernel, the following script can be used to run unit tests on kernel modules and generate coverage reports.

bash scripts/test/run_kunit.bash

You can also use pre-commit

Debug

Check the kernel log.

sudo dmesg -w

To use dynamic_debug for dynamically outputting debug logs, please run the following command as super user:

sudo su
echo 'file agnocast_main.c +p' > /sys/kernel/debug/dynamic_debug/control

Check if dynamic_debug is enabled by running the following command. If the right side of the = is p, it is enabled. (If it’s _, it is disabled.)

sudo cat /sys/kernel/debug/dynamic_debug/control | grep "agnocast_main.c"
/.../agnocast/agnocast_kmod/agnocast_main.c:810 [agnocast]release_msgs_to_meet_depth =p "Release oldest message in the publisher_queue (publisher_pid=%d) of the topic (topic_name=%s) with qos_depth %d. (release_msgs_to_meet_depth)\012"
/.../agnocast/agnocast_kmod/agnocast_main.c:367 [agnocast]insert_message_entry =p "Insert an entry (topic_name=%s publisher_pid=%d msg_virtual_address=%lld timestamp=%lld). (insert_message_entry)"

To use dynamic_debug, the Linux kernel configuration must have CONFIG_DYNAMIC_DEBUG set to y. If CONFIG_DYNAMIC_DEBUG is not enabled in your environment, perform a debug build with:

make CFLAGS_agnocast.o="-DDEBUG"

Refer to the Linux kernel documentation on kbuild for more information about compilation flags.

Troubleshooting

Shared memory cleanup

Agnocast spawns a background daemon process that automatically cleans up shared memory when processes exit. It is forked by any Agnocast process that finds no daemon running, so the first process in an IPC namespace starts one, and so does the next process to start after the daemon is gone. The daemon inherits the parent’s process name, so broad kill commands like killall or kill -9 $(pgrep -f ...) may accidentally kill it along with application processes; cleanup then stops until an Agnocast process starts again, which spawns a replacement and unlinks what was left behind in the meantime.

If shared memory is left behind, you can remove it manually:

# Remove leftover shared memory
rm /dev/shm/agnocast@*

Documents

User-facing documentation (setup, migration guide, API reference, ros2 CLI) is on the Agnocast documentation site. The design documents below are for developers:

• shared memory
• Memory format in heaphook
• Clang-tidy Suppressions
• agnocast::Node and rclcpp::Node interface comparison
• Agnocast-ROS 2 Bridge Internal Design
• Message Filters Design Document
• ApproximateTime Algorithm