Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -156,5 +156,11 @@ fetch example is prospective, and `CPP_LIBRARY_VERSION=1.0.0` is only a standalo
install-validation override, not release evidence.

The generated CI runs generic native and clang-tidy presets.
`.github/matrix.json` is not consumed by that workflow; shared, C++17, portable,
ASan, Qt, Emscripten, and package variants need separate validation.
Shared, C++17, portable, ASan, Qt, Emscripten, and package variants need separate
validation. Do not add an unconsumed project matrix or fork the generated workflow.
Toolkit extensions are tracked in stlab/cpp-library#30.

The pinned cpp-library 5.6.0 release provides the documentation and runtime-DLL
helpers; tests and documentation require no local toolkit override.
Keep Doxygen configuration on the shared toolkit template, declaring project
deltas through `DOCS_INPUTS`, `DOCS_EXCLUDE_SYMBOLS`, and `DOCS_OPTIONS`.
18 changes: 0 additions & 18 deletions .github/matrix.json

This file was deleted.

202 changes: 202 additions & 0 deletions .scout/evaluations/autotune-query-set.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,202 @@
description = "stlab-execution runtime search quality: public adapters, ABI, schedulers, timers, and lifecycle"

[[queries]]
id = "ident-main-queue"
query = "main_task_queue"
class = "identifier"
[judgments.ident-main-queue]
"src/concurrency/detail/main_task_queue.hpp" = 3
"src/concurrency/main_executor_portable.cpp" = 2
"src/concurrency/main_executor_emscripten.cpp" = 2

[[queries]]
id = "ident-waiter"
query = "waiter_state"
class = "identifier"
[judgments.ident-waiter]
"src/concurrency/detail/waiter_state.hpp" = 3
"src/concurrency/executor_abi.cpp" = 2
"test/waiter_state_test.cpp" = 2

[[queries]]
id = "ident-timer-delay"
query = "timer_delay"
class = "identifier"
[judgments.ident-timer-delay]
"src/concurrency/detail/timer_common.hpp" = 3
"src/concurrency/system_timer_portable.cpp" = 2
"src/concurrency/system_timer_windows.cpp" = 2
"src/concurrency/system_timer_libdispatch.cpp" = 2

[[queries]]
id = "ident-timer-validation"
query = "check_timer_submission"
class = "identifier"
[judgments.ident-timer-validation]
"src/concurrency/detail/timer_common.hpp" = 3
"src/concurrency/system_timer_portable.cpp" = 2
"src/concurrency/system_timer_windows.cpp" = 2
"src/concurrency/system_timer_emscripten.cpp" = 2
"src/concurrency/system_timer_libdispatch.cpp" = 2

[[queries]]
id = "ident-callback-scope"
query = "core_callback_scope"
class = "identifier"
[judgments.ident-callback-scope]
"src/concurrency/detail/core_shutdown.hpp" = 3
"src/concurrency/core_shutdown.cpp" = 3
"src/concurrency/executor_abi.cpp" = 2
"src/concurrency/system_timer_portable.cpp" = 2

[[queries]]
id = "ident-timer-status"
query = "stlab_v2_timer_status"
class = "identifier"
[judgments.ident-timer-status]
"include/stlab/concurrency/system_timer.hpp" = 3
"src/concurrency/detail/timer_common.hpp" = 2
"src/concurrency/system_timer_windows.cpp" = 2
"src/concurrency/system_timer_portable.cpp" = 2

[[queries]]
id = "ident-priority"
query = "executor_priority"
class = "identifier"
[judgments.ident-priority]
"include/stlab/concurrency/default_executor.hpp" = 3
"src/concurrency/executor_abi.cpp" = 2

[[queries]]
id = "ident-pre-exit"
query = "pre_exit"
class = "identifier"
[judgments.ident-pre-exit]
"include/stlab/pre_exit.hpp" = 3
"src/pre_exit.cpp" = 3
"src/concurrency/core_shutdown.cpp" = 2

[[queries]]
id = "nl-retirement-order"
query = "how does shutdown cancel pending timers before draining executor tasks"
class = "natural_language"
[judgments.nl-retirement-order]
"src/concurrency/core_shutdown.cpp" = 3
"src/concurrency/detail/core_shutdown.hpp" = 2
"src/concurrency/system_timer_portable.cpp" = 2
"src/concurrency/system_timer_windows.cpp" = 2
"src/concurrency/cooperative_executor.cpp" = 2
"test/system_timer_executor_shutdown.cpp" = 2
"src/pre_exit.cpp" = 1

[[queries]]
id = "nl-task-storage"
query = "move-only callable small buffer storage and nonthrowing relocation"
class = "natural_language"
[judgments.nl-task-storage]
"include/stlab/concurrency/task.hpp" = 3
"include/stlab/concurrency/default_executor.hpp" = 2
"src/concurrency/detail/main_task_queue.hpp" = 1
"src/concurrency/executor_abi.cpp" = 1

[[queries]]
id = "nl-cooperative-drain"
query = "threadless cooperative executor keeps event loop responsive while retiring descendants"
class = "natural_language"
[judgments.nl-cooperative-drain]
"src/concurrency/cooperative_executor.cpp" = 3
"src/concurrency/main_executor_emscripten.cpp" = 2
"src/concurrency/detail/core_shutdown.hpp" = 2
"include/stlab/pre_exit.hpp" = 2
"src/concurrency/core_shutdown.cpp" = 1

[[queries]]
id = "nl-lost-wake"
query = "remember a worker wake request that arrives before it starts waiting"
class = "natural_language"
[judgments.nl-lost-wake]
"src/concurrency/detail/waiter_state.hpp" = 3
"src/concurrency/executor_abi.cpp" = 2
"test/waiter_state_test.cpp" = 2

[[queries]]
id = "nl-timer-rounding"
query = "round positive timer delays upward and recheck monotonic time to prevent early callbacks"
class = "natural_language"
[judgments.nl-timer-rounding]
"include/stlab/concurrency/system_timer.hpp" = 3
"src/concurrency/detail/timer_common.hpp" = 3
"src/concurrency/system_timer_portable.cpp" = 2
"src/concurrency/system_timer_windows.cpp" = 2
"src/concurrency/system_timer_libdispatch.cpp" = 2

[[queries]]
id = "nl-main-fifo"
query = "main executor FIFO queue waits for work and invokes callbacks outside the queue mutex"
class = "natural_language"
[judgments.nl-main-fifo]
"src/concurrency/detail/main_task_queue.hpp" = 3
"src/concurrency/main_executor_portable.cpp" = 3
"src/concurrency/main_executor_emscripten.cpp" = 2
"src/concurrency/main_executor_libdispatch.cpp" = 2

[[queries]]
id = "nl-callback-shutdown"
query = "reject synchronous shutdown from a native timer or executor callback including capture destruction"
class = "natural_language"
[judgments.nl-callback-shutdown]
"src/concurrency/core_shutdown.cpp" = 3
"src/concurrency/detail/core_shutdown.hpp" = 2
"src/pre_exit.cpp" = 2
"src/concurrency/system_timer_portable.cpp" = 1
"src/concurrency/executor_abi.cpp" = 1

[[queries]]
id = "filt-public-status"
query = "stlab_v2_timer_status"
class = "filtered"
extensions = ["hpp"]
paths = ["include/stlab"]
[judgments.filt-public-status]
"include/stlab/concurrency/system_timer.hpp" = 3

[[queries]]
id = "filt-detail-waiter"
query = "waiter_state"
class = "filtered"
extensions = ["hpp"]
paths = ["src/concurrency/detail"]
[judgments.filt-detail-waiter]
"src/concurrency/detail/waiter_state.hpp" = 3

[[queries]]
id = "filt-priority"
query = "executor_priority"
class = "filtered"
extensions = ["hpp"]
paths = ["include/stlab/concurrency"]
[judgments.filt-priority]
"include/stlab/concurrency/default_executor.hpp" = 3

[[queries]]
id = "filt-monotonic-delay"
query = "timer_delay"
class = "filtered"
extensions = ["hpp"]
paths = ["src/concurrency/detail"]
[judgments.filt-monotonic-delay]
"src/concurrency/detail/timer_common.hpp" = 3

[[queries]]
id = "filt-callback-guard"
query = "core_callback_scope"
class = "filtered"
extensions = ["cpp"]
paths = ["src/concurrency"]
[judgments.filt-callback-guard]
"src/concurrency/core_shutdown.cpp" = 3
"src/concurrency/executor_abi.cpp" = 2
"src/concurrency/system_timer_windows.cpp" = 2
"src/concurrency/system_timer_portable.cpp" = 2
"src/concurrency/system_timer_libdispatch.cpp" = 2
"src/concurrency/system_timer_emscripten.cpp" = 2
17 changes: 17 additions & 0 deletions .scout/memory/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Memory Bank Index

## Knowledge

- [[knowledge/abi-stability-version-namespaces-and-shared-library-exports.md|ABI Stability, Version Namespaces, and Shared Library Exports]] (decision, 0.80) `abi-stability` `version-namespaces` `execution-def` `task-abi-guard` `shared-library-abi`
- [[knowledge/architecture-overview.md|Architecture Overview]] (concept, 0.80) `architecture-overview` `stlab-execution` `execution-runtime` `concurrency-runtime` `stlab-concurrency`
- [[knowledge/concurrency-contracts-and-locking-discipline.md|Concurrency Contracts and Locking Discipline]] (pattern, 0.80) `concurrency-contracts` `locking-rules` `synchronization-invariants` `mutex-discipline` `lock-scoping`
- [[knowledge/executor-architecture-and-native-priority-schedulers.md|Executor Architecture and Native Priority Schedulers]] (concept, 0.75) `default-executor` `executor-abi` `priority-task-system` `thread-pool` `stlab-v2-default-executor-submit`
- [[knowledge/main-executor-backends-and-dispatch-queue.md|Main Executor Backends and Dispatch Queue]] (concept, 0.75) `main-executor` `main-task-queue` `main-queue` `portable-main-executor`
- [[knowledge/process-lifecycle-and-pre-exit-protocol.md|Process Lifecycle and Pre-Exit Protocol]] (decision, 0.80) `pre-exit` `at-pre-exit` `process-shutdown` `stlab-pre-exit` `core-shutdown`
- [[knowledge/system-timer-architecture-and-guarantees.md|System Timer Architecture and Guarantees]] (concept, 0.75) `system-timer` `timer-status` `stlab-v2-system-timer-submit` `timer-delay` `portable-timers`
- [[knowledge/task-type-erasure-and-relocation-abi.md|Task Type Erasure and Relocation ABI]] (concept, 0.80) `task` `task-t` `stlab-v2-task-concept` `type-erasure` `move-only-task`
- [[knowledge/threadless-emscripten-cooperative-execution-and-shutdown.md|Threadless Emscripten Cooperative Execution and Shutdown]] (concept, 0.75) `emscripten` `cooperative-executor` `threadless-wasm` `webassembly-execution` `wasm-pre-exit`

## Procedures

- [[procedures/build-presets-testing-matrix-and-cpp-library-tooling.md|Build Presets, Testing Matrix, and cpp-library Tooling]] (procedure, 0.80) `build-system` `cmake-presets` `cpp-library` `test-infrastructure` `ctest-matrix`
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
title: "ABI Stability, Version Namespaces, and Shared Library Exports"
entity_type: decision
confidence: 0.80
created: 2026-10-13T00:39:46Z
last_accessed: 2026-10-13T00:39:46Z
last_reinforced: 2026-10-13T00:39:46Z
access_count: 1
sources:
- "include/stlab/concurrency/task.hpp:60-80"
- "include/stlab/concurrency/default_executor.hpp:50-80"
- "src/execution.def:1-30"
- "CMakeLists.txt:1-60"
relationships:
- type: relates_to
target: "Architecture Overview"
- type: relates_to
target: "Task Type Erasure and Relocation ABI"
tags: ["abi-stability", "version-namespaces", "execution-def", "task-abi-guard", "shared-library-abi"]
tier: knowledge
source: inferred
---

# ABI Stability, Version Namespaces, and Shared Library Exports

`stlab-execution` employs versioned symbols and ABI namespaces to prevent symbol collisions and preserve binary compatibility across component updates:

Key rules and constraints:
1. Version namespaces: C++ interfaces live inside `STLAB_EXECUTION_VERSION_NAMESPACE_BEGIN()` and `END()`, which expand to versioned inline namespaces (`inline namespace v2`). Internal implementation helpers reside in `execution_detail`.
2. Linker ABI Guard: Task submission across the C boundary requires passing `task_abi_guard` pointing to `execution_detail::current_task_storage_abi_guard::value`. Any mismatch in SBO buffer layout, alignment, or calling convention causes immediate assertion failure and termination.
3. C Export Vector: Core functions are exposed as C entry points (`stlab_pre_exit`, `stlab_at_pre_exit`, `stlab_v2_default_executor_submit`, etc.) and explicitly tracked in `src/execution.def` on Windows DLL builds. ABI changes require defining new versioned entry points, not weakening layout assertions.
4. Header generation: Platform capabilities are generated into `stlab/execution/config.hpp` via `config.hpp.in` and CMake. Never edit `config.hpp` directly in the build tree.

Aliases / also known as: abi_stability, version_namespaces, execution_def, task_abi_guard, shared_library_abi
29 changes: 29 additions & 0 deletions .scout/memory/knowledge/architecture-overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
---
title: "Architecture Overview"
entity_type: concept
confidence: 0.80
created: 2026-10-13T00:38:31Z
last_accessed: 2026-10-13T00:38:31Z
last_reinforced: 2026-10-13T00:38:31Z
access_count: 1
sources:
- "README.md:1-40"
- "include/stlab/concurrency/task.hpp:12-32"
- "include/stlab/pre_exit.hpp:11-32"
tags: ["architecture-overview", "stlab-execution", "execution-runtime", "concurrency-runtime", "stlab-concurrency"]
tier: knowledge
source: inferred
---

# Architecture Overview

stlab-execution is the standalone C++17/20 execution runtime extracted from STLab, providing move-only tasks, priority executors, asynchronous timers, and process lifecycle coordination (`pre_exit()`). It preserves canonical stlab namespace and include paths (`<stlab/concurrency/*.hpp>`, `<stlab/pre_exit.hpp>`), but deliberately excludes futures, channels, serial queues, and coroutine policies (which reside in higher-level libraries). Public C++ interfaces are header-only inline templates, while compiled sources implement process-wide schedulers, thread pools, and lifecycle state.

First-to-read headers and entry points:
- `include/stlab/concurrency/task.hpp`: non-copyable type-erased callable wrapper with SBO and noexcept relocation across the C ABI.
- `include/stlab/concurrency/default_executor.hpp`: default, high, and low priority thread-pool executors.
- `include/stlab/concurrency/system_timer.hpp`: non-early asynchronous timer service.
- `include/stlab/pre_exit.hpp`: process-wide LIFO pre-exit handler registry and drain barrier.
- `src/concurrency/executor_abi.cpp`: ABI implementation for native priority queues, threadpool backends, and portable blocking compensation.

Aliases / also known as: architecture_overview, stlab_execution, execution_runtime, concurrency_runtime, stlab_concurrency
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
title: "Concurrency Contracts and Locking Discipline"
entity_type: pattern
confidence: 0.80
created: 2026-10-13T00:39:55Z
last_accessed: 2026-10-13T00:39:55Z
last_reinforced: 2026-10-13T00:39:55Z
access_count: 1
sources:
- "CLAUDE.md:1-50"
- "src/concurrency/detail/main_task_queue.hpp:25-55"
- "src/concurrency/core_shutdown.cpp:30-80"
relationships:
- type: relates_to
target: "Architecture Overview"
- type: relates_to
target: "Task Type Erasure and Relocation ABI"
tags: ["concurrency-contracts", "locking-rules", "synchronization-invariants", "mutex-discipline", "lock-scoping"]
tier: knowledge
source: inferred
---

# Concurrency Contracts and Locking Discipline

Strict concurrency and lock-scoping guidelines govern all internal synchronization within `stlab-execution`:

Key rules and invariants:
1. Narrowest lock scope: Mutexes must protect only the minimal shared state invariant. Callbacks, capture destruction, task bodies, user code, and blocking waits must NEVER be executed inside a mutex critical section.
2. Mandatory mutex documentation: Every mutex declaration in source code must include a comment detailing the exact state and synchronization invariant it protects, including any associated condition variable coordination.
3. Queue push/pop safety: Callable construction, copy/move construction, and moved-from object destruction are prohibited from submitting work to queues, because queue implementations may hold locks during element relocation or destruction.
4. Mutex vs Atomic: Protect a single primitive with `std::atomic` only if compound invariants, wait queues, or object lifetime guarantees are not required.

Aliases / also known as: concurrency_contracts, locking_rules, synchronization_invariants, mutex_discipline, lock_scoping
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
---
title: "Executor Architecture and Native Priority Schedulers"
entity_type: concept
confidence: 0.75
created: 2026-10-13T00:39:05Z
last_accessed: 2026-10-13T00:39:05Z
last_reinforced: 2026-10-13T00:39:05Z
access_count: 1
sources:
- "include/stlab/concurrency/default_executor.hpp:50-115"
- "src/concurrency/executor_abi.cpp:630-760"
relationships:
- type: depends_on
target: "Task Type Erasure and Relocation ABI"
- type: relates_to
target: "Process Lifecycle and Pre-Exit Protocol"
tags: ["default-executor", "executor-abi", "priority-task-system", "thread-pool", "stlab-v2-default-executor-submit"]
tier: knowledge
source: inferred
---

# Executor Architecture and Native Priority Schedulers

Default thread-pool executors submit tasks through an ABI-stable C interface (`stlab_v2_default_executor_submit`, `stlab_v2_high_executor_submit`, `stlab_v2_low_executor_submit`) defined in `include/stlab/concurrency/default_executor.hpp`.

Key mechanics:
1. Entry points take a `task_abi_guard` pointer (`current_task_storage_abi_guard::value`), a vtable pointer (`stlab_v2_task_concept`), an invocation procedure (`stlab_v2_task_proc`), and a relocation source pointer.
2. Backends: In `src/concurrency/executor_abi.cpp`, native priority scheduling is sharded. Backends are selected at build time:
- macOS/Apple: Apple libdispatch (GCD) global concurrent queues (`DISPATCH_QUEUE_PRIORITY_*`).
- Windows: Windows thread pool APIs (`TrySubmitThreadpoolCallback`).
- Portable: Native portable worker threads (`priority_task_system`).
- Threadless Emscripten: `cooperative_executor.cpp` using the browser/Node event loop.
3. Blocking-wait compensation: Portable executor provides `stlab_v2_notify_default_executor_before_waiting()` (`stlab_v2_default_executor_supports_blocking()`). Calling threads notify the scheduler before blocking, allowing the thread pool to spawn a temporary worker thread to maintain concurrency and avoid deadlocks. On OS-managed pools (Windows/libdispatch), this is a no-op.

Aliases / also known as: default_executor, executor_abi, priority_task_system, thread_pool, stlab_v2_default_executor_submit
Loading
Loading