What is HORUS?

HORUS is a framework for building applications with multiple independent components that communicate through ultra-low-latency shared memory. Each component handles one responsibility, and they connect together to form complex systems.

The Core Idea

Instead of writing one monolithic program, you build:

• Independent Nodes - Each component is self-contained
• Connected by Topics - Nodes communicate through named channels
• Run by a Scheduler - HORUS manages execution order

Example: A robot control system might have:

• SensorNode (reads camera)
• VisionNode (detects objects)
• ControlNode (moves motors)
• SafetyNode (prevents collisions)

Each node runs independently, sharing data through topics like "camera.image", "detected.objects", "motor.commands".

Key Features

1. Low-Latency Communication

HORUS achieves ~3ns to ~167ns message latency through shared memory — up to 500x faster than traditional middleware. The system automatically selects the optimal communication path based on your topology (same-thread, same-process, or cross-process). No configuration needed.

This performance enables tight control loops and high-frequency data processing without introducing significant delay.

2. Clean APIs

HORUS provides idiomatic Rust APIs:

use horus::prelude::*;

// Create a publisher
let publisher: Topic<f32> = Topic::new("temperature")?;

// Create a subscriber
let subscriber: Topic<f32> = Topic::new("temperature")?;

// Send data
publisher.send(25.0);

// Receive data
if let Some(temp) = subscriber.recv() {
    println!("Temperature: {:.1}C", temp);
}

With the node macro:

node! {
    SensorNode {
        pub {
            temperature: f32 -> "temperature",
        }
        tick {
            self.temperature.send(25.0);
        }
    }
}

3. Built-in Developer Tools

# Create a new project
horus new my_project

# Run your application
horus run

# Monitor in real-time
horus monitor

The monitor displays:

• Running nodes
• Message flow between components
• Performance metrics (latency, throughput)
• Debugging information

4. Multi-Language Support

Python:

from horus import Node, Topic, Scheduler

class SensorNode(Node):
    def __init__(self):
        super().__init__("sensor")

    def init(self):
        self.temperature = Topic("temperature")

    def tick(self):
        self.temperature.send(25.0)

scheduler = Scheduler()
scheduler.node(SensorNode()).order(0).build()
scheduler.run()

Rust: Full framework capabilities for performance-critical code.

Python and Rust nodes can communicate in the same application.

Core Concepts

Nodes

A Node is a component that performs a specific task. Examples:

• Read data from a sensor
• Process information
• Control a motor
• Display data on screen
• Monitor system health

Node lifecycle:

1. init() - Start up (optional, run once)
2. tick() - Do work (runs repeatedly)
3. shutdown() - Clean up (optional, run once)

impl Node for MySensor {
    fn name(&self) -> &str { "MySensor" }

    fn init(&mut self) -> Result<()> {
        hlog!(info, "Sensor starting up");
        Ok(())
    }

    fn tick(&mut self) {
        // Read sensor, send data - runs repeatedly
    }

    fn shutdown(&mut self) -> Result<()> {
        hlog!(info, "Sensor shutting down");
        Ok(())
    }
}

Topics

A Topic is a named channel for sending messages. Multiple publishers can send to a topic, and multiple subscribers can receive from it.

Topic naming conventions:

• Use descriptive names: "temperature", "camera.image", "motor.speed"
• Use dots for hierarchy: "sensors.imu.accel", "actuators.left_wheel"

// Node A publishes temperature
let pub_a: Topic<f32> = Topic::new("temperature")?;
pub_a.send(25.0);

// Node B also publishes temperature
let pub_b: Topic<f32> = Topic::new("temperature")?;
pub_b.send(30.0);

// Node C receives from both
let sub: Topic<f32> = Topic::new("temperature")?;
if let Some(temp) = sub.recv() {
    println!("Got: {}", temp);
}

Type safety: The type parameter (<f32>) ensures publishers and subscribers use the same message type. The compiler prevents type mismatches at compile time.

Note: HORUS supports both typed messages (Pose2D, CmdVel, etc.) and generic messages (dicts/JSON in Python). Typed messages provide better performance and type safety. See Message Types for details.

Scheduler

The Scheduler runs nodes in priority order:

let mut scheduler = Scheduler::new();

// Add nodes with order (lower number = runs first)
scheduler.add(SensorNode::new()?).order(0).build()?;   // Runs first
scheduler.add(ProcessNode::new()?).order(1).build()?;  // Runs second
scheduler.add(DisplayNode::new()?).order(2).build()?;  // Runs third

// Run (Ctrl+C to stop)
scheduler.run()?;

Execution order:

1. All order 0 nodes tick first
2. Then all order 1 nodes tick
3. Then all order 2 nodes tick
4. Repeat

Use order to control data flow:

• Sensors should run before processors (lower order number)
• Processors should run before actuators
• Safety checks should run first (order 0)

When to Use HORUS

Suitable Applications

Multi-component applications - Isolated components that communicate:

• Robot control systems
• Real-time data processing pipelines
• Multi-sensor fusion systems
• Parallel processing workflows

Real-time systems - When latency matters:

• Control loops (motor control, flight control)
• High-frequency data processing
• Live audio/video processing

Single-machine distributed systems - Multiple processes on one machine:

• Embedded Linux systems (Raspberry Pi, Jetson)
• Edge computing devices
• Multi-core applications

Hardware integration - Combining multiple devices/languages:

• Mix Rust (performance) + Python (ease of use)
• Integrate Python prototypes with production Rust

Robotics Scenarios

Less Suitable Applications

Simple single-script programs — If your program fits in 100 lines, HORUS adds unnecessary complexity.

Internet-scale distributed systems — HORUS is optimized for single-machine shared memory IPC, not WAN/internet communication. For cross-machine communication, use gRPC, HTTP, or message queues.

CRUD web applications — Use web frameworks (Axum, Actix, Django, Flask) instead.

Bare-metal embedded systems — HORUS requires an operating system with shared memory support. For microcontrollers, use RTIC or Embassy.

Pure simulation — Use standalone simulators for pure simulation needs.

Comparison with Other Frameworks

vs Monolithic Programs

Traditional approach:

fn main() {
    loop {
        let temp = read_sensor();
        let filtered = process(temp);
        display(filtered);
    }
}

Issues:

• Difficult to test individual parts
• Changes can break everything
• Components cannot be reused
• No parallelization

HORUS approach:

// SensorNode - reusable, testable, independent
struct SensorNode { data_pub: Topic<f32> }

// ProcessNode - can swap implementation
struct ProcessNode { data_sub: Topic<f32>, processed_pub: Topic<f32> }

// DisplayNode - can replace with LogNode, etc.
struct DisplayNode { data_sub: Topic<f32> }

Benefits:

• Test each node independently
• Change one node without affecting others
• Reuse nodes across projects
• Nodes can run in parallel

vs ROS (Robot Operating System)

Use ROS when: You need cross-machine communication or extensive robotics libraries.

Use HORUS when: You need high performance on a single machine.

vs Message Queues (RabbitMQ, Kafka)

Use message queues when: You need multi-machine communication, persistence, or reliability guarantees.

Use HORUS when: You need high speed on a single machine.

Architecture Overview

Data flow:

1. Nodes communicate via Topics
2. Topics write/read from shared memory
3. Scheduler orchestrates node execution
4. Monitor displays system status in real-time

Technical Details

Performance Characteristics

IPC Latency:

• Same-thread: ~3ns
• Same-process: ~18-36ns
• Cross-process: ~50-167ns

Throughput:

• Small messages (<1KB): 2M+ msgs/sec
• Large messages (1MB): Limited by memory bandwidth

Memory Usage:

• Framework overhead: ~2MB
• Per topic: Auto-sized based on message type (~73KB to ~8MB)
• Per node: Depends on implementation

Built in Rust

HORUS leverages Rust for:

Safety - Compile-time guarantees:

• No null pointer dereferences
• No data races
• No use-after-free bugs

Performance - Zero-cost abstractions:

• No garbage collection pauses
• Predictable memory layout
• LLVM optimizations

Concurrency - Fearless concurrency:

• Send/Sync traits prevent data races
• Ownership prevents sharing mutable state

Learning Path

Start here:

1. Installation - Get HORUS installed
2. Quick Start - Build your first app
3. Basic Examples - Working examples

Core concepts: 4. Nodes - Build components 5. Topic - Pub/sub communication 6. Scheduler - Run your application

Practical features: 7. node! Macro - Reduce boilerplate 8. Monitor - Monitor and debug

Advanced: 9. Multi-Language - Python integration 10. Performance - Optimization 11. Examples - Real projects

Next Steps

1. Install HORUS - Get up and running
2. Quick Start Tutorial - Build your first application
3. See Examples - Learn from real projects

For command reference, see CLI Reference. For architecture details, see Architecture.