ROS 2 Agnocast

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

This middleware is based on the following paper and the corresponding prototype. The paper has been accepted to IEEE ISORC 2025 (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.

Table of Contents

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

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

For Users

Clone the repository

Since ROS packages under src/ such as agnocastlib are not yet distributed from the ROS build farm, a source build is currently required. Therefore, to perform the source build, first check out the specific version as follows:

git clone --branch 2.2.0 https://github.com/tier4/agnocast.git
cd agnocast

System Configuration

Agnocast uses POSIX message queues for inter-process notification. The following system parameters may need adjustment.

msg_max: Maximum number of messages per queue (Required)

Agnocast requires increasing the system limit for the maximum number of messages in a queue.

Temporary setting (Current session only):

sudo sysctl -w fs.mqueue.msg_max=256

Permanent setting:

echo "fs.mqueue.msg_max=256" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

queues_max: Maximum number of message queues system-wide (Optional)

Agnocast creates a message queue for each subscriber, so the total number of message queues grows with the number of topics and subscribers. The system default for queues_max is typically 256, which may not be sufficient for large-scale deployments.

You can check the current limit with:

cat /proc/sys/fs/mqueue/queues_max

If you encounter mq_open failed: No space left on device, you may need to increase this limit.

Temporary setting (Current session only):

sudo sysctl -w fs.mqueue.queues_max=1024

File truncated at 100 lines see the full file

Contributing to Agnocast

Thank you for your interest in contributing to Agnocast!

Pull Request Requirements

Version Update Labels (Required)

Every pull request must have exactly one of the following labels:

• need-major-update: User API breaking changes - requires MAJOR version update
• need-minor-update: Internal API breaking changes (heaphook/kmod/agnocastlib compatibility) - requires MINOR version update
• need-patch-update: Bug fixes and other changes - requires PATCH version update

Important notes:

• PRs without a version label or with multiple version labels will not be mergeable due to automated checks.
• PR Title Convention: If you need need-major-update or need-minor-update, please include this in the PR title as well.
  • Example: fix(foo)[needs major version update]: bar
  • Example: feat(baz)[needs minor version update]: qux
• Build Test Requirement: After receiving approval from reviewers, add the run-build-test label. The PR can only be merged after the build tests pass.

Versioning Rules

Agnocast follows a modified semantic versioning scheme:

MAJOR version (need-major-update)

Increment when you make breaking changes to the User API.

Examples:

• Changing public API function signatures
• Removing or renaming user-facing APIs
• Modifying behavior that affects users of the library

MINOR version (need-minor-update)

Increment when you make breaking changes to internal APIs or component compatibility.

This includes changes that affect compatibility between:

• heaphook
• kmod
• agnocastlib

Examples:

• Removing or renaming ioctl commands
• Modifying data structures used in ioctl interfaces
• Changing shared data structures between heaphook/kmod/agnocastlib
• Breaking changes to internal APIs not exposed to end users

PATCH version (need-patch-update)

Increment for bug fixes and other changes that don’t fall into the above categories.

Examples:

• Bug fixes
• Documentation updates
• Performance improvements (without API changes)
• Refactoring (without API changes)
• Test additions or improvements

Testing Requirements

Before submitting a PR, please ensure the following tests pass:

• Autoware (required)
• bash scripts/test/e2e_test_1to1 (required)
• bash scripts/test/e2e_test_2to2 (required)
• kunit tests (required when modifying the kernel module)

Questions?

If you’re unsure which version label to use, feel free to ask in the PR comments or open a discussion.