Communication Patterns Overview

HORUS provides two communication primitives that cover all robotics messaging needs:

Pattern	Purpose	Example
Topic	Streaming data (pub/sub)	Sensor readings, motor commands, video frames
Action	Long-running tasks (goal/feedback/result)	Navigation, arm motion, calibration

Both work locally (shared memory) and across machines (network transport via configuration).

Topic: Streaming Pub/Sub

Topic<T> is the primary communication primitive. It provides ultra-fast pub/sub with automatic optimization — ~3ns to ~167ns latency depending on topology.

use horus::prelude::*;

let pub_topic: Topic<f32> = Topic::new("sensor.temperature")?;
pub_topic.send(25.3);

let sub_topic: Topic<f32> = Topic::new("sensor.temperature")?;
if let Some(temp) = sub_topic.recv() {
    hlog!(info, "Temperature: {}", temp);
}

Scenario	Latency
Same thread	~3ns
Same process	~18-36ns
Cross-process	~50-167ns

The backend is auto-selected based on topology and participant count. Communication paths upgrade transparently at runtime as participants join.

For full Topic API details, see Topic Communication.

Action: Long-Running Tasks

Actions handle tasks that take time to complete and benefit from progress feedback and cancellation. They follow the Goal / Feedback / Result pattern.

For full Action API details, see Actions.

When to Use What

Scenario	Use	Why
Sensor data streaming	Topic	Continuous data, latest value matters
Motor commands	Topic	High frequency, low latency
Camera frames	Topic	Streaming, multiple consumers
Navigate to position	Action	Long-running, needs progress feedback
Pick-and-place	Action	Multi-step, cancellable
Calibration routine	Action	Takes time, reports progress
Emergency stop	Topic	Must be instantaneous, no handshake
Diagnostics broadcast	Topic	Many publishers, flexible topology

Rule of thumb: If it's a continuous stream of data, use Topic. If it's a task you'd want to start, monitor, and potentially cancel, use Action.

Composing Patterns

A typical robot system combines both patterns:

struct NavigationSystem {
    // Topics for streaming sensor data
    lidar_sub: Topic<LaserScan>,
    odom_sub: Topic<Odometry>,

    // Topics for publishing commands
    cmd_vel_pub: Topic<Twist>,
    status_pub: Topic<Status>,

    // Action server for goal-based navigation
    nav_server: ActionServerNode<NavigateToGoal>,
}

The navigation action server subscribes to sensor topics internally, computes a path, publishes velocity commands via topics, and reports progress back to the action client — all using the same underlying shared memory infrastructure.

Next Steps

Topic Details - Architecture and design patterns
Topic API Reference - Full method documentation
Actions - Goal/feedback/result pattern
Services - Synchronous request/response RPC