Merge remote-tracking branch 'origin/main' into release-0.18.X

.github/dependabot.yml

@@ -0,0 +1,12 @@
+# Copyright (c) 2020 ETH Zurich
+#
+# SPDX-License-Identifier: BSL-1.0
+# Distributed under the Boost Software License, Version 1.0. (See accompanying
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"

.github/workflows/docs.yml

@@ -28,7 +28,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Install sphinx and a theme
       run: |
           sudo apt update

.github/workflows/linux_coverage.yml

@@ -18,7 +18,7 @@ jobs:
     container: pikaorg/pika-ci-base:19
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Update apt repositories for ccache
       run: apt update
     - name: Setup ccache

.github/workflows/linux_debug.yml

@@ -25,7 +25,7 @@ jobs:
     container: pikaorg/pika-ci-base:19
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Update apt repositories for ccache
       run: apt update
     - name: Setup ccache

.github/workflows/linux_hip.yml

@@ -25,7 +25,7 @@ jobs:
     runs-on: ubuntu-latest
     container: pikaorg/pika-ci-hip:12
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Update apt repositories for ccache
       run: apt update
     - name: Setup ccache

.github/workflows/linux_leaksanitizer.yml

@@ -25,7 +25,7 @@ jobs:
     container: pikaorg/pika-ci-base:19
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Update apt repositories for ccache
       run: apt update
     - name: Setup ccache

.github/workflows/linux_release_fetchcontent.yml

@@ -26,7 +26,7 @@ jobs:
     container: pikaorg/pika-ci-base:19
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Update apt repositories for ccache
       run: apt update
     - name: Setup ccache

.github/workflows/linux_sanitizers.yml

@@ -26,7 +26,7 @@ jobs:
     container: pikaorg/pika-ci-base:19
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Update apt repositories for ccache
       run: apt update
     - name: Setup ccache

.github/workflows/linux_tracy.yml

@@ -27,7 +27,7 @@ jobs:
 
     steps:
     - name: Check out Tracy
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         repository: wolfpld/tracy
         ref: v0.8.2
@@ -58,7 +58,7 @@ jobs:
           cmake --build build --target install
 
     - name: Check out pika
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         path: pika
     - name: Configure

.github/workflows/macos_arm64_debug.yml

@@ -31,7 +31,7 @@ jobs:
           brew upgrade
           brew update
           brew install boost cmake fmt hwloc ninja
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Configure
       shell: bash
       run: |

.github/workflows/macos_debug.yml

@@ -37,7 +37,7 @@ jobs:
         brew upgrade
         brew update
         brew install boost cmake fmt hwloc ninja
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Setup ccache
       uses: hendrikmuhs/[email protected]
       with:

docs/index.rst

@@ -13,6 +13,29 @@ Overview
 <https://wg21.link/p2300>`_ by providing a CPU runtime with user-level threads, as well as
 integration with CUDA, HIP, and MPI. See :ref:`getting_started` to get started.
 
+Hello, world
+============
+
+Below is a brief overview of what you can do with pika. The majority of the functionality below
+comes from ``std::execution``. pika adds a high-performance CPU runtime as well as a `std::execution
+scheduler
+<https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2300r7.html#design-schedulers>`_ to
+target the pika runtime. The stdexec repository contains `an excellent list of resources for
+learning more about std::execution <https://github.com/NVIDIA/stdexec#resources>`_ itself.
+
+.. literalinclude:: ../examples/quickstart/hello_world_documentation.cpp
+   :language: c++
+   :start-at: #include
+
+The example above should output something like:
+
+.. code-block:: bash
+
+   Hello from a pika user-level thread (with id 0x7fec6000c040)!
+   x = 42
+   Is this pi: 3.14?
+   The result is 785942.2826
+
 Acknowledgements
 ================
 

docs/usage.rst

@@ -183,6 +183,10 @@ earlier revisions of P2300. The main differences to stdexec and the proposed fac
 - The pika implementation uses ``value_types``, ``error_types``, and ``sends_done`` instead of
   ``completion_signatures`` in sender types, as in the `first 3 revisions of P2300
   <https://wg21.link/p2300r3>`_.
+- ``pika::this_thread::experimental::sync_wait`` differs from ``std::this_thread::sync_wait``
+  in that the former expects the sender to send a single value which is returned directly by
+  ``sync_wait``. If no value is sent by the sender, ``sync_wait`` returns ``void``.  Errors in
+  ``set_error`` are thrown and ``set_stopped`` is not supported.
 
 pika has an experimental CMake option ``PIKA_WITH_STDEXEC`` which can be enabled to use stdexec for
 the P2300 facilities. pika brings the ``stdexec`` namespace into ``pika::execution::experimental``,

examples/quickstart/CMakeLists.txt

@@ -16,6 +16,7 @@ set(example_programs
     fibonacci_futures
     fibonacci
     hello_world
+    hello_world_documentation
     latch_example # suffix added to avoid conflict with unit tests
     channel_example # suffix added to avoid conflict with unit tests
     channel_docs

examples/quickstart/hello_world_documentation.cpp

@@ -0,0 +1,55 @@
+//  Copyright (c) 2023 ETH Zurich
+//
+//  SPDX-License-Identifier: BSL-1.0
+//  Distributed under the Boost Software License, Version 1.0. (See accompanying
+//  file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+#include <pika/execution.hpp>
+#include <pika/init.hpp>
+
+#include <fmt/ostream.h>
+#include <fmt/printf.h>
+
+#include <iostream>
+#include <utility>
+
+int main(int argc, char* argv[])
+{
+    // Most functionality is found in the pika::execution namespace. If pika is built with stdexec,
+    // std::execution will also be found in this namespace.
+    namespace ex = pika::execution::experimental;
+    // Some additional utilities are in pika::this_thread.
+    namespace tt = pika::this_thread::experimental;
+
+    // Start the pika runtime.
+    pika::start(argc, argv);
+
+    // Create a std::execution scheduler that runs work on the default pika thread pool.
+    ex::thread_pool_scheduler sched{};
+
+    // We can schedule work using sched.
+    auto snd1 = ex::transfer_just(sched, 42) | ex::then([](int x) {
+        fmt::print(std::cout, "Hello from a pika user-level thread (with id {})!\nx = {}\n",
+            pika::this_thread::get_id(), x);
+    });
+
+    // The work is started once we call sync_wait.
+    tt::sync_wait(std::move(snd1));
+
+    // We can build arbitrary graphs of work using the split and when_all adaptors.
+    auto snd2 = ex::just(3.14) | ex::split();
+    auto snd3 = ex::transfer(snd2, sched) |
+        ex::then([](double pi) { fmt::print(std::cout, "Is this pi: {}?\n", pi); });
+    auto snd4 = ex::when_all(std::move(snd2), ex::just(500.3)) | ex::transfer(sched) |
+        ex::then([](double pi, double r) { return pi * r * r; });
+    auto result = tt::sync_wait(ex::when_all(std::move(snd3), std::move(snd4)));
+    fmt::print(std::cout, "The result is {}\n", result);
+
+    // Tell the runtime that when there are no more tasks in the queues it is ok to stop.
+    pika::finalize();
+
+    // Wait for all work to finish and stop the runtime.
+    pika::stop();
+
+    return 0;
+}