Refactor and document parts of pika/init.hpp

.github/workflows/docs.yml

@@ -36,10 +36,15 @@ jobs:
                 --allow-downgrades \
                 --allow-remove-essential \
                 --allow-change-held-packages \
-                python3 python3-pip
-            pip install sphinx sphinx-material
+                doxygen python3 python3-pip
+            pip install breathe sphinx sphinx-material
       - name: Build documentation
-        run: sphinx-build -W -n -a -b html docs build/docs
+        run: |
+            export PIKA_DOCS_DOXYGEN_OUTPUT_DIRECTORY=$PWD/build/docs/doxygen
+            export PIKA_DOCS_DOXYGEN_INPUT_ROOT=$PWD
+            mkdir -p $PIKA_DOCS_DOXYGEN_OUTPUT_DIRECTORY
+            doxygen docs/Doxyfile
+            sphinx-build -W -a -b html docs $PWD/build/docs
       - name: Upload HTML output as artifact
         uses: actions/upload-pages-artifact@v2
         with:

.inshpect.toml

@@ -202,6 +202,7 @@ patterns = [
 [includes]
 enable = true
 patterns = [
+    { pattern = '\bEXIT_(SUCCESS|FAILURE)\b', include = 'cstdlib' },
     { pattern = '\bstd::make_shared\b', include = 'memory' },
     { pattern = '\bstd::map\b', include = 'map' },
     { pattern = '\bstd::set\b', include = 'set' },

docs/Doxyfile

@@ -0,0 +1,18 @@
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = "pika"
+GENERATE_XML           = YES
+GENERATE_LATEX         = NO
+GENERATE_MAN           = NO
+GENERATE_RTF           = NO
+GENERATE_HTML          = NO
+QUIET                  = NO
+OUTPUT_DIRECTORY       = "$(PIKA_DOCS_DOXYGEN_OUTPUT_DIRECTORY)"
+INPUT                  = "$(PIKA_DOCS_DOXYGEN_INPUT_ROOT)/libs/pika/init_runtime"
+FILE_PATTERNS          = *.cpp *.hpp *.cu
+RECURSIVE              = YES
+EXCLUDE_PATTERNS       = */test */detail
+EXCLUDE_SYMBOLS        = "*detail*"
+ENABLE_PREPPROCESSING  = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+PREDEFINED             = PIKA_EXPORT=

docs/_static/pika.css

@@ -30,3 +30,7 @@
 .md-header-nav__topic {
     font-weight: bold;
 }
+
+.md-typeset .headerlink {
+    opacity: 1;
+}

docs/api.rst

@@ -18,6 +18,13 @@ even in patch versions.
 The API reference is a work in progress. The following headers are part of the public API. Any other
 headers are internal implementation details.
 
+.. contents::
+   :local:
+   :depth: 1
+   :backlinks: none
+
+These headers are part of the public API, but are currently undocumented.
+
 - ``pika/async_rw_mutex.hpp``
 - ``pika/barrier.hpp``
 - ``pika/condition_variable.hpp``
@@ -31,6 +38,28 @@ headers are internal implementation details.
 - ``pika/shared_mutex.hpp``
 - ``pika/thread.hpp``
 
-All functionality in a namespace containing ``detail`` and all macros prefixed
-with ``PIKA_DETAIL`` are implementation details and may change without warning
-at any time.
+All functionality in a namespace containing ``detail`` and all macros prefixed with ``PIKA_DETAIL``
+are implementation details and may change without warning at any time. All functionality in a
+namespace containing ``experimental`` may change without warning at any time. However, the intention
+is to stabilize those APIs over time.
+
+.. _header_pika_init:
+
+``pika/init.hpp``
+=================
+
+The ``pika/init.hpp`` header provides functionality to manage the pika runtime.
+
+.. literalinclude:: ../examples/documentation/init_hpp_documentation.cpp
+   :language: c++
+   :start-at: #include
+
+.. doxygenfunction:: start(int argc, const char *const *argv, init_params const &params)
+.. doxygenfunction:: stop()
+.. doxygenfunction:: finalize()
+.. doxygenfunction:: wait()
+.. doxygenfunction:: resume()
+.. doxygenfunction:: suspend()
+
+.. doxygenstruct:: pika::init_params
+   :members:

docs/conf.py

@@ -5,6 +5,7 @@
 # file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
 from datetime import datetime
+import os
 
 # Project settings
 project = "pika"
@@ -14,13 +15,23 @@
 release = version
 
 # General sphinx settings
-extensions = []
+extensions = ["breathe"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 source_suffix = [".rst"]
 language = "English"
 primary_domain = "cpp"
 highlight_language = "cpp"
 
+breathe_projects = {"pika": os.getenv("PIKA_DOCS_DOXYGEN_OUTPUT_DIRECTORY") + "/xml"}
+breathe_default_project = "pika"
+breathe_domain_by_extension = {
+    "hpp": "cpp",
+    "cpp": "cpp",
+    "cu": "cpp",
+}
+breathe_default_members = ("members",)
+breathe_show_include = False
+
 # HTML settings
 html_title = "pika"
 html_theme = "sphinx_material"
@@ -38,7 +49,8 @@
     "repo_url": "https://github.com/pika-org/pika",
     "repo_name": "pika",
     "html_minify": False,
-    "html_prettify": True,
+    # Disabled because of https://github.com/bashtage/sphinx-material/issues/123
+    "html_prettify": False,
     "logo_icon": "",
     "css_minify": True,
     "repo_type": "github",

docs/index.rst

@@ -23,7 +23,7 @@ scheduler
 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
+.. literalinclude:: ../examples/documentation/hello_world_documentation.cpp
    :language: c++
    :start-at: #include
 

examples/1d_stencil/1d_stencil_1.cpp

@@ -17,6 +17,7 @@
 #include <chrono>
 #include <cstddef>
 #include <cstdint>
+#include <cstdlib>
 #include <iostream>
 #include <vector>
 
@@ -104,7 +105,8 @@ int pika_main(pika::program_options::variables_map& vm)
     std::uint64_t const os_thread_count = pika::get_os_thread_count();
     print_time_results(os_thread_count, elapsed, nx, nt, header);
 
-    return pika::finalize();
+    pika::finalize();
+    return EXIT_SUCCESS;
 }
 
 int main(int argc, char* argv[])

examples/1d_stencil/1d_stencil_2.cpp

@@ -27,6 +27,7 @@
 #include <chrono>
 #include <cstddef>
 #include <cstdint>
+#include <cstdlib>
 #include <iostream>
 #include <vector>
 
@@ -138,7 +139,8 @@ int pika_main(pika::program_options::variables_map& vm)
     std::uint64_t const os_thread_count = pika::get_os_thread_count();
     print_time_results(os_thread_count, elapsed, nx, nt, header);
 
-    return pika::finalize();
+    pika::finalize();
+    return EXIT_SUCCESS;
 }
 
 int main(int argc, char* argv[])

examples/1d_stencil/1d_stencil_3.cpp

@@ -20,6 +20,7 @@
 #include <chrono>
 #include <cstddef>
 #include <cstdint>
+#include <cstdlib>
 #include <iostream>
 #include <vector>
 
@@ -167,7 +168,8 @@ int pika_main(pika::program_options::variables_map& vm)
     std::uint64_t const os_thread_count = pika::get_os_thread_count();
     print_time_results(os_thread_count, elapsed, nx, np, nt, header);
 
-    return pika::finalize();
+    pika::finalize();
+    return EXIT_SUCCESS;
 }
 
 int main(int argc, char* argv[])

examples/CMakeLists.txt

@@ -6,7 +6,9 @@
 # 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)
 
-set(subdirs 1d_stencil balancing future_reduce jacobi_smp quickstart)
+set(subdirs 1d_stencil balancing documentation future_reduce jacobi_smp
+            quickstart
+)
 
 foreach(subdir ${subdirs})
   if(PIKA_WITH_TESTS AND PIKA_WITH_TESTS_EXAMPLES)

examples/documentation/CMakeLists.txt

@@ -0,0 +1,30 @@
+# 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)
+
+set(example_programs hello_world_documentation init_hpp_documentation)
+
+foreach(example_program ${example_programs})
+  set(sources ${example_program}.cpp)
+
+  source_group("Source Files" FILES ${sources})
+
+  pika_add_executable(
+    ${example_program} INTERNAL_FLAGS
+    SOURCES ${sources} ${${example_program}_FLAGS}
+    FOLDER "Examples/Documentation"
+  )
+
+  target_link_libraries(
+    ${example_program} PRIVATE ${${example_program}_LIBRARIES}
+  )
+  pika_add_example_target_dependencies("documentation" ${example_program})
+
+  if(PIKA_WITH_TESTS AND PIKA_WITH_TESTS_EXAMPLES)
+    pika_add_example_test(
+      "documentation" ${example_program} ${${example_program}_PARAMETERS}
+    )
+  endif()
+endforeach()

examples/documentation/init_hpp_documentation.cpp

@@ -0,0 +1,26 @@
+//  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/printf.h>
+
+int main(int argc, char* argv[])
+{
+    pika::start(argc, argv);
+
+    // The pika runtime is now active and we can schedule work on the default thread pool
+    pika::this_thread::experimental::sync_wait(
+        pika::execution::experimental::schedule(
+            pika::execution::experimental::thread_pool_scheduler{}) |
+        pika::execution::experimental::then([]() { fmt::print("Hello from the pika runtime\n"); }));
+
+    pika::finalize();
+    pika::stop();
+
+    return 0;
+}

examples/future_reduce/rnd_future_reduce.cpp

@@ -9,6 +9,7 @@
 #include <pika/init.hpp>
 #include <pika/runtime.hpp>
 //
+#include <cstdlib>
 #include <iostream>
 #include <random>
 #include <utility>
@@ -106,7 +107,8 @@ int pika_main()
               << "\n " << htimer.elapsed<std::chrono::seconds>() << " seconds \n"
               << std::flush;
     // Initiate shutdown of the runtime system.
-    return pika::finalize();
+    pika::finalize();
+    return EXIT_SUCCESS;
 }
 
 //----------------------------------------------------------------------------

examples/hello_world_standalone/hello_world.cpp

@@ -7,13 +7,15 @@
 #include <pika/init.hpp>
 #include <pika/thread.hpp>
 
+#include <cstdlib>
 #include <iostream>
 
 int pika_main()
 {
     std::cout << "Hello from pika-thread with id " << pika::this_thread::get_id() << std::endl;
 
-    return pika::finalize();
+    pika::finalize();
+    return EXIT_SUCCESS;
 }
 
 int main(int argc, char* argv[]) { return pika::init(pika_main, argc, argv); }

examples/jacobi_smp/jacobi.cpp

@@ -12,6 +12,7 @@
 #include <pika/modules/program_options.hpp>
 
 #include <cstddef>
+#include <cstdlib>
 #include <iostream>
 #include <string>
 
@@ -61,7 +62,8 @@ int pika_main(variables_map& vm)
 #if defined(JACOBI_SMP_NO_pika)
     return 0;
 #else
-    return pika::finalize();
+    pika::finalize();
+    return EXIT_SUCCESS;
 #endif
 }
 

examples/quickstart/CMakeLists.txt

@@ -11,7 +11,6 @@ set(example_programs
     event_synchronization
     fibonacci
     hello_world
-    hello_world_documentation
     latch_example # suffix added to avoid conflict with unit tests
     pipeline1
     # shared_mutex # Disabled due to unavailable timed suspension timed_wake #

examples/quickstart/command_line_handling.cpp

@@ -9,6 +9,7 @@
 
 #include <pika/modules/program_options.hpp>
 
+#include <cstdlib>
 #include <string>
 #include <vector>
 
@@ -27,7 +28,8 @@ int pika_main(pika::program_options::variables_map& vm)
     }
     else { pika::cout << "no positional command line options\n"; }
 
-    return pika::finalize();
+    pika::finalize();
+    return EXIT_SUCCESS;
 }
 
 int main(int argc, char* argv[])

examples/quickstart/customize_async.cpp

@@ -13,6 +13,7 @@
 #include <pika/thread.hpp>
 
 #include <algorithm>
+#include <cstdlib>
 #include <iostream>
 
 namespace ex = pika::execution::experimental;
@@ -75,7 +76,8 @@ int pika_main()
         tt::sync_wait(ex::schedule(fancy_scheduler) | ex::then(run_with_large_stack));
     }
 
-    return pika::finalize();
+    pika::finalize();
+    return EXIT_SUCCESS;
 }
 
 int main(int argc, char* argv[]) { return pika::init(pika_main, argc, argv); }

examples/quickstart/enumerate_threads.cpp

@@ -10,6 +10,7 @@
 #include <pika/latch.hpp>
 #include <pika/thread.hpp>
 
+#include <cstdlib>
 #include <functional>
 #include <iostream>
 #include <utility>
@@ -56,7 +57,8 @@ int pika_main()
 
     tt::sync_wait(ex::when_all_vector(std::move(results)));
 
-    return pika::finalize();
+    pika::finalize();
+    return EXIT_SUCCESS;
 }
 
 int main(int argc, char* argv[]) { return pika::init(pika_main, argc, argv); }