NUMA++ 0.11.0
Loading...
Searching...
No Matches
Files | Functions
Thread APIs
NUMA++

NUMA++ thread APIs. More...

Files

file  thread.cpp
 Definition of thread functions.
 

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

NUMA++ thread APIs.

Function Documentation

◆ GetThreadId()

pid_t numapp::thisThread::GetThreadId ( )
nodiscardnoexcept

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 gettid() is not provided by glibc.

Returns
callers thread ID.
Related man-page(s):

Definition at line 27 of file thread.cpp.

◆ GetThreadName() [1/2]

std::string numapp::thisThread::GetThreadName ( )
nodiscard

Get name of current thread (throwing version).

Returns
string containing current thread name.
empty string if error occurs (error is reported in ec).
Exceptions
std::bad_allocif allocation fails.
See also
SetThreadName()

Definition at line 75 of file thread.cpp.

◆ GetThreadName() [2/2]

std::string numapp::thisThread::GetThreadName ( std::error_code & ec)
nodiscardnoexcept

Get name of current thread.

Parameters
[out]ecout-parameter for error reporting.
Returns
string containing current thread name.
empty string if error occurs (error is reported in ec).
Exceptions
std::bad_allocif allocation fails.
See also
SetThreadName()

Definition at line 57 of file thread.cpp.

◆ MakeThread() [1/2]

template<class Func, class... Args>
std::thread numapp::MakeThread ( char const * thread_name,
NumaPolicies const & policies,
Func && func,
Args &&... args )
nodiscard

Compatibility overload accepting null terminated C string for thread_name.

See MakeThread group for detailed documentation.

Definition at line 187 of file thread.hpp.

◆ MakeThread() [2/2]

template<class Func, class... Args>
std::thread numapp::MakeThread ( std::string_view thread_name,
NumaPolicies const & policies,
Func && func,
Args &&... args )
nodiscard

Primary overload accepting string-view for thread_name.

See MakeThread group for detailed documentation.

Definition at line 144 of file thread.hpp.

◆ SetThreadName() [1/2]

void numapp::thisThread::SetThreadName ( std::string_view thread_name)

Set thread name for current thread (throwing version).

Parameters
thread_nameName of thread. Maximum length (thread_name.length()) is 15.
Exceptions
std::system_erroron errors.
See also
GetThreadName()

Definition at line 49 of file thread.cpp.

◆ SetThreadName() [2/2]

void numapp::thisThread::SetThreadName ( std::string_view thread_name,
std::error_code & ec )
noexcept

Set thread name for current thread.

Parameters
thread_nameName of thread. Maximum length (thread_name.length()) is 15.
[out]ecout-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.
See also
GetThreadName()

Definition at line 32 of file thread.cpp.