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).

<details> <summary>BibTeX</summary>

bibtex
@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}
}

</details>

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)

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.

Category	Supported Versions / Notes
ROS 2	Humble / Jazzy (only with `rclcpp` client library)
Linux Distribution	Ubuntu 22.04 (Jammy) / Ubuntu 24.04 (Noble)
Linux Kernel	5.x / 6.x series (detailed version matrix not yet available)

Warning: Agnocast service/client is not officially supported yet and the API may change in the future. Use at your own risk.

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:

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

Setup

Run the setup script to install dependencies:

bash
bash scripts/dev/setup.bash

Setup pre-commit

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

bash
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
bash scripts/dev/build_all.bash

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

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

Insert kernel module.

bash
cd agnocast_kmod
sudo insmod agnocast.ko
sudo lsmod

Test

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

bash
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
bash scripts/test/run_kunit.bash

You can also use pre-commit

Debug

Check the kernel log.

bash
sudo dmesg -w

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

bash
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.)

bash
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:

bash
make CFLAGS_agnocast.o="-DDEBUG"

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

Troubleshooting

Shared memory and message queue cleanup

Agnocast spawns a background daemon process (forked from the first Agnocast process) that automatically cleans up shared memory and message queues when processes exit. 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. If the daemon dies, cleanup stops and resources will leak. To avoid this, stop application processes individually (e.g., with Ctrl+C or by targeting specific PIDs).

If shared memory or message queues are left behind, you can remove them manually:

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

# Remove leftover message queues
rm /dev/mqueue/agnocast@*
rm /dev/mqueue/agnocast_bridge_manager@*

If you encounter mq_open failed: No space left on device, the system has reached the maximum number of message queues. Run the cleanup commands above, and if the error persists, increase the system-wide queues_max limit (e.g., sudo sysctl -w fs.mqueue.queues_max=1024). See System Configuration for details.