Remove legacy threading dead code

.github/workflows/ci_linux.yml

@@ -32,58 +32,3 @@ jobs:
       # 5️⃣ Run all tests
       - name: Run all tests
         run: bazelisk test //...
-
-  perf_sample:
-    name: Perf sampling (perf -> flamegraph)
-    runs-on: ubuntu-latest
-    if: ${{ github.event_name == 'workflow_dispatch' }}
-    needs: build_and_test
-    steps:
-        - name: Checkout repository
-          uses: actions/checkout@v4
-
-        - name: Setup Bazelisk
-          uses: bazel-contrib/setup-bazel@0.15.0
-
-        - name: Install perf and tools
-          run: |
-            sudo apt-get update
-            # Install perf (linux-tools) and other helpers
-            sudo apt-get install -y linux-tools-common linux-tools-$(uname -r) perf git perl
-
-        - name: Relax perf restrictions (may require sudo)
-          run: sudo sysctl -w kernel.perf_event_paranoid=-1 || true
-
-        - name: Build dtest with symbols
-          run: bazelisk build //library/tests:dtest -c opt --copt=-g
-
-        - name: Run perf capture via helper script
-          run: |
-            chmod +x copilot/perf/run_sample.sh
-            ./copilot/perf/run_sample.sh --no-build --duration 30 --bench hands/list100.txt --name ci-linux || true
-
-        - name: Post-process perf data (if present)
-          run: |
-            set -euo pipefail
-            ARTDIR=copilot/perf/artifacts
-            # Find newest .data file
-            DATA=$(ls -t ${ARTDIR}/*.data 2>/dev/null | head -n1 || true)
-            if [ -n "${DATA}" ]; then
-              echo "Found perf data: ${DATA}"
-              PERF_SCRIPT_OUT="${DATA%.data}.perf"
-              echo "Converting perf.data -> perf script (${PERF_SCRIPT_OUT})"
-              perf script -i "${DATA}" > "${PERF_SCRIPT_OUT}"
-              echo "Generating flamegraph (requires network to clone FlameGraph)"
-              git clone https://github.com/brendangregg/FlameGraph.git /tmp/FlameGraph
-              /tmp/FlameGraph/stackcollapse-perf.pl "${PERF_SCRIPT_OUT}" > "${PERF_SCRIPT_OUT}.folded"
-              /tmp/FlameGraph/flamegraph.pl "${PERF_SCRIPT_OUT}.folded" > "${PERF_SCRIPT_OUT}.svg"
-              echo "Flamegraph generated: ${PERF_SCRIPT_OUT}.svg"
-            else
-              echo "No perf .data file found in ${ARTDIR}; skipping post-processing"
-            fi
-
-        - name: Upload perf artifacts
-          uses: actions/upload-artifact@v4
-          with:
-            name: perf-artifacts
-            path: copilot/perf/artifacts/

README.md

@@ -105,4 +105,73 @@ Please report bugs to bo.haglund@bahnhof.se and soren.hein@gmail.com.
 Version 3.0.0, preliminary change log
 ====
 
-To build with C api include `<api/dll.h>`, for the full C++ api use <dds/dds.hpp>
+## API Documentation
+
+DDS 3.0 provides two API levels to suit different use cases:
+
+### Modern C++ API (Recommended for New Projects)
+
+The modern API uses instance-scoped `SolverContext` with automatic resource management (RAII):
+
+```cpp
+#include <dds/dds.hpp>
+
+auto main() -> int
+{
+    // Configure solver
+    SolverConfig cfg;
+    cfg.tt_kind_ = TTKind::Large;
+    cfg.tt_mem_default_mb_ = 2000;
+    cfg.tt_mem_maximum_mb_ = 2000;
+
+    // Create context (automatic cleanup on destruction)
+    SolverContext ctx(cfg);
+
+    // Solve boards
+    Deal deal{};
+    // ... initialize deal with cards ...
+
+    FutureTricks fut{};
+    SolveBoard(ctx, deal, -1, 3, 0, &fut);
+
+    return 0;
+}
+```
+
+**Benefits:**
+- Automatic memory management (no manual cleanup)
+- Per-context configuration (different settings per thread)
+- Better multithreading (no global state contention)
+- Explicit transposition table control
+
+### Legacy C API (Backward Compatible)
+
+The legacy API uses global state and is maintained for backward compatibility:
+
+```c
+#include <api/dll.h>
+
+struct Deal deal = {0};
+struct FutureTricks fut = {0};
+
+SetMaxThreads(4);
+SetResources(2000, 4);
+SolveBoard(deal, -1, 3, 0, &fut, 0);
+
+FreeMemory();
+```
+
+**Note:** Legacy initialization functions (`SetThreading`, `SetMaxThreads`, `SetResources`, `FreeMemory`) are deprecated but remain functional. See [docs/api_migration.md](docs/api_migration.md) for migration guidance.
+
+### Migration Guide
+
+For detailed migration examples and best practices, see:
+- **[API Migration Guide](docs/api_migration.md)** - Step-by-step migration from legacy to modern API
+- **[Legacy C API Reference](docs/legacy_c_api.md)** - Full documentation of deprecated functions
+- **[Migration Example](examples/migration_example.cpp)** - Side-by-side legacy and modern API sample
+- **[SolverContext Documentation](library/src/README_SolverContext.md)** - Modern API details
+
+**Quick decision:**
+- **New C++ projects**: Use modern API (`#include <dds/dds.hpp>`)
+- **Existing C projects**: Continue with legacy API (no changes required)
+- **Migration**: Follow incremental migration guide in docs/api_migration.md

copilot/instructions/completed/remove_dead_code.md

@@ -0,0 +1,10 @@
+## Retire the Threading Enum.
+
+Global memory allocation has been replaced by per call memory allocation. Clients can cache, and reuse, transposition tables. Computers have a lot more RAM compared to 15 years ago and it has to guess what is efficient from hardware configurations only. There are, however, some lingering types related to the legacy threading model.
+
+- Verify that C++ clients can cache, and either reuse or reset, transposition tables.
+- Verify that Threading is dead code.
+- Check for other pieces of dead code such as initialisations.
+- Check if any now unnecessary methods should remain as no operation implementations in the legacy C API.
+- Create a plan for removing all legacy threading code from the C++ interface and library.
+- There is a CI step called `perf_sample` that attempted to measure performance but is skipped and is unlikely to run correctly. Remove it if it does not execute correctly.