NUMA++ 0.11.0
Loading...
Searching...
No Matches
Namespaces | Functions
thread.hpp File Reference
NUMA++

Contains declarations for numapp thread utilities. More...

#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>

Go to the source code of this file.

Namespaces

namespace  numapp
 

Functions

pid_t numapp::thisThread::GetThreadId () noexcept
 Query the thread id "TID" of the current thread.
 
void numapp::thisThread::SetThreadName (std::string_view thread_name, std::error_code &ec) noexcept
 Set thread name for current thread.
 
void numapp::thisThread::SetThreadName (std::string_view thread_name)
 Set thread name for current thread (throwing version).
 
std::string numapp::thisThread::GetThreadName (std::error_code &ec) noexcept
 Get name of current thread.
 
std::string numapp::thisThread::GetThreadName ()
 Get name of current thread (throwing version).
 
Makes a std::thread or std::jthread with provided NUMA policies

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:

  • (P)Create std::thread with an unspecified thread-setup function as target.
  • (P)Wait for child to be created and complete setup.
  • (C)Function will set thread name and apply policies.
  • (C)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.
  • (C)Function signals parent thread with success/failure.
  • (C)If setup was successful invoke func with args, and in case of std::jthread the associated std::stop_token if func is invocable with it, otherwise return.
  • (P)Wake on signal from child:
    • If setup of new thread failed it will join with thread and throw std:system_error containing error.
    • On success it returns thread.
Parameters
thread_nameName of thread, Must be maximum 16 characters (15 + '\0').
policiesThe NUMA policies to apply.
funcCallable invoked in new thread.
argsArguments for func which will be decay-copied. Use std::reference_wrapper to pass references (remember: caller must ensure the life-time of references objects).
Exceptions
std::system_errorif new thread failed to apply policies.
Template Parameters
FuncMoveConstructible function to invoke in new thread.
ArgsMoveConstructible arguments to decay copy and call Func with in new thread.

Minimum application example with a main() function:

#include <chrono>
#include <iostream>
#include <numapp/numa.hpp>
#include <numapp/thread.hpp>
void ThreadFunc(std::chrono::milliseconds duration) {
std::cout << "Thread affinity: " << numapp::CpuAffinity::MakeFromActive() << std::endl;
std::this_thread::sleep_for(duration);
}
int main() {
using namespace numapp;
using namespace std::chrono_literals;
if (!NumaAvailable()) {
std::cout << "NUMA not available";
return -1;
}
NumaPolicies policies;
policies.SetCpuAffinity(CpuAffinity::MakeFromCpuStringAll("0-3"));
auto thread = MakeThread("myThread", policies, &ThreadFunc, 500ms);
thread.join();
}
numapp::CpuAffinity::MakeFromCpuStringAll
static CpuAffinity MakeFromCpuStringAll(char const *cpustring)
Create CpuAffinity from `cpustring` without considering current cpuset.
Definition cpuaffinity.cpp:47
numapp::CpuAffinity::MakeFromActive
static CpuAffinity MakeFromActive()
Create current affinity settings.
Definition cpuaffinity.cpp:35
numapp::NumaPolicies
Combines the the available NUMA policy types in one object.
Definition numapolicies.hpp:49
numapp::NumaPolicies::SetCpuAffinity
void SetCpuAffinity(std::optional< CpuAffinity > affinity) noexcept
Set CPU affinity.
Definition numapolicies.hpp:114
numapp::NumaAvailable
bool NumaAvailable() noexcept
Query whether system has NUMA support.
Definition numa.hpp:34
numapp::MakeThread
std::thread MakeThread(std::string_view thread_name, NumaPolicies const &policies, Func &&func, Args &&... args)
Primary overload accepting string-view for thread_name.
Definition thread.hpp:144
thread.hpp
Contains declarations for numapp thread utilities.

Example function that create pinned thread with local NUMA node memory policy:

#include <numapp/memory.hpp>
#include <numapp/thread.hpp>
template <class F, class... Args>
auto MakePinnedThread(int cpu, std::string_view name, F&& f, Args... args) -> std::thread {
using namespace numapp;
NumaPolicies policies;
policies.SetCpuAffinity(CpuAffinity::MakeBindCpu(cpu));
auto node = GetNodeOfCpu(cpu);
if (!node.has_value()) {
throw std::invalid_argument("cpu invalid");
}
policies.SetMemPolicy(MemPolicy::MakeBindNode(*node));
return MakeThread(name, policies, std::forward<F>(f), std::forward<Args>(args)...);
}
numapp::CpuAffinity::MakeBindCpu
static CpuAffinity MakeBindCpu(int cpu)
Create CpuAffinity bound to the specified CPU.
Definition cpuaffinity.cpp:59
numapp::MemPolicy::MakeBindNode
static MemPolicy MakeBindNode(int node)
Creates a strict policy (using MPOL_BIND) to allocate all memory to the specified node.
numapp::NumaPolicies::SetMemPolicy
void SetMemPolicy(std::optional< MemPolicy > policy) noexcept
Set memory policy.
Definition numapolicies.hpp:138
numapp::GetNodeOfCpu
std::optional< int > GetNodeOfCpu(int cpu) noexcept
Get NUMA node of the given CPU.
Definition memory.cpp:53
memory.hpp
Contains memory function declarations.

Similar to first example, but uses member function instead:

#include <chrono>
#include <iostream>
#include <numapp/numa.hpp>
#include <numapp/thread.hpp>
struct Example {
Example(std::chrono::milliseconds duration) : m_duration(duration) {
}
Example(Example&&) = default;
void ThreadFunc() {
std::cout << "Thread affinity: "
<< numapp::CpuAffinity::MakeFromActive() << std::endl;
std::this_thread::sleep_for(m_duration);
}
std::chrono::milliseconds m_duration;
};
int main() {
using namespace numapp;
using namespace std::chrono_literals;
if (!NumaAvailable()) {
std::cout << "NUMA not available";
return -1;
}
NumaPolicies policies;
policies.SetCpuAffinity(CpuAffinity::MakeFromCpuStringAll("0-3"));
auto thread =
MakeJthread("myThread", policies, &Example::ThreadFunc, Example{500ms});
}
template<class Func, class... Args>
std::thread numapp::MakeThread (std::string_view thread_name, NumaPolicies const &policies, Func &&func, Args &&... args)
 Primary overload accepting string-view for thread_name.
 
template<class Func, class... Args>
std::thread numapp::MakeThread (char const *thread_name, NumaPolicies const &policies, Func &&func, Args &&... args)
 Compatibility overload accepting null terminated C string for thread_name.
 

Detailed Description

Contains declarations for numapp thread utilities.

Copyright
ESO 2024 - European Southern Observatory

Definition in file thread.hpp.