Repository navigation
Releases
v3.0.1
Fixed
- Update the stlab-execution dependency to 1.0.2, fixing an MSVC compilation failure in task callback function-pointer types. Fixes #614 through stlab/stlab-execution#4. (#615)
- Support default short-form
CPMAddPackageconsumption with source dependencies, installed dependencies throughCPM_USE_LOCAL_PACKAGES, and mixed source/installed configurations. (#615)
Installation
STLab installation respects CPM's dependency exclusion: install prerequisites separately and make their prefixes discoverable through CMAKE_PREFIX_PATH. Installed STLab discovers those prerequisites through find_dependency(). See the README installation instructions.
Draft publication checklist
- All 21 checks passed on the PR head, including Windows native and portable DLL package matrices, macOS sanitizers, and WebAssembly.
- Confirm Build and Tests passes for release candidate
051a0983e5048218ac969d17fdc22e8f69465c70. - Documentation-site deployment succeeded for the release candidate.
Full changelog: v3.0.0...v3.0.1
v3.0.0
Highlights
- Fix broken-promise handling in
when_allandwhen_any, including executors that discard queued work. Join bookkeeping no longer requires a recovery shared state for each input. (#612) - Preserve future value forwarding and executor lifetimes across recovery, completion, and coroutine suspension. (#609)
- Correct producer replacement, move-only value extraction, and coroutine results containing
std::exception_ptr. (#609)
Breaking changes and migration
This major release changes future extraction and detachment contracts and removes deprecated APIs.
- For move-only futures, call
f.get_try()on a mutable lvalue for nonblocking polling. A successful poll moves out the value; a pending poll preserves the future. When readiness is known, usestd::move(f).get_ready(). Const extraction is no longer supported. Copyable futures retain non-destructive shared-value extraction. detach()is now rvalue-only. Replacef.detach()on a named future withstd::move(f).detach(). The detached future is retained until completion.- Replace
blocking_getwithawait, andblocking_get_forwithawait_for. For timed value extraction, retain the future returned byawait_forand use the appropriate extraction operation. - Replace
error()withis_ready()followed byexception(), or userecover()for continuation-based error handling. when_anyselects the first successful input observed by completion bookkeeping, rather than by executor notification order. If every input fails, it reports the last observed failure.
Draft publication checklist
- Confirm Build and Tests passes for release candidate
35197e5d81ebf6afe4a74dd833fd34a5ff55d005. The run was still in progress when this draft was prepared. - Doxygen API docs and documentation-site deployment succeeded for the release candidate.
What's Changed
- Address Coverity findings and preserve future value forwarding by @sean-parent in #609
- Fix broken-promise handling in future joins by @sean-parent in #612
Full Changelog: v2.4.0...v3.0.0
v2.4.0
Highlights
- Expanded coroutine support and generic
resume_onsupport for awaitables. - DLL-safe shared executor ABI and core-ABI system timers, including threadless Emscripten support.
- Execution primitives extracted into the standalone
stlab-executiondependency, consumed through CPM. - Doxygen documentation improvements and fixes for headers and
forest::child_iteratorconstruction.
Draft publication checklist
- Resolve the failed documentation-site build for the release commit: https://github.com/stlab/stlab/actions/runs/38341087303 (the deployment job was skipped).
What's Changed
- Enhance coroutine support in
future<>and update README by @sean-parent in #592 - Implement generic
resume_onsupport for awaitables infuture<>by @sean-parent in #594 - fix: Add the missing header file by @apocelipes in #597
- Add Doxygen support and enhance documentation across the project by @sean-parent in #599
- forest: fix child_iterator constructor argument by @purpleKarrot in #595
- Add DLL-safe shared executor ABI by @sean-parent in #604
- Move system timers into core ABI and add threadless Emscripten by @sean-parent in #605
- Mark coroutine test await_ready helpers nodiscard by @sean-parent in #606
- Extract standalone stlab-execution and consume it through CPM by @sean-parent in #607
New Contributors
- @apocelipes made their first contribution in #597
- @purpleKarrot made their first contribution in #595
Full Changelog: v2.3.0...v2.4.0
v2.3.0
What's Changed
future<>::on_completion()
New on_completion() interface on future<>. This allows notification when a future is complete. This is a low-level call used in the improved coroutine support. The completion function has a signature void() noexcept. It consumes a continuation slot, but does not consume the future, so if used on a move-only future, it consumes the only continuation slot, and it is UB to attach a continuation (such as with then() or recover()) after. Example:
auto f = stlab::async(default_executor, [] { return "world!\n"; });
f.on_completion([]() noexcept { std::cerr << "Hello "; });
std::cerr << stlab::await(std::move(f));This will print:
Hello world!
Coroutine cancellation for future<>.
Cancellation of coroutines is now supported. When a coroutine returning a future awaits a future, the coroutine may be canceled while suspended. Example:
auto coroutine(future<int> f) -> future<int> {
std::cout<< "start\n";
int x = co_await std::move(f);
std::cout<< "finish\n";
co_return x + 5;
}
int main() {
auto [p, f] = package<int(int)>(immediate_executor, std::identity{});
(void)coroutine(std::move(f)); // drop the result to cancel
p(42); // fulfill the promise
}This will print:
start
resume_on()
The resume_on() function takes a future and an executor and returns an Awaitable. This allows you to specify the execution context for resuming a coroutine. Example:
auto coroutine(future<int> f) -> future<int> {
int x = co_await resume_on(main_executor, f);
x += 42; // do this on the main thread
co_return x;
}The resume_on() function can be passed just an executor to immediately continue execution on the supplied executor. For both forms of resume_on(), if called in a coroutine that returns a future and all copies of the future are released, the operation may be canceled while suspended. Example:
(void)coroutine(async(immediate_executor, []{ return 42; })); // drop future to cancel
// might never resume from the co_await and not execute `x+= 42;`doctest
Moved from BoostTest to doctest as part of the migration towards using stlab/cpp-library for this project. This improves the build times for the tests and the developer experience in VSCode/Cursor using the C++ TestMate extension.
- Improvements to coroutine support for
future<>by @sean-parent in #590
Full Changelog: v2.2.0...v2.3.0
v2.2.0
What's Changed
- Changed repo to stlab/stlab to better support CPM.cmake with installs.
- Added
cmake --installsupport usingstlab/cpp-library. - Release version is now pickup from the git tag via cpp-library.
Bug Fix
- Fixed a bug in system_timer that could crash on exit when using libdispatch.
Full Changelog: v2.1.4...v2.2.0
v2.1.4
On Windows, the static singleton executors were being created in a member function templated on the task type. This was causing unnecessary thread pools to get constructed. Moved instances to the .cpp file to make it simpler to share across DLLs (open issue is to normalize the various implementations).
What's Changed
- Fixing windows singleton executors by @sean-parent in #580
Full Changelog: v2.1.3...v2.1.4
v2.1.3
- Updated dependencies.
- Tests are now only registered if the project is top-level.
v2.1.2
Some minor fixes to allow building with \permissive in MSVC under C++17.
v2.1.1
v2.1.0
What's Changed
- Make task pool size configurable by @bmedina in #571
- Adding dependency to new enum_ops library. by @sean-parent in #572
New Contributors
Full Changelog: v2.0.2...v2.1.0