thread.hpp

Go to the documentation of this file.

/**
 * @file
 * @ingroup numapp
 * @brief Contains declarations for numapp thread utilities
 * @copyright
 *   SPDX-FileCopyrightText: 2020-2026 European Southern Observatory (ESO)
 *
 *   SPDX-License-Identifier: LGPL-3.0-only
 *
 * @defgroup numapp_thread Thread APIs
 * @ingroup numapp
 * @brief NUMA++ thread APIs
 */
#ifndef NUMAPP_THREAD_HPP_
#define NUMAPP_THREAD_HPP_
#include <numapp/config.hpp>
 
#include <string>
#include <string_view>
#include <system_error>
#include <thread>
#include <type_traits>
 
#include <numapp/detail/thread.hpp>
#include <numapp/numapolicies.hpp>
 
namespace numapp {
namespace thisThread {
 
/**
 * Query the thread id "TID" of the current thread.
 *
 * @note This is the Kernel task identifier and is unrelated to any pthread id.
 *
 * It is provided in NUMA++ as @c gettid() is not provided by glibc.
 *
 * @return callers thread ID.
 *
 * @manpages
 * @manpage{gettid,2}
 *
 * @ingroup numapp_thread
 */
[[nodiscard]] pid_t GetThreadId() noexcept;
 
/**
 * Set thread name for current thread.
 *
 * @param thread_name Name of thread. Maximum length (`thread_name.length()`) is 15.
 * @param[out] ec out-parameter for error reporting.
 *  - std::errc::result_out_of_range if thread_name is longer than 16 characters.
 *  - other errors propagated from underlying prctl call.
 *
 * @sa GetThreadName()
 * @ingroup numapp_thread
 */
void SetThreadName(std::string_view thread_name, std::error_code& ec) noexcept;
 
/**
 * Set thread name for current thread (throwing version).
 *
 * @param thread_name Name of thread. Maximum length (`thread_name.length()`) is 15.
 * @throws std::system_error on errors.
 *
 * @sa GetThreadName()
 * @ingroup numapp_thread
 */
void SetThreadName(std::string_view thread_name);
 
/**
 * Get name of current thread.
 *
 * @param[out] ec out-parameter for error reporting.
 *
 * @return string containing current thread name.
 * @return empty string if error occurs (error is reported in @a ec).
 * @throws std::bad_alloc if allocation fails.
 * @sa SetThreadName()
 * @ingroup numapp_thread
 */
[[nodiscard]] std::string GetThreadName(std::error_code& ec) noexcept;
 
/**
 * Get name of current thread (throwing version).
 *
 * @return string containing current thread name.
 * @return empty string if error occurs (error is reported in @a ec).
 * @throws std::bad_alloc if allocation fails.
 * @sa SetThreadName()
 * @ingroup numapp_thread
 */
[[nodiscard]] std::string GetThreadName();
 
}  // namespace thisThread
 
/**
 * @name Makes a std::thread or std::jthread with provided NUMA policies
 * @anchor make_thread
 * Create a named thread with optional CPU affinity, scheduler and memory policies.
 *
 * Function has the following effects in this thread `(P)arent` and new thread `(C)hild`:
 *
 * - <sup>(P)</sup>Create std::thread with an unspecified *thread-setup* function as target.
 * - <sup>(P)</sup>Wait for child to be created and complete setup.
 * - <sup>(C)</sup>Function will set thread name and apply policies.
 * - <sup>(C)</sup>Function will apply memory policy to thread stack memory which will move
 *   physical pages if necessary. This is done with strict MemPolicyFlag such that if moving pages
 *   fails the thread creation will fail.
 * - <sup>(C)</sup>Function signals parent thread with success/failure.
 * - <sup>(C)</sup>If setup was successful invoke @c func with @a args, and in case of std::jthread
 *   the associated `std::stop_token` if func is invocable with it, otherwise return.
 * - <sup>(P)</sup>Wake on signal from child:
 *   - If setup of new thread failed it will join with thread and throw @c std:system_error
 *     containing error.
 *   - On success it returns thread.
 *
 * @param thread_name Name of thread, Must be maximum 16 characters (15 + '\0').
 * @param policies The NUMA policies to apply.
 * @param func Callable invoked in new thread.
 * @param args Arguments for func which will be decay-copied. Use `std::reference_wrapper` to pass
 * references (remember: caller must ensure the life-time of references objects).
 * @throws std::system_error if new thread failed to apply policies.
 *
 * @tparam Func MoveConstructible function to invoke in new thread.
 * @tparam Args MoveConstructible arguments to decay copy and call Func with in new thread.
 *
 * Minimum application example with a `main()` function:
 * @include makeThreadExample.cpp
 *
 * Example function that create pinned thread with local NUMA node memory policy:
 * @include makeThreadExample2.cpp
 *
 * Similar to first example, but uses member function instead:
 * @include makeThreadExample3.cpp
 *
 * @ingroup numapp_thread
 */
/// @{
/**
 * Primary overload accepting string-view for @c thread_name.
 *
 * See @ref make_thread "MakeThread group" for detailed documentation.
 * @ingroup numapp_thread
 */
template <class Func, class... Args>
[[nodiscard]] std::thread MakeThread(std::string_view thread_name,
                                     NumaPolicies const& policies,
                                     Func&& func,
                                     Args&&... args) {
    static_assert(std::is_constructible_v<std::decay_t<Func>, Func>,
                  "ill formed - Func must be MoveConstructible");
    static_assert((std::is_constructible_v<std::decay_t<Args>, Args> && ...),
                  "ill formed - Args must be MoveConstructible");
    static_assert(std::is_invocable_v<std::decay_t<Func>, std::decay_t<Args>...>,
                  "ill formed - Func must be invocable with Args");
 
    auto trampoline = detail::ThreadInitializer(thread_name, policies);
 
    // note: let std::thread forward arguments rather than capturing in lambda as it would make
    // lambda non-copyable/movable if combinations of args is non-copyable/movable.
    auto thr = std::thread(
        [&trampoline, func = std::forward<Func>(func)](auto&&... args) mutable {
            if (trampoline.Initialize() != std::error_code()) {
                // Abort
                return;
            }
            // Finally run
            std::invoke(std::move(func), std::move(args)...);
        },
        std::forward<Args>(args)...);
    // Wait for thread to start to complete
    auto result = trampoline.Wait();
    if (result.code()) {
        // Thread failed to set name or apply policy
        thr.join();
        throw std::system_error(result);
    }
    return thr;
}
 
/**
 * Compatibility overload accepting null terminated C string for thread_name.
 *
 * See @ref make_thread "MakeThread group" for detailed documentation.
 * @ingroup numapp_thread
 */
template <class Func, class... Args>
[[nodiscard]] std::thread
MakeThread(char const* thread_name, NumaPolicies const& policies, Func&& func, Args&&... args) {
    return MakeThread(std::string_view(thread_name),
                      policies,
                      std::forward<Func>(func),
                      std::forward<Args>(args)...);
}
 
#ifdef __cpp_lib_jthread  // C++20
 
/**
 * Create std::jthread with specified named and NUMA policies.
 *
 * @note Like `std::jthread` it can optionally accept a `std::stop_token` as the first
 * argument.
 *
 * @tparam Func MoveConstructible function to invoke in new thread. Func may optionally take
 * `std::stop_token` as first argument.
 * @tparam Args MoveConstructible arguments to decay copy and call Func with in new thread.
 *
 * See @ref make_thread "MakeThread group" for detailed documentation.
 * @ingroup numapp_thread
 */
template <class Func, class... Args>
[[nodiscard]] std::jthread MakeJthread(std::string_view thread_name,
                                       NumaPolicies const& policies,
                                       Func&& func,
                                       Args&&... args) {
    static_assert(std::is_constructible_v<std::decay_t<Func>, Func>,
                  "ill formed - Func must be MoveConstructible");
    static_assert((std::is_constructible_v<std::decay_t<Args>, Args> && ...),
                  "ill formed - Args must be MoveConstructible");
    static_assert(
        std::is_invocable_v<std::decay_t<Func>, std::decay_t<Args>...> ||
            std::is_invocable_v<std::decay_t<Func>, std::stop_token, std::decay_t<Args>...>,
        "ill formed - Func must be invocable with Args, with our without stop token");
 
    auto trampoline = detail::ThreadInitializer(thread_name, policies);
    // note: let std::thread forward arguments rather than capturing in lambda as it would make
    // lambda non-copyable/movable if combinations of args is non-copyable/movable.
    auto thr = std::jthread(
        [&trampoline, func = std::forward<Func>(func)](std::stop_token const& token,
                                                       auto&&... args) mutable {
            if (trampoline.Initialize() != std::error_code()) {
                // Abort
                return;
            }
            // Finally run, with or without std::stop_token
            if constexpr (std::is_invocable_v<std::decay_t<Func>,
                                              std::stop_token,
                                              std::decay_t<Args>...>) {
                std::invoke(std::move(func), token, std::move(args)...);
            } else {
                std::invoke(std::move(func), std::move(args)...);
            }
        },
        std::forward<Args>(args)...);
 
    // Wait for thread to start to complete
    auto result = trampoline.Wait();
    if (result.code()) {
        // Thread failed to set name or apply policy
        thr.join();
        throw std::system_error(result);
    }
 
    return thr;
}
 
#endif
/// @}
 
}  // namespace numapp
#endif  // NUMAPP_THREAD_HPP_