Latest Release: 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 https://github.com/stlab/stlab/pull/590

Full Changelog: https://github.com/stlab/stlab/compare/v2.2.0…v2.3.0

Posts

• Dec 1, 2020

  Forest: An Introduction

  Hierarchies. Everyone uses them, so why are they difficult to maintain? In this article we explore forest, a data structure that makes hierarchies self-maintainable, so you can go back to thinking about the data they contain.

• Dec 23, 2017

  Small Object Optimization for Polymorphic Types

  At Meeting C++ 2017 I presented a lightning talk Polymorphic Task Template in Ten which showed an easy way to implement a polymorphic task template, similar to std::function, with a small object optimization in 10 minutes.

  Unfortunately, the small object optimization, as described, leads to undefined behavior. As a general rule, you cannot store an object of one type in memory and read it back as another, even if the other type is the objects base class (there are exceptions to this rule, but they do not apply to this situation).

  This tip looks at the details of the issue and describes a solution which turns out to be more efficient although it does require slightly more, and more complex, code to implement. A small object optimization for polymorphic types is a very useful construct so it important to understand how it can be done correctly.

• May 11, 2017

  New Concurrency Library

  A new concurrency library was added as a first one to this new stlab instance.

  This library provides an alternative to the C++11/14 and upcoming C++17 TS futures. As well it provides an implementation of channels that allow the creation of process graphs.

subscribe via RSS