Omar SobhandClaude Opus 4.7
7b23f61632
Hand-authored skill catalog anchored to real 2026-07 versions:
- Rust 1.97.1 (stable), edition 2024
- React 19.2.7, Server Components + Actions
- TailwindCSS 4.3.3 (CSS-first config, Oxide engine)
- three.js r185 (WebGPURenderer stable, BatchedMesh matured)
- React Native 0.86 / Expo SDK 54+ (New Architecture default)
- cargo-nextest 0.9.140, gitleaks 8.20+, cargo-audit 0.21+
- Postgres 17 (18 in beta, don't rely on)
- CUDA Blackwell, Metal Apple7+, ROCm CDNA3
Ships 15 skills across the categories:
foundation/ workspace-repo-commit-protocol
small-focused-commits
tdd-red-green-refactor
code-review-checklist
int-xx-marker-protocol
decompose-int-items
rust/ write-rust-current-edition
rust-error-handling
cargo-test-driven-development
rust-async-tokio-idioms
backend/ postgres-migrations-forward-only
postgres-index-selection
api-pagination-day-1
frontend/ react-19-server-components
tailwind-v4-idioms
component-4-state-model
mobile/ expo-managed-vs-bare
rn-flashlist-perf
gpu/ gpu-coalescing-and-occupancy
roofline-model
threejs/ threejs-perf-and-teardown
security/ cargo-audit-workflow
secret-scanning-gitleaks
skills_loader.rs walks skills/**/*.md, parses YAML frontmatter
(name, description, when_to_use, tags), upserts via
skills_catalog::upsert_builtin. Idempotent per boot — bumps version
+ appends skill_versions row ONLY when body changes. Deterministic
sha256-derived ids so builtins are stable across boots.
Dockerfile copies skills/ to /etc/clawmates/skills. Server boot
task spawns loader alongside team_template_loader.
Follow-ups (Slice 3.5c continuation, future PRs):
- 20-30 more skills (duckdb, shadcn composition, a11y, WebGPU
migration, metal frame capture, rocprof, deep gitea forge
integration, semgrep rulepacks)
- Bind skills to team template roles (add [role.skills] refs to
templates/teams/*.toml + wire template_role_skills population
in team_template_loader)
Co-Authored-By: Claude Opus 4.7 <[email protected]>
64 lines
3.0 KiB
Markdown
64 lines
3.0 KiB
Markdown
---
|
|
name: rust-async-tokio-idioms
|
|
description: Tokio 1.x runtime idioms — spawn vs block_in_place, cancellation, channels, avoiding Arc<Mutex<T>> patterns.
|
|
when_to_use: You're writing async Rust code with Tokio. Applies to nearly all clawmates crates.
|
|
tags: [rust, async, tokio]
|
|
---
|
|
|
|
# Tokio async idioms
|
|
|
|
Anchored to **Tokio 1.x** (workspace tracks the latest 1.x line, currently ~1.42).
|
|
|
|
## Runtime choice
|
|
|
|
- **`#[tokio::main]`** in the binary. Default is multi-thread — fine.
|
|
- **`#[tokio::test]`** in tests. Default is current-thread (fast, deterministic). Add `flavor = "multi_thread"` when the code under test spawns.
|
|
- **NEVER** call `tokio::runtime::Handle::current().block_on(...)` inside async code — deadlocks in current-thread, breaks structured concurrency in multi-thread.
|
|
|
|
## Spawning
|
|
|
|
```rust
|
|
let handle = tokio::spawn(async move {
|
|
do_work().await
|
|
});
|
|
let result = handle.await??; // ?? = JoinError, then inner Result
|
|
```
|
|
|
|
- **`tokio::spawn`** for detached background work. Returns `JoinHandle`.
|
|
- **`tokio::task::spawn_blocking`** for CPU-heavy or blocking-syscall work (`std::fs`, `sync::Mutex`). Bounded pool — don't spawn thousands.
|
|
- **`tokio::task::spawn_local`** only inside a `LocalSet` — you almost never want this.
|
|
|
|
## Cancellation
|
|
|
|
- Dropping a `JoinHandle` DOES NOT cancel the task by default. Use `.abort()` or `CancellationToken`.
|
|
- Prefer `tokio_util::sync::CancellationToken` for structured cancel — pass the child token, call `parent.cancel()` at teardown.
|
|
- `tokio::select!` on `token.cancelled()` in every long-running loop.
|
|
|
|
## Channels
|
|
|
|
- **`mpsc::channel(cap)`** for actor-like state — one owner processes messages. Cap ≥ number of expected concurrent senders.
|
|
- **`oneshot::channel()`** for request/response. Sender is consumed on send.
|
|
- **`broadcast::channel(cap)`** for fan-out. Slow subscribers get `Lagged` errors — handle it.
|
|
- **`watch::channel(initial)`** for latest-value-wins state (config, health flags).
|
|
|
|
## Avoiding `Arc<Mutex<T>>`
|
|
|
|
Common trap: shared mutable state protected by a lock. Usually a smell.
|
|
|
|
- Immutable snapshot: `Arc<T>` is enough.
|
|
- Update-then-read cadence: `arc-swap::ArcSwap<T>` (lock-free).
|
|
- Actor-shaped: `mpsc::channel` + one task owning the state.
|
|
- Sync mutex needed AT ALL: use `std::sync::Mutex` (not `tokio::sync::Mutex`) for anything held < 1ms. Tokio's mutex is for holding across `.await`, which you should be actively avoiding.
|
|
|
|
## `.await` discipline
|
|
|
|
- Never `.await` inside a `std::sync::MutexGuard` scope — deadlock waiting to happen. Drop the guard first.
|
|
- Never `.await` inside a `tokio::task::block_in_place` block — it panics.
|
|
- `tokio::select! { biased; ... }` when you need branch order guarantees (usually shutdown-first).
|
|
|
|
## Anti-patterns
|
|
|
|
- **`futures::executor::block_on` inside a Tokio task.** Use `tokio::task::block_in_place` if you really need to sync-bridge.
|
|
- **`std::thread::sleep` in async code.** Use `tokio::time::sleep`.
|
|
- **Spawning from `Drop`.** `Drop` isn't async; the runtime may already be shutting down.
|