Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions rclcpp/topics/minimal_subscriber/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,34 @@
# Minimal subscriber cookbook recipes

## Overview

This package demonstrates several ways to implement subscriber nodes in ROS 2 using `rclcpp`.

All examples subscribe to the same topic and print received messages to the console,
but they illustrate different architectural patterns and callback styles used
when designing ROS 2 applications.

The goal of these examples is to help developers understand the trade-offs between
different subscriber implementations and when each pattern might be useful.

## Message Flow

All examples follow the same communication structure:

Publisher Node
|
v
Topic (`std_msgs/msg/String`)
|
v
Subscriber Node
|
v
Subscription Callback

In ROS 2, publishers and subscribers communicate through topics using a
publish–subscribe communication model.

This package contains a few different strategies for creating nodes which receive messages:
* `lambda.cpp` uses a C++11 lambda function
* `member_function.cpp` uses a C++ member function callback
Expand All @@ -23,3 +52,22 @@ This is not a common use case in ROS 2 so this is not the recommended strategy t
This strategy makes sense in some specific situations, for example when the developer needs to have more control over callback order execution, to create custom triggering conditions or to use the timeouts provided by the wait-sets.

The example `content_filtering.cpp` shows how to use the content filtering feature for Subscriptions.

## When to Use Each Example

Although all examples create a subscriber that receives messages from the same topic,
they demonstrate different implementation patterns that may be useful in different
situations when developing ROS 2 systems.

| Example | Pattern | Typical Use Case |
|---------|---------|------------------|
| `lambda.cpp` | Lambda callback | Simple nodes where a short inline callback is sufficient |
| `member_function.cpp` | Class-based node | Recommended structure for larger ROS 2 systems because it improves modularity and code organization |
| `not_composable.cpp` | Non-subclassed node | Demonstrates a ROS 1 style pattern; generally discouraged for modern ROS 2 applications |
| `wait_set_subscriber.cpp` | WaitSet polling | Useful when explicit control over callback execution order is required |
| `static_wait_set_subscriber.cpp` | Static WaitSet | Optimized wait set usage for systems with fixed communication structures |
| `time_triggered_wait_set_subscriber.cpp` | Timer-triggered polling | Useful when periodic checks are required alongside message handling |
| `content_filtering.cpp` | Content filtering | Allows subscribers to receive only messages matching specific criteria |

In most real ROS 2 applications, the **class-based node approach (`member_function.cpp`)**
is commonly used because it improves modularity, testability, and maintainability.