sm_multithread_test_1 - SMACC2 Multi-threaded Executor Demonstration

A reference implementation demonstrating SMACC2’s multi-threaded executor capability.

🎯 Addresses GitHub Issue #571: “Multithread executor example”

📋 Table of Contents

• What is This?
• Quick Start
• The Problem This Solves
• What You’ll Observe
• How It Works
• When to Use Multi-threaded Mode
• Important Limitations
• Code Deep Dive
• Build Instructions
• Troubleshooting
• Further Reading

What is This?

This state machine demonstrates SMACC2’s multi-threaded executor feature by running four concurrent timers with simulated work. The logs clearly show the difference between single-threaded and multi-threaded execution through thread IDs and overlapping timestamps.

Key Features:

• ✅ Multi-threaded ROS2 callback processing
• ✅ Visual demonstration of concurrency via logs
• ✅ Side-by-side comparison with single-threaded mode
• ✅ Comprehensive documentation of usage and limitations

Quick Start

Run Multi-threaded Version (Main Demo)

# Build the package
colcon build --packages-select sm_multithread_test_1

# Source the workspace
source install/setup.bash

# Launch multi-threaded version
ros2 launch sm_multithread_test_1 sm_multithread_test_1.launch.py

Run Single-threaded Version (For Comparison)

# Launch single-threaded version
ros2 launch sm_multithread_test_1 sm_multithread_test_1_single.launch.py

The state machine runs for 15 seconds then enters a terminal state. Press Ctrl+C to exit.

The Problem This Solves

Background

By default, SMACC2 uses a single-threaded executor where ROS2 callbacks (timers, subscribers, action clients) execute sequentially. This is simple and deterministic, but can be a bottleneck when:

• Multiple callbacks have significant processing time
• Callbacks involve I/O operations (network, disk, sensors)
• You want maximum throughput for concurrent operations

Solution

SMACC2 supports ROS2’s Multi-threaded Executor which allows callbacks to execute concurrently on multiple threads, improving throughput for I/O-bound and concurrent operations.

Enabling it is trivial – just one parameter change:

// Single-threaded (default)
smacc2::run<MyStateMachine>();

// Multi-threaded
smacc2::run<MyStateMachine>(smacc2::ExecutionModel::MULTI_THREAD_SPINNER);
                            //  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                            //  THIS IS THE ONLY CHANGE NEEDED!

What You’ll Observe

Multi-threaded Mode Output

``` [Timer-A] Tick 1 START (Thread: 12345678) - simulating 50ms work [Timer-B] Tick 1 START (Thread: 87654321) - simulating 100ms work ← Different thread! [Timer-A] Tick 1 END (Thread: 12345678) [Timer-C] Tick 1 START (Thread: 11223344) - simulating 150ms work ← Concurrent! [Timer-A] Tick 2 START (Thread: 12345678) - simulating 50ms work

File truncated at 100 lines see the full file