bitmask.hpp

Go to the documentation of this file.

/**
 * @file
 * @ingroup numapp_numa
 * @brief Contains declarations for numapp::Bitmask
 * @copyright
 *   SPDX-FileCopyrightText: 2020-2024 European Southern Observatory (ESO)
 *
 *   SPDX-License-Identifier: LGPL-3.0-only
 */
#ifndef NUMAPP_BITMASK_HPP_
#define NUMAPP_BITMASK_HPP_
#include <iosfwd>
#include <memory>
#include <type_traits>
 
#include <numa.h>
 
namespace numapp {
 
/**
 * Lowlevel bitmask type.
 *
 * @ingroup numapp_numa
 */
using NumaBitmaskPtr = std::unique_ptr<struct bitmask, void (*)(struct bitmask*)>;
 
template <class Class>
class Bitmask;
 
/**
 * Invoke function for each bit in mask that matches @a value.
 *
 * @param bitmask Bitmask to iterate over.
 * @param f function callable as `f(position)` where @a position is the `unsigned int` bit position.
 * @param value to test bit for (true == bit is set, false == bit is unset).
 *
 * Example that starts a pinned thread for each bit in a CPU mask:
 *
 * @include forEachExample.cpp
 *
 * @par Header file
 * @c <numapp/bitmask.hpp>
 *
 * @relatesalso Bitmask
 * @sa Cpumask Nodemask
 * @ingroup numapp_numa
 */
template <class Class, class F>
void ForEach(Bitmask<Class> const& bitmask, F&& f, bool value = true);
 
/**
 * Generic bitmask
 *
 * @ingroup numapp_numa
 */
template <class Class>
class Bitmask {
public:
    Bitmask() : m_bitmask(Class::Alloc()) {
    }
 
    Bitmask(Bitmask&& rhs) noexcept = default;
    Bitmask(Bitmask const& rhs) : m_bitmask(Class::Alloc()) {
        *this = rhs;
    }
    Bitmask& operator=(Bitmask&&) noexcept = default;
    /**
     * Copy from @a rhs to this.
     *
     * @param rhs bitmask to copy from.
     * @returns reference to this.
     */
    Bitmask& operator=(Bitmask const& rhs) noexcept {
        // Copy from rhs to this
        copy_bitmask_to_bitmask(rhs.m_bitmask.get(), m_bitmask.get());
        return *this;
    }
 
    /**
     * @name Comparison
     */
    /// @{
    /**
     * @returns true if bitmask are equal.
     */
    [[nodiscard]] bool operator==(Bitmask const& rhs) const noexcept {
        return numa_bitmask_equal(m_bitmask.get(), rhs.m_bitmask.get()) == 1;
    }
    /**
     * @returns true if bitmask are equal.
     */
    [[nodiscard]] bool operator!=(Bitmask const& rhs) const noexcept {
        return !(this == rhs);
    }
    /// @}
 
    /**
     * @name Accessors
     */
    /// @{
    /**
     * Access native bitmask type.
     *
     * @return pointer to libnuma bitmask type.
     */
    struct bitmask const* GetNative() const noexcept {
        return m_bitmask.get();
    }
    /**
     * Access native bitmask type.
     *
     * @return pointer to libnuma bitmask type.
     */
    struct bitmask* GetNative() noexcept {
        return m_bitmask.get();
    }
 
    /**
     * Query number of bits in mask.
     *
     * @return number of bits in mask.
     */
    [[nodiscard]] std::size_t GetSize() const noexcept {
        return m_bitmask->size;
    }
 
    /**
     * Test if bit in specified position is set.
     *
     * @param position Zero-indexed bit position to test.
     * @return value of bit in requested @a position or false if @a position is outside valid range.
     */
    [[nodiscard]] bool Test(unsigned int position) const noexcept {
        return numa_bitmask_isbitset(GetNative(), position);
    }
 
    /// @}
    /**
     * @name Modifiers
     *
     * If specified bit position is outside valid range no operations is performed. This behaviour
     * is inherited from libnuma.
     */
    /// @{
    /**
     * Set bit in @a position to specified value.
     *
     * @note If position is outside valid range nothing is done.
     *
     * @param position Zero-indexed bit position to modify.
     * @param value Bit value to set (default true).
     * @return Reference to this object (for call chaining).
     */
    Bitmask& Set(unsigned int position, bool value = true) noexcept {
        if (value) {
            numa_bitmask_setbit(GetNative(), position);
        } else {
            numa_bitmask_clearbit(GetNative(), position);
        }
        return *this;
    }
 
    /**
     * Sets bit in specified position to false.
     *
     * @note If position is outside valid range nothing is done.
     *
     * @param position Zero-indexed bit position to modify.
     * @return Reference to this object (for call chaining).
     */
    Bitmask& Reset(unsigned int position) noexcept {
        numa_bitmask_clearbit(GetNative(), position);
        return *this;
    }
    /// @}
protected:
    /**
     * Construction from native bitmask type can be error prone in that
     * the mask wasn't allocated using the correction function. To prevent mistakes this is made
     * protected so it can only be used by the concrete implementations.
     */
    Bitmask(NumaBitmaskPtr&& bitmask) : m_bitmask(std::move(bitmask)) {
    }
 
private:
    NumaBitmaskPtr m_bitmask;
};
 
/**
 * Formats @a mask and inserts it to @a os.
 *
 * @param os output stream to insert into.
 * @param mask Bitmask to format.
 * @param min_bits Minimum number of bits to format.
 * @returns @a os
 *
 * @relatesalso Bitmask
 * @ingroup numapp_numa
 */
template <class Class>
std::ostream& FormatBitmask(std::ostream& os, Bitmask<Class> const& mask, int min_bits);
 
/**
 * Formats @a mask and inserts it to @a os.
 *
 * @param os output stream to insert into.
 * @param mask Bitmask to format.
 * @param min_bits Minimum number of bits to format.
 * @returns @a os
 *
 * @relatesalso Bitmask
 * @ingroup numapp_numa
 */
std::ostream& FormatBitmask(std::ostream& os, bitmask const* mask, int min_bits);
 
template <class Class>
std::ostream& FormatBitmask(std::ostream& os, Bitmask<Class> const& mask, int min_bits) {
    return FormatBitmask(os, mask.GetNative(), min_bits);
}
 
template <class Class, class F>
void ForEach(Bitmask<Class> const& bits, F&& f, bool value) {
    static_assert(std::is_invocable_v<F, unsigned int>,
                  "Function must be invocable with signature `f(unsigned int)`");
    auto const num_bits = bits.GetSize();
    for (unsigned int position = 0u; position < num_bits; ++position) {
        if (bits.Test(position) == value) {
            f(position);
        }
    }
}
 
}  // namespace numapp
 
#endif  // #ifndef NUMAPP_BITMASK_HPP_