@cubis/foundry 0.3.71 → 0.3.72

package/workflows/powers/cpp-pro/references/concurrency-primitives.md

@@ -0,0 +1,266 @@
+# Concurrency Primitives
+
+## `std::jthread` and `std::stop_token`
+
+```cpp
+#include <thread>
+#include <stop_token>
+
+// jthread — cooperative cancellation + auto-join
+void worker(std::stop_token stoken) {
+    while (!stoken.stop_requested()) {
+        process_next_item();
+    }
+    // Clean up when stop is requested
+}
+
+{
+    std::jthread t(worker); // starts thread
+    // ... do work ...
+} // jthread destructor: requests stop, then joins — no leak
+
+// Stop callback — register actions on cancellation
+void monitored_worker(std::stop_token stoken) {
+    std::stop_callback callback(stoken, [] {
+        std::cout << "Stop requested, cleaning up...\n";
+    });
+
+    while (!stoken.stop_requested()) {
+        do_work();
+    }
+}
+```
+
+## Mutex Strategies
+
+```cpp
+#include <mutex>
+#include <shared_mutex>
+
+// scoped_lock — locks multiple mutexes without deadlock
+std::mutex m1, m2;
+{
+    std::scoped_lock lock(m1, m2); // deadlock-free multi-lock
+    // ... access resources protected by both mutexes
+} // automatically unlocked
+
+// shared_mutex — multiple readers, single writer
+class ThreadSafeMap {
+    mutable std::shared_mutex mutex_;
+    std::unordered_map<std::string, int> data_;
+
+public:
+    int read(const std::string& key) const {
+        std::shared_lock lock(mutex_); // concurrent reads allowed
+        auto it = data_.find(key);
+        return it != data_.end() ? it->second : 0;
+    }
+
+    void write(const std::string& key, int value) {
+        std::unique_lock lock(mutex_); // exclusive write access
+        data_[key] = value;
+    }
+};
+
+// NEVER use lock/unlock manually — always use RAII guards
+// WRONG: m.lock(); ... m.unlock(); // exception-unsafe
+// RIGHT: std::lock_guard lock(m); or std::unique_lock lock(m);
+```
+
+## Atomic Operations
+
+```cpp
+#include <atomic>
+
+// Lock-free counters and flags
+class Stats {
+    std::atomic<uint64_t> requests_{0};
+    std::atomic<uint64_t> errors_{0};
+    std::atomic<bool> healthy_{true};
+
+public:
+    void record_request() {
+        requests_.fetch_add(1, std::memory_order_relaxed);
+    }
+
+    void record_error() {
+        errors_.fetch_add(1, std::memory_order_relaxed);
+    }
+
+    uint64_t requests() const {
+        return requests_.load(std::memory_order_relaxed);
+    }
+};
+
+// Memory ordering guide
+// relaxed:  no ordering guarantees, fastest — counters, flags
+// acquire:  reads see writes that happened before the matching release
+// release:  writes are visible to subsequent acquire loads
+// seq_cst:  total order across all threads — default, safest, slowest
+
+// Compare-and-swap for lock-free data structures
+std::atomic<Node*> head{nullptr};
+
+void push(Node* node) {
+    node->next = head.load(std::memory_order_relaxed);
+    while (!head.compare_exchange_weak(
+        node->next, node,
+        std::memory_order_release,
+        std::memory_order_relaxed)) {
+        // retry if another thread modified head
+    }
+}
+```
+
+## Condition Variables
+
+```cpp
+#include <condition_variable>
+
+class BoundedQueue {
+    std::queue<int> queue_;
+    std::mutex mutex_;
+    std::condition_variable not_empty_;
+    std::condition_variable not_full_;
+    size_t max_size_;
+
+public:
+    explicit BoundedQueue(size_t max) : max_size_(max) {}
+
+    void push(int value) {
+        std::unique_lock lock(mutex_);
+        not_full_.wait(lock, [this] { return queue_.size() < max_size_; });
+        queue_.push(value);
+        not_empty_.notify_one();
+    }
+
+    int pop() {
+        std::unique_lock lock(mutex_);
+        not_empty_.wait(lock, [this] { return !queue_.empty(); });
+        int value = queue_.front();
+        queue_.pop();
+        not_full_.notify_one();
+        return value;
+    }
+};
+```
+
+## `std::latch` and `std::barrier` (C++20)
+
+```cpp
+#include <latch>
+#include <barrier>
+
+// Latch — one-time synchronization point
+void parallel_init(size_t num_workers) {
+    std::latch ready(num_workers);
+
+    auto worker = [&ready](int id) {
+        initialize(id);
+        ready.count_down();   // signal ready
+    };
+
+    std::vector<std::jthread> threads;
+    for (size_t i = 0; i < num_workers; ++i) {
+        threads.emplace_back(worker, i);
+    }
+
+    ready.wait(); // wait until all workers initialized
+    start_processing();
+}
+
+// Barrier — reusable synchronization point
+void iterative_computation(size_t workers, size_t iterations) {
+    std::barrier sync(workers, [] noexcept {
+        // completion function — runs once per phase after all arrive
+        merge_results();
+    });
+
+    auto worker = [&sync, iterations](int id) {
+        for (size_t i = 0; i < iterations; ++i) {
+            compute_partial(id);
+            sync.arrive_and_wait(); // sync between iterations
+        }
+    };
+}
+```
+
+## Async and Futures
+
+```cpp
+#include <future>
+
+// std::async for fire-and-forget computation
+auto future = std::async(std::launch::async, [] {
+    return expensive_computation();
+});
+// ... do other work ...
+auto result = future.get(); // blocks until ready
+
+// packaged_task for deferred execution
+std::packaged_task<int(int)> task([](int x) { return x * x; });
+auto future = task.get_future();
+std::jthread t(std::move(task), 42); // execute in thread
+int result = future.get();
+
+// std::promise for hand-off between threads
+std::promise<int> promise;
+auto future = promise.get_future();
+
+std::jthread t([&promise] {
+    try {
+        int result = compute();
+        promise.set_value(result);
+    } catch (...) {
+        promise.set_exception(std::current_exception());
+    }
+});
+
+int result = future.get(); // may throw if set_exception was called
+```
+
+## C++20 Coroutines Basics
+
+```cpp
+#include <coroutine>
+
+// Generator coroutine
+template<typename T>
+struct Generator {
+    struct promise_type {
+        T current_value;
+        auto yield_value(T value) {
+            current_value = value;
+            return std::suspend_always{};
+        }
+        Generator get_return_object() {
+            return Generator{std::coroutine_handle<promise_type>::from_promise(*this)};
+        }
+        auto initial_suspend() { return std::suspend_always{}; }
+        auto final_suspend() noexcept { return std::suspend_always{}; }
+        void return_void() {}
+        void unhandled_exception() { throw; }
+    };
+
+    std::coroutine_handle<promise_type> handle_;
+
+    bool next() {
+        handle_.resume();
+        return !handle_.done();
+    }
+
+    T value() const { return handle_.promise().current_value; }
+    ~Generator() { if (handle_) handle_.destroy(); }
+};
+
+// Usage
+Generator<int> fibonacci() {
+    int a = 0, b = 1;
+    while (true) {
+        co_yield a;
+        auto next = a + b;
+        a = b;
+        b = next;
+    }
+}
+```

package/workflows/powers/cpp-pro/references/move-semantics-and-value-types.md

@@ -0,0 +1,149 @@
+# Move Semantics and Value Types
+
+## Move Constructor and Assignment
+
+```cpp
+class Buffer {
+    std::unique_ptr<uint8_t[]> data_;
+    size_t size_;
+
+public:
+    // Move constructor — steal resources
+    Buffer(Buffer&& other) noexcept
+        : data_(std::move(other.data_))
+        , size_(std::exchange(other.size_, 0)) {}
+
+    // Move assignment — release current, steal from other
+    Buffer& operator=(Buffer&& other) noexcept {
+        if (this != &other) {
+            data_ = std::move(other.data_);
+            size_ = std::exchange(other.size_, 0);
+        }
+        return *this;
+    }
+
+    // Rule of Five: if you define move ops, define or delete all five
+    Buffer(const Buffer&) = delete;            // expensive copy not needed
+    Buffer& operator=(const Buffer&) = delete;
+    ~Buffer() = default;
+};
+```
+
+## When to `std::move`
+
+```cpp
+// MOVE when transferring ownership
+void process(std::vector<int> data) { /* owns data */ }
+std::vector<int> v = {1, 2, 3};
+process(std::move(v)); // v is now in moved-from state
+
+// DO NOT move from const objects — silently copies instead
+const std::string s = "hello";
+std::string t = std::move(s); // copies! const prevents move
+
+// DO NOT move return values — defeats copy elision (NRVO)
+std::string make_string() {
+    std::string result = "hello";
+    return result;         // GOOD: NRVO applies
+    // return std::move(result); // BAD: prevents NRVO
+}
+
+// DO NOT use after move — object is in valid but unspecified state
+std::vector<int> v = {1, 2, 3};
+auto w = std::move(v);
+// v.size() — legal but unspecified
+// v.push_back(4) — legal, v is usable again
+```
+
+## Perfect Forwarding
+
+```cpp
+// Forward arguments preserving value category (lvalue/rvalue)
+template<typename... Args>
+auto make_unique_wrapper(Args&&... args) {
+    return std::make_unique<Widget>(std::forward<Args>(args)...);
+}
+
+// Forwarding reference (T&& with template deduction) vs rvalue reference
+template<typename T>
+void forward_ref(T&& arg) {         // forwarding reference: T is deduced
+    inner(std::forward<T>(arg));
+}
+
+void rvalue_ref(Widget&& arg) {      // rvalue reference: type is fixed
+    inner(std::move(arg));           // use move, not forward
+}
+```
+
+## Value Categories
+
+| Category    | Can take address? | Can move from?        | Examples                                          |
+| ----------- | ----------------- | --------------------- | ------------------------------------------------- |
+| **lvalue**  | Yes               | Only with `std::move` | `x`, `*p`, `a[i]`, function returning `T&`        |
+| **prvalue** | No                | Yes (implicit)        | `42`, `std::string("hi")`, function returning `T` |
+| **xvalue**  | Yes\*             | Yes                   | `std::move(x)`, function returning `T&&`          |
+
+## Copy Elision (Guaranteed since C++17)
+
+```cpp
+// Guaranteed copy elision — no copy/move constructor call
+Widget make_widget() {
+    return Widget(42); // prvalue: directly constructed in caller's storage
+}
+
+Widget w = make_widget(); // no copy, no move — guaranteed
+
+// NRVO (Named Return Value Optimization) — not guaranteed but common
+Widget make_named() {
+    Widget w(42);
+    w.configure();
+    return w; // NRVO: likely elided, but not guaranteed
+}
+```
+
+## `std::exchange` for Clean Moves
+
+```cpp
+// std::exchange replaces value and returns old value — ideal for moves
+class Socket {
+    int fd_;
+public:
+    Socket(Socket&& other) noexcept
+        : fd_(std::exchange(other.fd_, -1)) {} // steal fd, leave -1
+
+    ~Socket() {
+        if (fd_ != -1) ::close(fd_);
+    }
+};
+```
+
+## Reference Wrappers
+
+```cpp
+// std::reference_wrapper for storing references in containers
+std::vector<std::reference_wrapper<Widget>> widgets;
+Widget w1, w2;
+widgets.push_back(std::ref(w1));
+widgets.push_back(std::ref(w2));
+
+// Useful with algorithms that copy elements
+std::sort(widgets.begin(), widgets.end(),
+    [](const Widget& a, const Widget& b) { return a.id() < b.id(); });
+```
+
+## Moved-From State Obligations
+
+A moved-from object must be in a valid state that supports:
+
+1. Destruction (destructor runs)
+2. Assignment (can be reused)
+
+No other guarantees are required. Standard library types guarantee "valid but unspecified" state.
+
+```cpp
+// GOOD — reuse after move
+std::string s = "hello";
+std::string t = std::move(s);
+s = "world"; // valid: assign new value
+s.clear();   // valid: explicit reset
+```

package/workflows/powers/cpp-pro/references/performance-and-profiling.md

@@ -0,0 +1,191 @@
+# Performance and Profiling
+
+## Profiling Workflow
+
+1. **Measure first** — never optimize without profiling evidence.
+2. **Identify hotspots** — focus on the 5% of code that takes 95% of time.
+3. **Change one thing** — benchmark before and after each change.
+4. **Verify correctness** — run tests after every optimization.
+
+## Profiling Tools
+
+```bash
+# perf (Linux) — sampling profiler
+perf record -g ./myapp          # record call graph
+perf report                      # interactive analysis
+perf stat ./myapp                # hardware counters summary
+
+# Google Benchmark — microbenchmarks
+# CMakeLists.txt
+find_package(benchmark REQUIRED)
+add_executable(bench bench.cpp)
+target_link_libraries(bench benchmark::benchmark)
+
+# VTune (Intel) — detailed CPU analysis
+vtune -collect hotspots -- ./myapp
+vtune -collect memory-access -- ./myapp
+
+# Instruments (macOS)
+xcrun xctrace record --instrument "Time Profiler" --launch ./myapp
+```
+
+## Google Benchmark Patterns
+
+```cpp
+#include <benchmark/benchmark.h>
+
+static void BM_VectorPush(benchmark::State& state) {
+    for (auto _ : state) {
+        std::vector<int> v;
+        for (int i = 0; i < state.range(0); ++i) {
+            v.push_back(i);
+        }
+        benchmark::DoNotOptimize(v.data()); // prevent dead-code elimination
+    }
+    state.SetItemsProcessed(state.iterations() * state.range(0));
+}
+BENCHMARK(BM_VectorPush)->Range(8, 1 << 20);
+
+static void BM_VectorReserved(benchmark::State& state) {
+    for (auto _ : state) {
+        std::vector<int> v;
+        v.reserve(state.range(0)); // pre-allocate
+        for (int i = 0; i < state.range(0); ++i) {
+            v.push_back(i);
+        }
+        benchmark::DoNotOptimize(v.data());
+    }
+    state.SetItemsProcessed(state.iterations() * state.range(0));
+}
+BENCHMARK(BM_VectorReserved)->Range(8, 1 << 20);
+
+BENCHMARK_MAIN();
+```
+
+## Cache-Friendly Data Layout
+
+```cpp
+// Array of Structs (AoS) — good when you access all fields together
+struct Particle_AoS {
+    float x, y, z;
+    float vx, vy, vz;
+    float mass;
+};
+std::vector<Particle_AoS> particles; // each particle contiguous
+
+// Struct of Arrays (SoA) — good when you access one field across many elements
+struct Particles_SoA {
+    std::vector<float> x, y, z;
+    std::vector<float> vx, vy, vz;
+    std::vector<float> mass;
+};
+// Iterating over just x,y,z is cache-efficient — no vx,vy,vz,mass pollution
+
+// When to use which:
+// AoS: random access to individual particles, insertion/deletion
+// SoA: SIMD operations on one field, physics simulation, GPU uploads
+```
+
+## Allocation Reduction
+
+```cpp
+// Avoid repeated heap allocations in hot paths
+// BAD — allocates string each iteration
+for (const auto& item : items) {
+    std::string key = "prefix_" + item.name(); // allocation
+    cache.lookup(key);
+}
+
+// GOOD — reuse string buffer
+std::string key;
+key.reserve(64);
+for (const auto& item : items) {
+    key = "prefix_";
+    key += item.name(); // may reuse existing buffer
+    cache.lookup(key);
+}
+
+// string_view to avoid copies
+void process(std::string_view input) {  // no copy
+    auto pos = input.find(':');
+    auto key = input.substr(0, pos);    // no copy — just a view
+    auto val = input.substr(pos + 1);
+}
+
+// Small Buffer Optimization (SBO) — many types use it
+// std::string: typically 15-22 chars stored inline (no heap)
+// std::function: small callables stored inline
+// std::any: small types stored inline
+// pmr allocators: customize allocation strategy
+
+// Pre-allocate containers
+std::vector<int> v;
+v.reserve(expected_size); // avoids repeated reallocation
+```
+
+## Avoiding Virtual Dispatch in Hot Paths
+
+```cpp
+// Virtual dispatch: ~3-5ns per call (cache miss: ~100ns)
+// For tight loops with millions of iterations, this matters
+
+// std::variant + std::visit — static dispatch
+using Shape = std::variant<Circle, Rectangle, Triangle>;
+
+double total_area(const std::vector<Shape>& shapes) {
+    double sum = 0;
+    for (const auto& s : shapes) {
+        sum += std::visit([](const auto& shape) {
+            return shape.area(); // statically dispatched
+        }, s);
+    }
+    return sum;
+}
+
+// CRTP for static polymorphism (see template-and-concepts-patterns.md)
+```
+
+## Compiler Hints
+
+```cpp
+// [[likely]] and [[unlikely]] for branch prediction hints
+if (result == SUCCESS) [[likely]] {
+    process(result);
+} else [[unlikely]] {
+    handle_error(result);
+}
+
+// [[assume]] (C++23) — optimizer hint
+void process(int x) {
+    [[assume(x > 0)]]; // optimizer can assume this is true
+    // ... code that benefits from knowing x > 0
+}
+
+// Prefetch for known access patterns
+for (size_t i = 0; i < n; ++i) {
+    __builtin_prefetch(&data[i + 16], 0, 1); // prefetch ahead
+    process(data[i]);
+}
+```
+
+## Link-Time Optimization (LTO)
+
+```bash
+# Enable LTO
+g++ -flto -O2 -o myapp *.cpp
+clang++ -flto=thin -O2 -o myapp *.cpp  # thin LTO: faster build, similar gains
+
+# CMake
+set(CMAKE_INTERPROCEDURAL_OPTIMIZATION TRUE)
+```
+
+## Common Performance Anti-Patterns
+
+| Anti-pattern                     | Cost                      | Fix                                          |
+| -------------------------------- | ------------------------- | -------------------------------------------- |
+| `std::map` for lookup            | O(log n) + cache misses   | `std::unordered_map` or sorted `std::vector` |
+| `std::list` traversal            | Cache miss per node       | `std::vector` or `std::deque`                |
+| `std::shared_ptr` in hot path    | Atomic ref-count per copy | `unique_ptr` or raw observer pointer         |
+| String concatenation in loop     | O(n²) total allocations   | `std::string::reserve` + append              |
+| `virtual` dispatch in tight loop | Vtable indirection        | `std::variant` + `visit` or CRTP             |
+| Exceptions for control flow      | Stack unwinding cost      | Error codes or `expected<T, E>`              |

package/workflows/powers/cpp-pro/references/raii-and-modern-cpp-checklist.md

@@ -0,0 +1,87 @@
+# RAII and Modern C++ Checklist
+
+## RAII ownership patterns
+
+### Smart pointer selection
+
+| Pattern             | Type                 | When to use                                                                   |
+| ------------------- | -------------------- | ----------------------------------------------------------------------------- |
+| Exclusive ownership | `std::unique_ptr<T>` | Default choice. One owner, zero overhead, move-only.                          |
+| Shared ownership    | `std::shared_ptr<T>` | Multiple owners with shared lifetime. Use sparingly — adds refcount overhead. |
+| Non-owning observer | `T*` or `T&`         | Borrowing without ownership. Never delete through a raw pointer.              |
+| Weak observer       | `std::weak_ptr<T>`   | Observing shared-owned object without preventing destruction.                 |
+
+- Prefer `std::make_unique` and `std::make_shared` over raw `new`. They are exception-safe and more efficient.
+- Use custom deleters for non-memory resources: `unique_ptr<FILE, decltype(&fclose)> f(fopen(...), fclose);`
+
+### Rule of five / zero
+
+- **Rule of zero**: If a class only contains RAII members (smart pointers, containers), don't write any special member functions.
+- **Rule of five**: If you must write a destructor, also write or delete: copy constructor, copy assignment, move constructor, move assignment.
+- Use `= default` and `= delete` explicitly. Never leave special members implicitly generated when the class manages resources.
+
+## Value semantics
+
+- Prefer passing by value for small types (<= 2 words) and types you need to move from.
+- Pass large types by `const&` for reading, by `&&` for consuming.
+- Use `std::string_view` and `std::span<T>` for non-owning views of contiguous data.
+- Return by value — compilers apply NRVO/RVO. Avoid `std::move` on return statements in most cases.
+
+## Move correctness
+
+- After `std::move`, the source object is in a valid-but-unspecified state. Only assign to it or destroy it.
+- Mark move constructors and move assignment operators `noexcept` — this enables `std::vector` to use moves on reallocation.
+- Test that moved-from objects don't leak resources or crash when destroyed.
+
+## Concepts and constraints (C++20/23)
+
+```cpp
+template<typename T>
+concept Hashable = requires(T a) {
+    { std::hash<T>{}(a) } -> std::convertible_to<std::size_t>;
+};
+
+template<Hashable Key, typename Value>
+class HashMap { /* ... */ };
+```
+
+- Use concepts to replace SFINAE. They produce clear error messages and are readable.
+- Define concepts in terms of required expressions, not just type traits.
+- Combine concepts with `requires` clauses for complex constraints.
+
+## std::variant and pattern matching
+
+```cpp
+using Shape = std::variant<Circle, Rectangle, Triangle>;
+
+double area(const Shape& s) {
+    return std::visit(overloaded{
+        [](const Circle& c)    { return std::numbers::pi * c.r * c.r; },
+        [](const Rectangle& r) { return r.w * r.h; },
+        [](const Triangle& t)  { return 0.5 * t.base * t.height; }
+    }, s);
+}
+```
+
+- Use `std::variant` over inheritance for closed type sets. Adding a new alternative causes compile errors at all visit sites.
+- Use the `overloaded` pattern (aggregate of lambdas) for exhaustive visiting.
+
+## std::expected (C++23)
+
+```cpp
+std::expected<User, Error> find_user(int id) {
+    if (auto it = db.find(id); it != db.end())
+        return *it;
+    return std::unexpected(Error::NotFound);
+}
+```
+
+- Use `std::expected<T, E>` for recoverable errors in performance-sensitive paths instead of exceptions.
+- Chain operations with `.and_then()`, `.transform()`, `.or_else()` for monadic error handling.
+
+## Concurrency checklist
+
+- Use `std::jthread` + `std::stop_token` for threads that need cancellation.
+- Use `std::scoped_lock` for multi-mutex locking — prevents deadlocks from inconsistent lock order.
+- Use `std::atomic` with `memory_order_relaxed` only when you can prove no ordering dependency exists.
+- Run ThreadSanitizer (`-fsanitize=thread`) on all concurrent tests in CI.