contexture: Instructions file for GitHub Copilot

cpp rules

Auto-loaded by Copilot when editing files matching **/*.{cpp,cc,cxx,h,hpp,hxx}. Generated from architectural-rules/cpp/ — do not hand-edit.

C++ concurrency

Use RAII lock guards (std::lock_guard, std::scoped_lock, std::unique_lock) — never bare mutex.lock() / unlock(). A manual unlock is skipped on every early return and every throw. (CP.20) Acquire multiple locks with std::scoped_lock (or std::lock) in one statement — it orders acquisition to avoid deadlock. Never hand-order two lock_guards. (CP.21) Never call unknown / user-supplied code while holding a lock — it may re-enter and deadlock, or block far longer than intended. (CP.22) Use std::atomic for cross-thread flags and counters. volatile is not a synchronization primitive — it has no memory-ordering guarantees. (CP.8) Do not write lock-free code unless you must and have measured the need. Assume your lock-free code is wrong until proven otherwise with tooling. (CP.100) Minimize sharing of writable data. The cheapest concurrency bug is the one that can't happen because nothing is shared. (CP.3)

Why: concurrency bugs are non-deterministic and survive code review and most tests — RAII locking and atomics remove whole classes of them by construction. Source: C++ Core Guidelines (CP).

C++ const-correctness

Declare objects const unless the value must change. Immutable-by-default makes the few mutable things visible and lets the compiler enforce the rest. (Con.1) Make member functions const when they don't modify observable state. A non-const method is a claim that it mutates — don't make that claim falsely. (Con.2) Pass non-trivial types by const& (or const*) when you only read them — no copy, no mutation. Pass by value only for cheap-to-copy types or when you need an owned copy anyway. (Con.3) Use constexpr for values computable at compile time — they cost nothing at runtime and can be used in constant contexts (array sizes, template args). (Con.5)