Skip to content

Commit b6be416

Browse files
committed
Remove deprecated API references and update error types
- Delete migration-zero-overhead.mdx (v0.2→v0.3 migration guide) - Remove OLD DESIGN sections and version references from zero-overhead-ipc - Update HorusError enum: remove Other, add Driver/Unsupported/Internal{}/Contextual{} - Remove send_logged()/recv_logged() mentions from message-types - Clean v0.3+ version references from topic and common-mistakes docs
1 parent fbe2cdf commit b6be416

7 files changed

Lines changed: 42 additions & 470 deletions

File tree

content/docs/concepts/core-concepts-topic.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -144,7 +144,7 @@ See [Communication Transport](/concepts/communication-transport) for detailed co
144144

145145
## Send and Receive
146146

147-
> **Note**: HORUS v0.3+ uses a [zero-overhead IPC architecture](/concepts/zero-overhead-ipc) where introspection is separated from the hot path. The `send()` and `recv()` methods have zero logging overhead.
147+
> **Note**: HORUS uses a [zero-overhead IPC architecture](/concepts/zero-overhead-ipc) where introspection is separated from the hot path. The `send()` and `recv()` methods have zero logging overhead.
148148
149149
### The send() Method
150150

content/docs/concepts/message-types.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -255,7 +255,7 @@ impl LogSummary for PointCloud {
255255
**Standard operation**:
256256
- `Topic::new("name")?` — zero-overhead, no logging, no `LogSummary` required
257257
- `Topic::new("name")?.with_logging()` — enables logging + metrics, requires `T: LogSummary`
258-
- Both use the same `send()`/`recv()` methods; there are no separate `send_logged()`/`recv_logged()` methods
258+
- Both use the same `send()`/`recv()` methods; logging behavior is configured at topic creation time
259259
- Implementing LogSummary is recommended so you can opt into logging when needed
260260

261261
**When logging is active**:

content/docs/concepts/zero-overhead-ipc.mdx

Lines changed: 3 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ order: 5
66

77
# Zero-Overhead IPC Architecture
88

9-
HORUS v0.3+ introduces a **zero-overhead IPC architecture** that separates introspection from the hot path. This design ensures that `send()` and `recv()` have minimal latency regardless of whether monitoring tools are attached.
9+
HORUS uses a **zero-overhead IPC architecture** that separates introspection from the hot path. This design ensures that `send()` and `recv()` have minimal latency regardless of whether monitoring tools are attached.
1010

1111
## Key Takeaways
1212

@@ -16,32 +16,9 @@ After reading this guide, you will understand:
1616
- How external tools monitor Topics without affecting performance
1717
- Performance characteristics of each backend
1818

19-
## The Problem: Introspection Overhead
19+
## Architecture: Separated Introspection
2020

21-
In traditional robotics frameworks, logging and timing are embedded in every message operation:
22-
23-
```rust
24-
// OLD DESIGN (embedded introspection)
25-
pub fn send(&self, msg: T, ctx: &mut Option<&mut NodeInfo>) -> HorusResult<()> {
26-
let start = Instant::now(); // +10-20ns
27-
28-
// Write to shared memory
29-
self.backend.push(msg)?;
30-
31-
let elapsed = start.elapsed(); // +10-20ns
32-
// Logging with hlog!
33-
c.record_ipc_latency(elapsed); // +50-100ns (logging)
34-
c.log_pub(&self.name, &msg); // +100-500ns (serialization)
35-
}
36-
Ok(())
37-
}
38-
```
39-
40-
This adds **170-640ns of overhead** to every message, even when no one is monitoring!
41-
42-
## The Solution: Separated Introspection
43-
44-
HORUS separates introspection from the hot path:
21+
HORUS separates introspection from the hot path. Traditional frameworks embed logging and timing in every message operation, adding 170-640ns of overhead even when no one is monitoring. HORUS avoids this entirely:
4522

4623
<MermaidDiagram
4724
chart={`%%{init: {'flowchart': {'padding': 20}}}%%
@@ -289,27 +266,6 @@ horus topic echo sensors
289266
horus monitor
290267
```
291268

292-
## Migrating from Old API
293-
294-
If you're upgrading from HORUS v0.2.x, see the [Migration Guide](/development/migration-zero-overhead).
295-
296-
**Quick summary:**
297-
298-
```rust
299-
// OLD (v0.2.x) - ctx parameter required
300-
topic.send(msg)?;
301-
topic.recv()
302-
303-
// NEW (v0.3+) - zero-overhead, infallible
304-
topic.send(msg);
305-
topic.recv()
306-
307-
// NEW - opt-in introspection (configure once at creation)
308-
let topic = Topic::new("name")?.with_logging();
309-
topic.send(msg); // logging happens automatically
310-
topic.recv() // logging happens automatically
311-
```
312-
313269
## Design Rationale
314270

315271
### Why Separate Introspection?
@@ -350,6 +306,5 @@ This provides:
350306
## Next Steps
351307

352308
- [Topic Communication](/concepts/core-concepts-topic) - Full Topic API reference
353-
- [Migration Guide](/development/migration-zero-overhead) - Upgrading from v0.2.x
354309
- [Benchmarks](/performance/benchmarks) - Detailed performance data
355310
- [Backend Selection](/concepts/communication-transport) - Choosing the right backend

content/docs/development/error-handling.mdx

Lines changed: 32 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -54,10 +54,12 @@ The main error type for all HORUS operations:
5454
| `AlreadyExists` | Resource already exists |
5555
| `ParseError` | Parsing errors |
5656
| `CommandFailed` | External command errors |
57+
| `Driver` | Driver-related errors |
5758
| `FeatureNotAvailable` | Feature not enabled |
5859
| `Unsupported` | Operation not supported on this platform |
59-
| `Internal` | Internal errors |
60-
| `Other` | Catch-all |
60+
| `Unsupported` | Operation not supported on this platform |
61+
| `Internal` | Internal errors with source location (`file`, `line`) |
62+
| `Contextual` | Error with preserved source chain |
6163

6264
## Creating Errors
6365

@@ -98,6 +100,30 @@ let err = Error::PermissionDenied("/dev/ttyUSB0".to_string());
98100
let err = Error::AlreadyExists("Session 'main' already exists".to_string());
99101
```
100102

103+
### Internal Errors with Source Location
104+
105+
Use the `horus_internal!()` macro to create internal errors that automatically capture file and line number:
106+
107+
```rust
108+
use horus::prelude::*;
109+
110+
// Captures file/line automatically
111+
return Err(horus_internal!("Unexpected state: {:?}", state));
112+
// Produces: Internal { message: "Unexpected state: ...", file: "src/foo.rs", line: 42 }
113+
```
114+
115+
### Contextual Errors with Source Chain
116+
117+
Use `.horus_context()` on Results to wrap errors with additional context while preserving the original error chain:
118+
119+
```rust
120+
use horus::prelude::*;
121+
122+
let config = load_file("robot.yaml")
123+
.horus_context("Failed to load robot configuration")?;
124+
// If load_file fails, produces: Contextual { message: "Failed to...", source: <original error> }
125+
```
126+
101127
## Error Propagation
102128

103129
### Using the `?` Operator
@@ -129,7 +155,8 @@ fn load_robot_config(path: &str) -> Result<Config> {
129155
| `std::num::ParseIntError` | `Error::ParseError` |
130156
| `std::num::ParseFloatError` | `Error::ParseError` |
131157
| `uuid::Error` | `Error::Internal` |
132-
| `anyhow::Error` | `Error::Other` |
158+
| `std::sync::PoisonError` | `Error::Internal` |
159+
| `anyhow::Error` | `Error::Internal` |
133160

134161
## Error Checking
135162

@@ -177,8 +204,8 @@ match result {
177204
// Good: Specific error with context
178205
return Err(Error::backend("IMU", "I2C read failed on register 0x3B"));
179206

180-
// Avoid: Generic error
181-
return Err(Error::Other("error".to_string()));
207+
// Avoid: Internal without context
208+
return Err(horus_internal!("something went wrong"));
182209
```
183210

184211
### 2. Add Context When Propagating

0 commit comments

Comments
 (0)