thread.hpp

Go to the documentation of this file.

/**
 * @file
 * @ingroup numapp
 * @copyright ESO 2024 - European Southern Observatory
 *
 * @brief Contains declarations for numapp thread utilities
 *
 * @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.
 *
 * 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
 * @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) {
    auto trampoline = detail::ThreadInitializer(thread_name, policies);
    auto thr = std::thread(
        [&, func = std::bind(std::forward<Func>(func), std::forward<Args>(args)...)]() mutable {
            if (trampoline.Initialize() != std::error_code()) {
                // Abort
                return;
            }
            // Finally run
            func();
        });
    // 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.
 *
 * 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) {
    constexpr bool wants_stop_token = std::is_invocable_v<Func, std::stop_token const&, Args...>;
 
    auto trampoline = detail::ThreadInitializer(thread_name, policies);
    auto thr = std::jthread([&,
                             func = detail::TokenPrepender<wants_stop_token>::Bind(
                                 std::forward<Func>(func), std::forward<Args>(args)...)](
                                std::stop_token const& token) mutable {
        if (trampoline.Initialize() != std::error_code()) {
            // Abort
            return;
        }
        // Finally run, with or without std::stop_token
        if constexpr (wants_stop_token) {
            func(token);
        } else {
            func();
        }
    });
    // 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_