cpuaffinity.hpp

Go to the documentation of this file.

/**
 * @file
 * @ingroup numapp_affinity
 * @copyright ESO 2024 - European Southern Observatory
 *
 * @brief Contains declarations for CpuAffinity
 *
 * @defgroup numapp_affinity CPU Affinity APIs
 * @ingroup numapp
 * @brief NUMA++ CPU affinity APIs
 *
 * Use header file <tt>\#include <numapp/cpuaffinity.hpp></tt>
 *
 * See @ref affinity-api for an overview.
 *
 */
#ifndef NUMAPP_CPUAFFINITY_HPP_
#define NUMAPP_CPUAFFINITY_HPP_
 
#include <bitset>
#include <cstring>
#include <iosfwd>
#include <optional>
#include <system_error>
 
#include "cpumask.hpp"
 
namespace numapp {
 
class CpuAffinity;
 
namespace thisThread {
 
/**
 * @name Apply CPU Affinity to Current Thread
 *
 * Applies specified policy to calling thread.
 */
/// @{
/**
 * Apply policy to calling thread.
 *
 * @param affinity The CPU affinity to apply.
 *
 * @relatesalso ::numapp::CpuAffinity
 * @ingroup numapp_affinity
 * @headerfile <> <numapp/cpuaffinity.hpp>
 */
[[nodiscard]] std::error_code Apply(CpuAffinity const& affinity) noexcept;
/// @}
 
}  // namespace thisThread
 
/**
 * @name Apply CPU Affinity to Specific Thread
 *
 * Applies specified policy to calling thread.
 */
/// @{
 
/**
 * Apply policy to specified thread.
 *
 * @param thread Thread id.
 * @param affinity The CPU affinity to apply.
 *
 * @relatesalso CpuAffinity
 * @ingroup numapp_affinity
 * @headerfile <> <numapp/cpuaffinity.hpp>
 */
[[nodiscard]] std::error_code Apply(pid_t thread, CpuAffinity const& affinity) noexcept;
/// @}
 
/**
 * Create CPU affinity and apply to current thread
 *
 * For memory policy see numapp::MemPolicy.
 *
 * @manpages
 * @manpage{numa_sched_setaffinity,3}
 *
 * @sa numapp::MemPolicy
 *
 * @ingroup numapp_affinity
 * @headerfile <> <numapp/cpuaffinity.hpp>
 */
class CpuAffinity {
public:
    /**
     * Create affinity from Cpumask.
     *
     * @param mask The CPU-mask to use.
     */
    explicit CpuAffinity(Cpumask&& mask) noexcept;
    explicit CpuAffinity(Cpumask const& mask) noexcept;
    CpuAffinity(CpuAffinity&&) noexcept = default;
    CpuAffinity& operator=(CpuAffinity&&) noexcept = default;
    CpuAffinity(CpuAffinity const& rhs) = default;
    CpuAffinity& operator=(CpuAffinity const& rhs) = default;
 
    [[nodiscard]] bool operator==(CpuAffinity const& rhs) const noexcept {
        return m_mask == rhs.m_mask;
    }
    [[nodiscard]] bool operator!=(CpuAffinity const& rhs) const noexcept {
        return !(*this == rhs);
    }
 
    /**
     * Create current affinity settings.
     *
     * @throws std::system_error on failure.
     */
    [[nodiscard]] static CpuAffinity MakeFromActive();
 
    /**
     * Create CpuAffinity from @a @c `cpustring` while considering allowed CPUs from current cpuset.
     *
     * Example patterns:
     * - <tt>1-5,7,10</tt>
     * - <tt>!4-5</tt>
     * - <tt>+0-3</tt>
     * - <tt>all</tt>
     *
     * c.f. numa_parse_cpustring for how the format is specified.
     *
     * @note numa_parse_cpustring
     *
     *
     * @param cpustring CPUs to include such as <tt>1-5,7,10</tt> or <tt>all</tt>.
     * @throws std::system_error on failure. Method will fail if cpustring references a CPU outside
     * current cpuset. Use @ref MakeFromCpuStringAll when current cpuset should not be considered.
     *
     * @sa MakeFromCpuStringAll
     */
    [[nodiscard]] static CpuAffinity MakeFromCpuString(char const* cpustring);
 
    /**
     * Create CpuAffinity from @a @c `cpustring` @a without considering current cpuset.
     *
     * Example patterns:
     * - <tt>1-5,7,10</tt>
     * - <tt>!4-5</tt>
     * - <tt>+0-3</tt>
     * - <tt>all</tt>
     *
     * c.f. numa_parse_cpustring for how the format is specified.
     *
     * @note The @a cpustring is parsed using numa_parse_cpustring_all which does not consider
     * current cpuset. This method must be used when referencing CPUs isolated with isolcpus.
     *
     * @param cpustring CPUs to include such as <tt>1-5,7,10</tt> or <tt>all</tt>.
     * @throws std::system_error on failure.
     *
     * @sa MakeFromCpuString
     */
    static CpuAffinity MakeFromCpuStringAll(char const* cpustring);
 
    /**
     * Create CpuAffinity bound to the specified NUMA node.
     *
     * @throws std::system_error on failure.
     */
    [[nodiscard]] static CpuAffinity MakeBindNode(int node);
 
    /**
     * Create CpuAffinity bound to the specified CPU.
     *
     * @throws std::system_error on failure.
     */
    [[nodiscard]] static CpuAffinity MakeBindCpu(int cpu);
 
    /**
     * @return Underlying CPU mask.
     */
    Cpumask const& GetMask() const noexcept;
 
private:
    explicit CpuAffinity(struct bitmask* cpumask) {
    }
    Cpumask m_mask;
};
 
/**
 * Formats @a affinity and inserts it to @a os.
 *
 * @param os output stream to insert into.
 * @param affinity CPU affinity to format.
 * @returns @a os
 *
 * @relates CpuAffinity
 * @headerfile <> <numapp/cpuaffinity.hpp>
 */
std::ostream& operator<<(std::ostream& os, CpuAffinity const& affinity);
 
}  // namespace numapp
#endif  // #ifndef NUMAPP_CPUAFFINITY_HPP_