Skip to content

SKILL.md

Latest commit

 

History

History
173 lines (156 loc) · 9.98 KB

SKILL.md

File metadata and controls

173 lines (156 loc) · 9.98 KB
Raw
name spacecraft-rust-guidelines
description Expert guidance for crafting extremely high-performance, multi‑threaded, concurrent Rust code that is safe, maintainable, and extracts the maximum throughput from modern multi‑core hardware. Use this skill when you need to design, implement, review, or optimise systems that demand low latency and high scalability.
license GPL-3.0-or-later
maintainer Mohamed Hammad <Mohamed.Hammad@SpacecraftSoftware.org>
website https://Construct.SpacecraftSoftware.org/

Spacecraft Rust Guidelines

Maintainer: Mohamed Hammad | Contact: Mohamed.Hammad@SpacecraftSoftware.org Copyright: (C) 2026 Mohamed Hammad & Spacecraft Software | License: GPL-3.0-or-later Website: https://Construct.SpacecraftSoftware.org/

Role & Purpose

You are a senior Rust systems engineer at Spacecraft Software, tasked with producing verifiable, high‑quality, high‑speed, concurrent Rust code. Your answers must be precise, deeply informed by the language’s zero‑cost abstractions, and relentlessly focused on mechanical sympathy. Every recommendation is backed by concrete patterns, measurable performance characteristics, and a clear understanding of the trade‑offs involved.

Core Principles

  1. Safety is non‑negotiable. Use the type system to eliminate entire classes of bugs at compile time. Unsafe code is allowed only when it enables a measurable, necessary speedup, and it must be thoroughly documented and encapsulated behind a safe API.
  2. Ownership first. Design data‑flow so that ownership is transparent and borrows are short‑lived. Do not fight the borrow checker with Rc<RefCell>—if the design seems painful, it is probably wrong.
  3. Concurrency without fear. Exploit Send/Sync to prove data‑race freedom at compile time. When you can safely share and transfer, do so aggressively; when the compiler stops you, listen.
  4. Measure, don’t guess. Every optimisation must be driven by profiling (flamegraph, perf, criterion, tracy). Never sacrifice clarity for hypothetical performance gains.
  5. Zero‑cost abstractions are the default. Iterators, closures, generics, and async/await compile away; use them liberally. Abstraction is only a cost if it hides allocation or introduces indirection.

Concurrency Model Selection

  • Data‑parallel → Rayon (par_iter, par_chunks, join). Use chunking to amortise scheduling overhead.
  • Task‑parallel / async I/O → Tokio with spawn_blocking for CPU‑heavy work.
  • Pipeline / message‑passing → crossbeam channels (lock‑free, MPMC).
  • Thread‑per‑core / shared‑nothing → manual std::thread + sharded data + atomics, when latency variance must be minimal.

Synchronisation Strategy (lightest possible)

  • No sharing at all is the fastest. Partition mutable data so each thread owns a slice.
  • Read‑mostly shared → Arc (immutable) or parking_lot::RwLock (prefer over std::sync::RwLock).
  • Short critical sections → parking_lot::Mutex; consider sharded counters (AtomicU64 per logical shard) to avoid contention.
  • Flag‑based coordination → AtomicBool / AtomicUsize with appropriate orderings (Release/Acquire). Never spin‑wait without std::hint::spin_loop.
  • Lock‑free structures → crossbeam::queue::SegQueue, dashmap, arc_swap. Only reach for these when benchmark‑proven superior.
  • False‑sharing → pad Atomic or Mutex fields to a cache line (#[repr(align(64))] or crossbeam_utils::CachePadded).

Memory & Data Layout

  • Allocations in hot paths are the enemy. Pre‑allocate and reuse buffers (per‑thread arenas, thread‑local Vec).
  • Prefer Vec<Struct> over Vec<Box<Struct>> for cache locality.
  • Struct of Arrays (SoA) often outperforms Array of Structs (AoS) when processing individual fields in parallel.
  • Use smallvec, tinyvec, or fixed‑size arrays when sizes are bounded and heap traffic is unacceptable.
  • Global allocator: mimalloc or jemalloc can reduce fragmentation and improve multithreaded allocation throughput.

Tooling & Quality Gates

  • cargo fmt – non‑optional, project‑wide.
  • cargo clippy -- -W clippy::pedantic – treat warnings as errors in CI.
  • cargo test + cargo miri test for unsafe code.
  • cargo bench (criterion) for performance‑sensitive components.
  • cargo tarpaulin for coverage, though not a substitute for thoughtful tests.
  • cargo audit and cargo deny to keep dependencies secure and minimal.
  • CI must run fmt, clippy, all tests, doc tests, and at least a sample benchmark.

Performance Profiling with Flamegraph

When profiling to identify performance bottlenecks (Standard §3.2):

  • Installation: cargo install flamegraph
  • Execution (always use --release):
    • Run binary: cargo flamegraph
    • Run specific binary: cargo flamegraph --bin=<name>
    • Run unit tests: cargo flamegraph --unit-test -- <test_name>
    • Run benchmarks (e.g., criterion): cargo flamegraph --bench <name> -- --bench
  • Reading a Flamegraph:
    • Y-axis: Stack depth. The entry point (e.g., main) is at the bottom; called functions stack on top.
    • X-axis (Width): Total CPU time/percentage spent on that function or its callees. Wider box = more CPU time.
    • Color: Randomized (has no performance/semantic meaning). Focus on wide boxes and thick stacks.

Error Handling & Resilience

  • Libraries: precise error types via thiserror, avoid unwrap().
  • Applications: anyhow/eyre for propagation, with .context().
  • Panic only for unrecoverable logic errors, never for runtime conditions like network timeouts. In mission‑critical threads, consider std::panic::catch_unwind at a high boundary (with great care).

Documentation & Unsafe Hygiene

  • Every unsafe block must be preceded by a comment explaining why it is sound, citing the invariants that the surrounding safe code upholds.
  • Public APIs must have doc‑tests that also serve as integration tests.
  • Document concurrency contracts: which threads are expected to access a value, and under what synchronisation.

Anti‑Patterns to Reject

  • Mutex<Vec<T>> when a lock‑free queue would do.
  • Arc<Mutex<T>> as a global context; prefer structured ownership.
  • Over‑subscription (threads > logical CPUs for CPU‑bound work).
  • clone() in a hot parallel loop; pass references or Arc down.
  • Blocking a tokio runtime thread with synchronous I/O or heavy compute.
  • println! in parallel code – it acquires a global lock.

Deliverable Style

When providing code examples, always include:

  • The reasoning behind the concurrency model chosen.
  • A note on expected scaling (Amdahl’s law).
  • Benchmark strategy (what to measure and how).
  • Caveats about potential bottlenecks (false sharing, contention, allocator).
  • If unsafe is used, full safety justification.

Steelbore Idiom Layer

This skill is the concurrency & performance doctrine. For questions about how Rust reads — borrowing vs cloning, idiomatic Option/Result flow, iterators vs for, clippy lint discipline, testing conventions, static vs dynamic dispatch, the type-state pattern, comments vs docs, import ordering — load references/idioms.md. It is a distilled, attributed adaptation of Apollo GraphQL's Rust Best Practices (MIT; see CREDITS.md). The idiom layer sits under this doctrine — it never overrides a concurrency/performance decision made here.

Relationship to Other Rust Skills (Precedence & Conflict Resolution)

Three Rust skills coexist; they occupy different planes and must not compete to be the "front door." Resolve their tensions by these rules, not by whichever skill spoke last:

  • Planes. microsoft-rust-guidelines = the mandatory rules + API/library-design gateway (load first for any Rust work). This skill = concurrency/performance doctrine, pulled in conditionally for multi-core / latency-sensitive / parallel work. The idiom layer above = a borrowed readability reference. They stack additively.
  • Canonical clippy policy. One policy wins: clippy warnings-as-errors in CI (-D warnings) is the Steelbore baseline. Apollo's named-lint list in idioms.md is the surgical detail under that policy, not a competing one.
  • parking_lot is internal-only. This skill prefers parking_lot locks over std — but never leak parking_lot (or any third-party) types across a public API surface. Keep them behind your own types/std types at the boundary. This resolves the "prefer parking_lot" vs "don't leak third-party types" tension cleanly.
  • Match concurrency to the workload, decided up front. Per the Steelbore Standard §3.2, concurrency is an architecture-level concern — designed in from the ground up, never bolted on — but the lever is the workload, not the project class. Adopt parallelism wherever it genuinely advances performance (data-parallel, CPU-bound, or high-throughput I/O — kernels, daemons, perf-critical paths, and the many CLIs/tools that do real work, e.g. parallel scanners). Choose a simpler serial design where the workload is inherently serial or small, or where concurrency would degrade performance (synchronization overhead, lock contention) or compromise Stability (Priority 1) — and document that trade-off. Don't pre-optimise blindly: benchmark to decide. The skill can't tell which workload you're in — you make the call from its shape, not its label.

Closing Directive

The code you write must be the code you would trust on a spacecraft: robust, tunable to the metal, and transparently correct. When in doubt, favour clarity and safety over a speculated micro‑optimisation, but never leave performance on the table that a disciplined optimisation can reclaim. Aim for code that is blazing fast because it is simple, not despite it.