No longer a header-only library. Added support for src files to make it simpler to integrate with dynamic libraries with hidden symbols.

Added .cpp files to hold thread pool and pre-exit support code to avoid duplicates when built as/in a DLL.

Declared pre_exit and at_pre_exit as extern "C" to make them simpler to export from a DLL in an export list.

Adding an issue to make it simpler to export the default executor as well.

---------

Co-authored-by: Guillaume BOTTESI <[email protected]>
Co-authored-by: Sean Parent <[email protected]>

Author: 3 people

CMakeLists.txt

@@ -69,13 +69,7 @@ if((STLAB_MAIN_EXECUTOR STREQUAL "qt6") AND NOT Qt6Core_FOUND)
   message(SEND_ERROR "STLAB_MAIN_EXECUTOR is set to \"qt6\", but a Qt6 installation was not found.")
 endif()
 
-#
-# stlab has no compiled components. As such, we declare it as an `INTERFACE`
-# library, which denotes a collection of target propeties to be applied
-# transitively to linking targets. In our case, this ammounts to an include
-# directory, compile flags, linking flags, and links to system libraries.
-#
-add_library(stlab INTERFACE)
+add_library(stlab)
 add_library(stlab::stlab ALIAS stlab)
 
 #
@@ -84,8 +78,8 @@ add_library(stlab::stlab ALIAS stlab)
 # on how the configuration under which this library is being consumed.
 #
 target_include_directories(stlab INTERFACE
-  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>/include
-  $<BUILD_INTERFACE:${PROJECT_BINARY_DIR}>/include
+  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+  $<BUILD_INTERFACE:${PROJECT_BINARY_DIR}/include>
   $<INSTALL_INTERFACE:include>)
 
 #
@@ -98,6 +92,7 @@ target_include_directories(stlab INTERFACE
 target_compile_definitions(stlab INTERFACE $<$<CXX_COMPILER_ID:MSVC>:NOMINMAX>)
 
 add_subdirectory(include/stlab)
+add_subdirectory(src)
 
 if(NOT STLAB_THREAD_SYSTEM STREQUAL "none")
   target_link_libraries(stlab INTERFACE Threads::Threads)
@@ -130,16 +125,6 @@ write_basic_package_version_file(
   VERSION ${stlab_VERSION}
   COMPATIBILITY SameMajorVersion)
 
-#
-# As a header-only library, there are no target components to be installed
-# directly (the PUBLIC_HEADER property is not white listed for INTERFACE
-# targets for some reason).
-#
-# However, it is worthwhile export our target description in order to later
-# generate a CMake configuration file for consumption by CMake's `find_package`
-# intrinsic
-#
-
 install(
   TARGETS stlab
   EXPORT stlabTargets

CMakePresets.json

@@ -144,7 +144,8 @@
             "cacheVariables": {
                 "CMAKE_CXX_STANDARD": "17",
                 "CMAKE_BUILD_TYPE": "DEBUG",
-                "CMAKE_CXX_INCLUDE_WHAT_YOU_USE": "include-what-you-use;-Xiwyu;--mapping_file=/usr/local/Cellar/include-what-you-use/0.23/libexec/share/include-what-you-use/boost-all.imp"
+                "CMAKE_CXX_INCLUDE_WHAT_YOU_USE":
+                    "include-what-you-use;-Xiwyu;--mapping_file=/usr/local/Cellar/include-what-you-use/0.23/libexec/share/include-what-you-use/boost-all.imp"
             }
         }
     ],
@@ -170,7 +171,7 @@
             "description": "",
             "displayName": "",
             "configurePreset": "ninja-cpp20-debug-thread-undefined",
-            "output":{
+            "output": {
                 "verbosity": "verbose"
             }
         }

docs/_data/contributors.json

@@ -41,7 +41,7 @@
         "type": "User",
         "user_view_type": "public",
         "site_admin": false,
-        "contributions": 167
+        "contributions": 170
     },
     {
         "login": "fosterbrereton",

docs/include/stlab/pre_exit.hpp/f_at_pre_exit.md

@@ -8,7 +8,7 @@ hyde:
     - function
   inline:
     brief:
-      - Register a pre-exit handler. The pre-exit-handler may not throw. With C++17 or later it is required to be `noexcept`.
+      - Register a pre-exit handler. The `pre-exit-handler` may not throw. With C++17 or later it is required to be `noexcept`.
   defined_in_file: stlab/pre_exit.hpp
   overloads:
     void at_pre_exit(stlab::pre_exit_handler):
@@ -19,10 +19,10 @@ hyde:
       description: Register the `pre_exit_handler` to be called on [`pre_exit()`](./f_pre_exit.html). The functions are called in the reverse order that they are registered.
       inline:
         description:
-          - Register a pre-exit handler. The pre-exit-handler may not throw. With C++17 or later it is required to be `noexcept`.
+          - Register a pre-exit handler. The `pre-exit-handler` may not throw. With C++17 or later it is required to be `noexcept`.
       return: __OPTIONAL__
       signature_with_names: void at_pre_exit(stlab::pre_exit_handler f)
   namespace:
     - stlab
-    - v1
+    - v2
 ---

docs/include/stlab/pre_exit.hpp/f_pre_exit.md

@@ -20,5 +20,5 @@ hyde:
       signature_with_names: void pre_exit()
   namespace:
     - stlab
-    - v1
+    - v2
 ---

docs/include/stlab/pre_exit.hpp/f_stlab_at_pre_exit.md

@@ -0,0 +1,28 @@
+---
+layout: function
+title: stlab_at_pre_exit
+hyde:
+  owner: __MISSING__
+  brief: __INLINED__
+  tags:
+    - function
+  inline:
+    brief:
+      - An `extern "C"` vector for `at_pre-exit()` to make it simpler to export the function from a shared library.
+  defined_in_file: stlab/pre_exit.hpp
+  overloads:
+    void stlab_at_pre_exit(stlab::pre_exit_handler):
+      arguments:
+        - description: __OPTIONAL__
+          name: f
+          type: stlab::pre_exit_handler
+      description: __INLINED__
+      inline:
+        description:
+          - An `extern "C"` vector for `at_pre-exit()` to make it simpler to export the function from a shared library.
+      return: __OPTIONAL__
+      signature_with_names: void stlab_at_pre_exit(stlab::pre_exit_handler f)
+  namespace:
+    - stlab
+    - v2
+---

docs/include/stlab/pre_exit.hpp/f_stlab_pre_exit.md

@@ -0,0 +1,24 @@
+---
+layout: function
+title: stlab_pre_exit
+hyde:
+  owner: __MISSING__
+  brief: __INLINED__
+  tags:
+    - function
+  inline:
+    brief:
+      - An `extern "C"` vector for `pre-exit()` to make it simpler to export the function from a shared library.
+  defined_in_file: stlab/pre_exit.hpp
+  overloads:
+    void stlab_pre_exit():
+      description: __INLINED__
+      inline:
+        description:
+          - An `extern "C"` vector for `pre-exit()` to make it simpler to export the function from a shared library.
+      return: __OPTIONAL__
+      signature_with_names: void stlab_pre_exit()
+  namespace:
+    - stlab
+    - v2
+---

docs/tools/docker-tools/README.md

@@ -75,7 +75,7 @@ This should leave you at a bash prompt that looks like this:
 app@fc7590a63ba3:~$
 ```
 
-The hex number is the docker image container ID and may be different. Going foreward I refer to this as the _docker_ prompt to distinguish it from the _local_ prompt.
+The hex number is the docker image container ID and may be different. Going foreword I refer to this as the _docker_ prompt to distinguish it from the _local_ prompt.
 
 ```
 cd /mnt/host

include/stlab/CMakeLists.txt

@@ -44,7 +44,7 @@ stlab_generate_config_file()
 target_sources( stlab INTERFACE
   FILE_SET stlab
   TYPE HEADERS
-  BASE_DIRS ${PROJECT_BINARY_DIR}
+  BASE_DIRS ${PROJECT_BINARY_DIR}/include
   FILES
-    ${PROJECT_BINARY_DIR}/stlab/config.hpp
+    ${PROJECT_BINARY_DIR}/include/stlab/config.hpp
 )

include/stlab/concurrency/default_executor.hpp

@@ -11,25 +11,22 @@
 
 #include <stlab/config.hpp>
 
-#include <stlab/pre_exit.hpp>
-
-#include <stlab/concurrency/set_current_thread_name.hpp>
-#include <stlab/concurrency/task.hpp>
-
 #include <cassert>
-#include <chrono>
 #include <cstdint>
-#include <functional>
-#include <memory>
 #include <type_traits>
 #include <utility>
 
 #if STLAB_TASK_SYSTEM(LIBDISPATCH)
 #include <dispatch/dispatch.h>
 #elif STLAB_TASK_SYSTEM(WINDOWS)
+#include <stlab/pre_exit.hpp>
+
 #include <Windows.h>
 #include <memory>
 #elif STLAB_TASK_SYSTEM(PORTABLE)
+#include <stlab/concurrency/set_current_thread_name.hpp>
+#include <stlab/concurrency/task.hpp>
+
 #include <algorithm>
 #include <atomic>
 #include <climits>
@@ -79,17 +76,7 @@ struct group_t {
     }
 };
 
-inline auto group() -> group_t& {
-    // Use an immediately executed lambda to atomically register pre-exit handler
-    // and create the dispatch group.
-    static group_t g{[] {
-        at_pre_exit([]() noexcept { // <br>
-            dispatch_group_wait(g._group, DISPATCH_TIME_FOREVER);
-        });
-        return group_t{};
-    }()};
-    return g;
-}
+group_t& group();
 
 template <executor_priority P = executor_priority::medium>
 struct executor_type {
@@ -452,15 +439,7 @@ class priority_task_system {
 /// Returns an instance of the task system singleton. An immediately executed lambda is used
 /// to register the the task system for tear down pre-exit in a thread safe manner.
 
-inline priority_task_system& pts() {
-    // Uses the `nullptr` constructor with an immediate executed lambda to register the task
-    // system in a thread safe manner.
-    static priority_task_system only_task_system{[] {
-        at_pre_exit([]() noexcept { only_task_system.join(); });
-        return nullptr;
-    }()};
-    return only_task_system;
-}
+priority_task_system& pts();
 
 #endif
 

include/stlab/pre_exit.hpp

@@ -10,16 +10,10 @@
 
 /**************************************************************************************************/
 
-#include <cassert>
-#include <mutex>
-#include <vector>
-
-/**************************************************************************************************/
-
 // The namespace for pre_exit cannot be changed without an ABI break. If making an ABI breaking
 // change in this file it needs to be done in a way supporting this version as well.
 namespace stlab {
-inline namespace v1 {
+inline namespace v2 {
 
 /**************************************************************************************************/
 
@@ -30,68 +24,25 @@ using pre_exit_handler = void (*)() noexcept;
 using pre_exit_handler = void (*)();
 #endif
 
-namespace detail {
-
-/// Thread-safe stack of pre-exit handlers. The stack closes after the last element is popped.
-struct _pre_exit_stack_t {
-    using lock_t = std::unique_lock<std::mutex>;
-
-    std::mutex _mutex;
-    std::vector<pre_exit_handler> _stack;
-    bool _closed{false};
-
-    /// Push an exit handler. Precondition that stack is not closed.
-    void push(pre_exit_handler f) {
-        lock_t lock{_mutex};
-        assert(
-            !_closed &&
-            "WARNING: Adding pre-exit handler with `at_pre_exit()` after `pre_exit()` completed.");
-        _stack.push_back(f);
-    }
-
-    /// Pop one exit handler, returns `nullptr` and closes stack if empty.
-    auto pop() -> pre_exit_handler {
-        lock_t lock{_mutex};
-        if (_stack.empty()) {
-            assert(!_closed && "WARNING `pre_exit()` invoked more than once.");
-            _closed = true;
-            return nullptr;
-        }
-        auto result = _stack.back();
-        _stack.pop_back();
-        return result;
-    }
-
-    ~_pre_exit_stack_t() {
-        assert(_closed && "WARNING: `pre_exit()` not called before program exit.");
-    }
-};
-
-/// Returns a reference to the pre-exit stack singleton.
-inline auto _pre_exit_stack() -> auto& {
-    static _pre_exit_stack_t _q;
-    return _q;
-}
-
-} // namespace detail
+/// An `extern "C"` vector for `pre-exit()` to make it simpler to
+/// export the function from a shared library.
+extern "C" void stlab_pre_exit();
+/// An `extern "C"` vector for `at_pre-exit()` to make it simpler to
+/// export the function from a shared library.
+extern "C" void stlab_at_pre_exit(pre_exit_handler f);
 
 /// Invoke all registered pre-exit handlers in the reverse order they are registered. It is safe
 /// to register additional handlers during this operation. Must be invoked exactly once prior to
 /// program exit.
-inline void pre_exit() {
-    auto& _s = detail::_pre_exit_stack();
-    while (auto f = _s.pop()) {
-        f();
-    };
-}
+inline void pre_exit() { stlab_pre_exit(); }
 
-/// Register a pre-exit handler. The pre-exit-handler may not throw. With C++17 or later it
+/// Register a pre-exit handler. The `pre-exit-handler` may not throw. With C++17 or later it
 /// is required to be `noexcept`.
-inline void at_pre_exit(pre_exit_handler f) { detail::_pre_exit_stack().push(f); }
+inline void at_pre_exit(pre_exit_handler f) { stlab_at_pre_exit(f); }
 
 /**************************************************************************************************/
 
-} // namespace v1
+} // namespace v2
 } // namespace stlab
 
 /**************************************************************************************************/

include/stlab/utility.hpp

@@ -14,7 +14,10 @@
 #include <stlab/config.hpp>
 
 #include <array>
-#include <type_traits>
+#include <cstddef>          // for size_t
+#include <initializer_list> // for initializer_list
+#include <type_traits>      // for remove_reference, is_same, is_const
+#include <utility>          // for index_sequence, forward
 
 /**************************************************************************************************/
 
@@ -76,8 +79,7 @@ template <class Seq, template <std::size_t> class F, std::size_t Index, std::siz
 struct index_sequence_transform;
 
 template <class Seq,
-          template <std::size_t>
-          class F,
+          template <std::size_t> class F,
           std::size_t Index = 0,
           std::size_t Count = Seq::size()>
 using index_sequence_transform_t = typename index_sequence_transform<Seq, F, Index, Count>::type;

src/CMakeLists.txt

@@ -0,0 +1,7 @@
+target_sources(stlab PRIVATE pre_exit.cpp concurrency/default_executor.cpp)
+target_include_directories(stlab PRIVATE ${CMAKE_SOURCE_DIR}/include ${CMAKE_BINARY_DIR}/include)
+target_compile_definitions(stlab PRIVATE $<$<CXX_COMPILER_ID:MSVC>:NOMINMAX>)
+
+if(BUILD_SHARED_LIBS)
+    set_target_properties(stlab PROPERTIES WINDOWS_EXPORT_ALL_SYMBOLS ON)
+endif()