Repository files navigation

stdexec is an experimental reference implementation of theSenders model of asynchronous programming proposed byP2300 -std::execution for adoption into the C++ Standard.

Purpose of this Repository:

1. Provide a proof-of-concept implementation of the design proposed inP2300.
2. Provide early access to developers looking to experiment with the Sender model.
3. Collaborate with those interested in participating or contributing to the design of P2300 (contributions welcome!).

stdexec is experimental in nature and subject to change without warning.The authors and NVIDIA do not guarantee that this code is fit for any purpose whatsoever.

Below is a simple program that executes three senders concurrently on a thread pool.Try it live ongodbolt!.

#include<stdexec/execution.hpp>#include<exec/static_thread_pool.hpp>intmain(){// Declare a pool of 3 worker threads:    exec::static_thread_poolpool(3);// Get a handle to the thread pool:auto sched = pool.get_scheduler();// Describe some work:// Creates 3 sender pipelines that are executed concurrently by passing to `when_all`// Each sender is scheduled on `sched` using `on` and starts with `just(n)` that creates a// Sender that just forwards `n` to the next sender.// After `just(n)`, we chain `then(fun)` which invokes `fun` using the value provided from `just()`// Note: No work actually happens here. Everything is lazy and `work` is just an object that statically// represents the work to later be executedauto fun = [](int i) {return i*i; };auto work =stdexec::when_all(stdexec::starts_on(sched,stdexec::just(0) |stdexec::then(fun)),stdexec::starts_on(sched,stdexec::just(1) |stdexec::then(fun)),stdexec::starts_on(sched,stdexec::just(2) |stdexec::then(fun))    );// Launch the work and wait for the resultauto [i, j, k] =stdexec::sync_wait(std::move(work)).value();// Print the results:std::printf("%d %d %d\n", i, j, k);}

• Working with Asynchrony Generically: A Tour of Executors: Part 1 (Part 2) (Video): A comprehensive introduction to Senders and structured concurrency
• What are Senders Good For, Anyway? (Blog): Demonstrates the value of a standard async programming model by wrapping a C-style async API in a sender
• From Zero to Sender/Receiver in ~60 Minutes (Video): Live-coding a toy sender/receiver implementation from scratch
• A Unifying Abstraction for Async in C++ (Video): A simple introduction to the concepts behind P2300
• A Universal Async Abstraction for C++ (Blog): An introduction to Senders
• A Universal I/O Abstraction for C++ (Blog): A look at how the Senders concepts interact withio_uring on Linux
• Structured Concurrency (Video): An explanation of structured concurrency in C++ and its benefits
• Executors: a Change of Perspective (Article): An article about the computational completeness of Senders
• Structured Concurrency in C++ (Article): An article about how Senders manifest the principles of structured concurrency
• Structured Networking in C++ (Video): A look at what a P2300-style networking library could look like
• HPCWire Article: Provides a high-level overview of the Sender model and its benefits
• NVIDIA HPC SDK Documentation: Documentation for the NVIDIA HPC SDK
• P2300 -std::execution: Senders proposal to C++ Standard

This library is header-only, so all the source code can be found in theinclude/ directory. The physical and logical structure of the code can be summarized by the following table:

There are a few ways to getstdexec:

1. Clone from GitHub
   • git clone https://github.com/NVIDIA/stdexec.git
2. Download theNVIDIA HPC SDK starting with 22.11
3. (Recommended) UseCMake Package Manager (CPM) to automatically pullstdexec as part of your CMake project.See below for more information.

You can also try it directly ongodbolt.org where it is available as a C++ library or via the nvc++ compiler starting with version 22.11 (see below for more details).

stdexec requires compiling with C++20 (-std=c++20) but otherwise does not have any dependencies and only requires a sufficiently new compiler:

• gcc 11+
• clang 16+
• XCode 16+
• nvc++ 22.11+ (required forGPU support). If usingstdexec from GitHub, then nvc++ 23.3+ is required.

How you configure your environment to usestdexec depends on how you gotstdexec.

Starting with the 22.11 release of theNVHPC SDK,stdexec is available as an experimental, opt-in feature. Specifying the--experimental-stdpar flag tonvc++ makes thestdexec headers available on the include path. You can then include anystdexec header as normal:#include <stdexec/...>,#include <nvexec/...>. Seegodbolt example.

GPU features additionally require specifying-stdpar=gpu. For more details, seeGPU Support.

As a header-only C++ library, technically all one needs to do is add thestdexecinclude/ directory to your include path as-I<stdexec root>/include in addition to specifying any necessary compile options.

For simplicity, we recommend using theCMake targets thatstdexec provides as they encapsulate the necessary configuration.

If your project uses CMake, then after cloningstdexec simply add the following to yourCMakeLists.txt:

add_subdirectory(<stdexec root>)

This will make theSTDEXEC::stdexec target available to link with your project:

target_link_libraries(my_project PRIVATE STDEXEC::stdexec)

This target encapsulates all of the necessary configuration and compiler flags for usingstdexec.

To further simplify obtaining and includingstdexec in your CMake project, we recommend usingCMake Package Manager (CPM) to fetch and configurestdexec.

Complete example:

cmake_minimum_required(VERSION 3.25.0 FATAL_ERROR)project(stdexecExample)# Get CPM# For more information on how to add CPM to your project, see: https://github.com/cpm-cmake/CPM.cmake#adding-cpminclude(CPM.cmake)CPMAddPackage(  NAME stdexec  GITHUB_REPOSITORY NVIDIA/stdexec  GIT_TAG main # This will always pull the latest code from the `main` branch. You may also use a specific release version or tag)add_executable(main example.cpp)target_link_libraries(main STDEXEC::stdexec)

stdexec provides schedulers that enable execution on NVIDIA GPUs:

• nvexec::stream_scheduler
  • Single GPU scheduler that executes on the first available GPU (device 0)
  • Defined in<nvexec/stream_context.cuh>
• nvexec::multi_gpu_stream_scheduler
  • Executes on all visible GPUs
  • Defined in<nvexec/multi_gpu_context.cuh>

These schedulers are only supported when using thenvc++ compiler with-stdpar=gpu.

Example:https://godbolt.org/z/4cEMqY8r9

stdexec is a header-only library and does not require building anything.

This section is only relevant if you wish to build thestdexec tests or examples.

The following tools are needed:

• CMake
• One of the following supported C++ compilers:
  • GCC 11+
  • clang 12+
  • nvc++ 22.11 (nvc++ 23.3+ forstdexec from GitHub)

Perform the following actions:

# Configure the projectcmake -S. -B build -G<gen># Build the projectcmake --build build

Here,<gen> can beNinja,"Unix Makefiles",XCode,"Visual Studio 15 Win64", etc.

You can set the C++ compiler via-D CMAKE_CXX_COMPILER:

# Use GCC:cmake -S. -B build/g++ -DCMAKE_CXX_COMPILER=$(which g++)cmake --build build/g++# Or clang:cmake -S. -B build/clang++ -DCMAKE_CXX_COMPILER=$(which clang++)cmake --build build/clang++

If you want to uselibc++ with clang instead oflibstdc++, you can specify the standard library as follows:

# Do the actual buildcmake -S. -B build/clang++ -G<gen> \    -DCMAKE_CXX_FLAGS=-stdlib=libc++ \    -DCMAKE_CXX_COMPILER=$(which clang++)cmake --build build/clang++

For users ofVSCode, stdexec provides aVSCode extensionthat colorizes compiler output. The highlighter recognizes the diagnosticsgenerated by the stdexec library, styling them to make them easier to pickout. Details about how to configure the extension can be foundhere.