Skip to content

Commit f0a5e85

Browse files
committed
Remove internal type references from documentation
Update docs to match cleaned-up public API surface. Remove references to internal types (BackendMode, TopicRole, TopicConfig, RtKernelInfo, RtCpuInfo, LogEntry, SIMD_COPY_THRESHOLD, TensorPoolStats fields) and internal helper functions (pin_thread_to_core, detect_isolated_cpus, get_rt_recommended_cpus, prefault_stack). Fix import paths for RtScheduler and RtApplyResult which moved out of the prelude.
1 parent 057aa8e commit f0a5e85

8 files changed

Lines changed: 58 additions & 310 deletions

File tree

content/docs/advanced/rt-config.mdx

Lines changed: 16 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,11 @@ RtConfig is designed for **development on any OS** with **production deployment
1919
| **macOS** | Graceful degradation (no RT) | Development & testing |
2020
| **Windows** | Graceful degradation (no RT) | Development & testing |
2121

22-
On non-Linux platforms, `RtConfig::apply()` returns `RtApplyResult::Degraded` and your code continues running normally - just without kernel-level RT guarantees. This allows you to develop and test on any OS.
22+
On non-Linux platforms, `RtConfig::apply()` returns a degraded result and your code continues running normally - just without kernel-level RT guarantees. This allows you to develop and test on any OS.
2323

2424
```rust
25+
use horus::core::rt_config::RtApplyResult;
26+
2527
let config = RtConfig::hard_realtime(Some(&[2, 3]));
2628
match config.apply() {
2729
Ok(RtApplyResult::FullSuccess) => println!("Full RT enabled (Linux)"),
@@ -48,7 +50,7 @@ match config.apply() {
4850
## Quick Start
4951

5052
```rust
51-
use horus::prelude::*; // Provides RtConfig, RtScheduler
53+
use horus::prelude::*;
5254

5355
// Apply hard real-time configuration
5456
let config = RtConfig::hard_realtime(Some(&[2, 3])); // Pin to cores 2, 3
@@ -104,6 +106,7 @@ For fine-grained control:
104106

105107
```rust
106108
use horus::prelude::*;
109+
use horus::core::rt_config::RtScheduler;
107110

108111
let config = RtConfig::new()
109112
.memory_locked(true) // mlockall()
@@ -130,14 +133,14 @@ config.apply()?;
130133

131134
### Scheduling Classes
132135

133-
```rust
134-
pub enum RtScheduler {
135-
Normal, // Default Linux scheduler (SCHED_OTHER)
136-
Fifo, // SCHED_FIFO - First-in-first-out RT
137-
RoundRobin, // SCHED_RR - Round-robin RT
138-
Deadline, // SCHED_DEADLINE - For periodic tasks (not yet implemented)
139-
}
140-
```
136+
Available via `use horus::core::rt_config::RtScheduler`:
137+
138+
| Variant | Linux Scheduler | Description |
139+
|---------|----------------|-------------|
140+
| `Normal` | `SCHED_OTHER` | Default Linux scheduler |
141+
| `Fifo` | `SCHED_FIFO` | First-in-first-out RT |
142+
| `RoundRobin` | `SCHED_RR` | Round-robin RT |
143+
| `Deadline` | `SCHED_DEADLINE` | Periodic tasks (not yet implemented) |
141144

142145
| Class | Preemption | Use Case |
143146
|-------|------------|----------|
@@ -257,6 +260,8 @@ With full RT configuration on PREEMPT_RT kernel:
257260
`RtConfig` degrades gracefully when features aren't available:
258261

259262
```rust
263+
use horus::core::rt_config::RtApplyResult;
264+
260265
let config = RtConfig::hard_realtime(Some(&[2, 3]));
261266
match config.apply() {
262267
Ok(RtApplyResult::FullSuccess) => {
@@ -307,53 +312,6 @@ let cpus = RtConfig::get_current_affinity()?;
307312
println!("CPU affinity: {:?}", cpus);
308313
```
309314

310-
### Detect System RT Capabilities
311-
312-
```rust
313-
// Get detailed kernel RT information
314-
let info = RtKernelInfo::detect();
315-
println!("PREEMPT_RT: {}", info.preempt_rt);
316-
println!("Kernel: {}", info.kernel_version);
317-
println!("Max RT priority: {}", info.max_rt_priority);
318-
println!("mlockall permitted: {}", info.mlockall_permitted);
319-
println!("CPU count: {}", info.cpu_count);
320-
```
321-
322-
### Find Best CPUs for RT
323-
324-
```rust
325-
// Get recommended CPUs for RT tasks (prefers isolated + nohz_full cores)
326-
let rt_cpus = get_rt_recommended_cpus(2);
327-
println!("Recommended RT CPUs: {:?}", rt_cpus);
328-
329-
// Or get full CPU info
330-
let cpu_info = RtCpuInfo::detect();
331-
println!("{}", cpu_info.summary());
332-
```
333-
334-
## Helper Functions
335-
336-
HORUS provides standalone helper functions for common RT operations:
337-
338-
```rust
339-
use horus::prelude::*;
340-
341-
// Pin current thread to a single CPU core
342-
pin_thread_to_core(2)?;
343-
344-
// Detect kernel-isolated CPUs (from isolcpus boot parameter)
345-
let isolated = detect_isolated_cpus();
346-
347-
// Detect tickless CPUs (from nohz_full boot parameter)
348-
let nohz = detect_nohz_full_cpus();
349-
350-
// Get recommended CPUs for RT (prefers isolated+nohz_full, then isolated, etc.)
351-
let best_cpus = get_rt_recommended_cpus(2);
352-
353-
// Prefault stack memory to avoid page faults
354-
prefault_stack(512 * 1024); // 512KB
355-
```
356-
357315
## Troubleshooting
358316

359317
### "Operation not permitted" on mlockall
@@ -400,6 +358,7 @@ cat /sys/devices/system/cpu/isolated
400358

401359
```rust
402360
use horus::prelude::*;
361+
use horus::core::rt_config::{RtApplyResult, RtScheduler};
403362

404363
fn main() -> Result<()> {
405364
// Configure system for hard real-time

content/docs/concepts/communication-configuration.mdx

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -93,17 +93,16 @@ println!("Camera endpoint: {}", endpoint);
9393
// For direct: "sensor@192.168.1.5:9000"
9494
```
9595

96-
### Creating Topics from Config
96+
### Creating Topics
9797

9898
```rust
9999
use horus::prelude::*;
100100

101-
// Create a topic with TopicConfig
102-
let topic_config = TopicConfig::new("sensors").with_capacity(16);
103-
let topic: Topic<SensorData> = Topic::from_config(topic_config)?;
104-
105-
// Or create directly with Topic::new using the hub name
101+
// Create a topic using the hub name
106102
let topic: Topic<SensorData> = Topic::new("sensors")?;
103+
104+
// Or with custom capacity
105+
let topic: Topic<SensorData> = Topic::with_capacity("sensors", 32, None)?;
107106
```
108107

109108
## EndpointConfig Fields

content/docs/concepts/communication-transport.mdx

Lines changed: 2 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -117,15 +117,6 @@ let camera: Topic<Image> = Topic::new("camera")?;
117117

118118
## Topic Configuration
119119

120-
### From Config Struct
121-
122-
```rust
123-
use horus::prelude::*;
124-
125-
let config = TopicConfig::new("sensors").with_capacity(16);
126-
let topic: Topic<SensorData> = Topic::from_config(config)?;
127-
```
128-
129120
### Custom Capacity
130121

131122
```rust
@@ -172,7 +163,7 @@ mDNS allows nodes to discover each other without hardcoding IP addresses. This i
172163

173164
## Endpoint Configuration (Planned)
174165

175-
> **Note:** The endpoint configuration system (`HorusConfig`, `EndpointConfig`, transport types) is **planned but not yet implemented**. See [Communication Configuration](/concepts/communication-configuration) for the intended design. Currently, all topics use local shared memory via `Topic::new("name")` or `Topic::from_config(TopicConfig)`.
166+
> **Note:** The endpoint configuration system (`HorusConfig`, `EndpointConfig`, transport types) is **planned but not yet implemented**. See [Communication Configuration](/concepts/communication-configuration) for the intended design. Currently, all topics use local shared memory via `Topic::new("name")`.
176167
177168
## Summary
178169

@@ -183,7 +174,7 @@ mDNS allows nodes to discover each other without hardcoding IP addresses. This i
183174
| **Throughput** | 2.5M+ msgs/sec (SPSC), 1.5M+ msgs/sec (MPMC) |
184175
| **Backend Selection** | Automatic based on usage pattern |
185176
| **Platforms** | Linux (`/dev/shm`), macOS (`shm_open`), Windows (page file) |
186-
| **Configuration** | `Topic::new("name")` or `Topic::from_config(TopicConfig)` |
177+
| **Configuration** | `Topic::new("name")` or `Topic::with_capacity("name", N, None)` |
187178

188179
## Next Steps
189180

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

Lines changed: 0 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -306,19 +306,6 @@ Creates a topic with a custom ring buffer capacity. By default, HORUS auto-sizes
306306
let topic: Topic<f32> = Topic::with_capacity("velocity", 256, None)?;
307307
```
308308

309-
### from_config()
310-
311-
```rust
312-
pub fn from_config(config: TopicConfig) -> Result<Self>
313-
```
314-
315-
Creates a topic from a `TopicConfig` struct. Primarily used by Python bindings and config-file-based topic creation.
316-
317-
```rust
318-
let config = TopicConfig::new("velocity").with_capacity(128);
319-
let topic: Topic<f32> = Topic::from_config(config)?;
320-
```
321-
322309
## Type-Safe Topic Descriptors
323310

324311
The `topics!` macro defines compile-time topic descriptors that prevent topic name typos and type mismatches across your codebase.

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -123,12 +123,12 @@ The `with_logging()` method requires `T: LogSummary`. Use `#[derive(LogSummary)]
123123
2. Records `Instant::now()` before the IPC operation
124124
3. Performs the IPC send
125125
4. Calculates elapsed IPC time
126-
5. Publishes a `LogEntry` (timestamp, node name, tick number, topic, summary, IPC latency)
126+
5. Records a log entry with timestamp, node name, tick number, topic, summary, and IPC latency
127127

128128
**What `with_logging()` adds to `recv()`:**
129129
1. Records `Instant::now()` before the IPC operation
130130
2. Performs the IPC receive
131-
3. If a message was received, calls `msg.log_summary()` and publishes a `LogEntry`
131+
3. If a message was received, calls `msg.log_summary()` and records a log entry
132132

133133
**Latency:** +200-500ns overhead per operation
134134

content/docs/performance/performance.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -179,7 +179,7 @@ RUSTFLAGS="-C target-feature=+avx2" cargo build --release
179179

180180
SIMD acceleration automatically applies to:
181181

182-
- **Topic send/recv**: Message copying for messages >= 4KB (`SIMD_COPY_THRESHOLD`)
182+
- **Topic send/recv**: Message copying for messages >= 4KB
183183
- **Shared memory operations**: Large buffer transfers using non-temporal streaming stores
184184

185185
For messages smaller than 4KB, standard `ptr::copy_nonoverlapping` is used (setup overhead exceeds SIMD benefit for small copies).
@@ -194,7 +194,7 @@ Benchmarks on Intel Core i9-13900K (AVX2 enabled):
194194
| 304B (IMU) | ~280ns | ~160ns | 1.75x |
195195
| 1.5KB (LaserScan) | ~800ns | ~400ns | 2x |
196196

197-
> **Note**: SIMD acceleration applies to messages >= 4KB (`SIMD_COPY_THRESHOLD`). Smaller messages use standard `ptr::copy_nonoverlapping`. The latency improvements above are from the overall Topic pipeline, including cache-line alignment and lock-free algorithms.
197+
> **Note**: SIMD acceleration applies to messages >= 4KB. Smaller messages use standard `ptr::copy_nonoverlapping`. The latency improvements above are from the overall Topic pipeline, including cache-line alignment and lock-free algorithms.
198198
199199
### Fallback Behavior
200200

@@ -561,7 +561,7 @@ HORUS automatically tracks IPC timing for each topic operation. The `horus monit
561561
Tick: 12μs | IPC: 296ns
562562
```
563563

564-
Each `LogEntry` includes `tick_us` (node tick time in microseconds) and `ipc_ns` (IPC write time in nanoseconds).
564+
Each log entry includes `tick_us` (node tick time in microseconds) and `ipc_ns` (IPC write time in nanoseconds).
565565

566566
### Manual Profiling
567567

0 commit comments

Comments
 (0)