scheduler.hpp

Go to the documentation of this file.

/**
 * @file
 * @ingroup numapp_sched
 * @brief Contains scheduler declarations
 * @copyright
 *   SPDX-FileCopyrightText: 2020-2025 European Southern Observatory (ESO)
 *
 *   SPDX-License-Identifier: LGPL-3.0-only
 *
 * @defgroup numapp_sched Scheduler APIs
 * @ingroup numapp
 * @brief NUMA++ scheduler APIs
 *
 *
 * See @ref scheduler-api for an overview.
 */
#ifndef NUMAPP_SCHEDULER_HPP_
#define NUMAPP_SCHEDULER_HPP_
#include <iosfwd>
#include <system_error>
#include <variant>
 
#include <sched.h>
 
namespace numapp {
class IdleScheduler;
class DynamicScheduler;
class StaticScheduler;
class Scheduler;
 
/**
 * @name Apply Scheduler to Specified Thread
 *
 * Applies scheduler to specified thread.
 */
/// @{
 
/**
 * Apply idle scheduler to specified thread.
 *
 * @param thread thread id.
 * @param scheduler parameters.
 * @returns 0 on success.
 * @returns on-zero on failure.
 *
 * @relatesalso ::numapp::IdleScheduler
 * @ingroup numapp_sched
 * @headerfile <> <numapp/scheduler.hpp>
 */
[[nodiscard]] std::error_code Apply(pid_t thread, IdleScheduler const& scheduler) noexcept;
 
/**
 * Apply dynamic scheduler to specified thread.
 *
 * @param thread thread id.
 * @param scheduler scheduler parameters.
 * @returns 0 on success.
 * @returns on-zero on failure.
 *
 * @relatesalso DynamicScheduler
 * @ingroup numapp_sched
 * @headerfile <> <numapp/scheduler.hpp>
 */
[[nodiscard]] std::error_code Apply(pid_t thread, DynamicScheduler const& scheduler) noexcept;
 
/**
 * Apply static scheduler to specified thread.
 *
 * @param thread thread id.
 * @param scheduler scheduler parameters.
 * @returns 0 on success.
 * @returns on-zero on failure.
 *
 * @relatesalso StaticScheduler
 * @ingroup numapp_sched
 * @headerfile <> <numapp/scheduler.hpp>
 */
[[nodiscard]] std::error_code Apply(pid_t thread, StaticScheduler const& scheduler) noexcept;
 
/**
 * Apply variadic scheduler to specified thread.
 *
 * @param thread thread id.
 * @param scheduler parameters.
 * @returns 0 on success.
 * @returns on-zero on failure.
 *
 * @relatesalso Scheduler
 * @ingroup numapp_sched
 * @headerfile <> <numapp/scheduler.hpp>
 */
[[nodiscard]] std::error_code Apply(pid_t thread, Scheduler const& scheduler) noexcept;
/// @}
 
namespace thisThread {
 
/**
 * @name Apply Scheduler to Current Thread
 *
 * Applies specified scheduler to current thread.
 * @ingroup numapp_sched
 */
/// @{
/**
 * Apply idle scheduler to @a this thread.
 *
 * @param scheduler parameters.
 * @returns 0 on success.
 * @returns on-zero on failure.
 *
 * @relatesalso numapp::IdleScheduler
 * @ingroup numapp_sched
 * @headerfile <> <numapp/scheduler.hpp>
 */
[[nodiscard]] std::error_code Apply(IdleScheduler const& scheduler) noexcept;
 
/**
 * Apply dynamic scheduler to @a this thread.
 *
 * @param scheduler parameters.
 * @returns 0 on success.
 * @returns on-zero on failure.
 *
 * @relatesalso ::numapp::DynamicScheduler
 * @ingroup numapp_sched
 * @headerfile <> <numapp/scheduler.hpp>
 */
[[nodiscard]] std::error_code Apply(DynamicScheduler const& scheduler) noexcept;
 
/**
 * Apply static scheduler to @a this thread.
 *
 * @param scheduler parameters.
 * @returns 0 on success.
 * @returns on-zero on failure.
 *
 * @relatesalso ::numapp::StaticScheduler
 * @ingroup numapp_sched
 * @headerfile <> <numapp/scheduler.hpp>
 */
[[nodiscard]] std::error_code Apply(StaticScheduler const& scheduler) noexcept;
 
/**
 * Apply variadic scheduler to @a this thread.
 *
 * @param scheduler parameters.
 * @returns 0 on success.
 * @returns on-zero on failure.
 *
 * @relatesalso ::numapp::Scheduler
 * @ingroup numapp_sched
 * @headerfile <> <numapp/scheduler.hpp>
 */
[[nodiscard]] std::error_code Apply(Scheduler const& scheduler) noexcept;
/// @}
}
 
/**
 * Represents @c SCHED_IDLE scheduler policy.
 *
 * It does not use either dynamic or static priority and is only scheduled to execute if no
 * other task is ready to run.
 
 * @manpages
 * @manpage{sched,7}
 * @ingroup numapp_sched
 * @headerfile <> <numapp/scheduler.hpp>
 */
class IdleScheduler {
public:
    IdleScheduler() noexcept = default;
    explicit constexpr IdleScheduler(IdleScheduler&&) noexcept = default;
    explicit constexpr IdleScheduler(IdleScheduler const&) noexcept = default;
    constexpr IdleScheduler& operator=(IdleScheduler&&) noexcept = default;
    constexpr IdleScheduler& operator=(IdleScheduler const&) noexcept = default;
 
    [[nodiscard]] constexpr bool operator==(IdleScheduler const& rhs) const {
        return true;
    }
    [[nodiscard]] bool operator!=(IdleScheduler const& rhs) const {
        return false;
    }
 
    /**
     * Apply policy to calling thread
     */
    [[nodiscard]] std::error_code Apply() const noexcept;
};
 
/**
 * Formats @a scheduler and inserts it to @a os.
 *
 * @param os output stream to insert into.
 * @param scheduler IdleScheduler to format.
 * @returns @a os
 *
 * @relates IdleScheduler
 */
std::ostream& operator<<(std::ostream& os, IdleScheduler const& scheduler);
 
/**
 * Static priority scheduler (real-time).
 *
 * Get and set scheduler for the calling thread.
 *
 * The implementation use the pthread API to query and apply policy.
 *
 * @par Permissions
 *
 * Real-time priority scheduler may require additional permissions provided by `CAP_SYS_NICE` unless
 * allowed by resource limits (`RLIMIT_RTPRIO`). See also @ref permissions.
 *
 * @manpages
 * @manpage{sched,7}
 * @ingroup numapp_sched
 * @headerfile <> <numapp/scheduler.hpp>
 */
class StaticScheduler {
public:
    /**
     * Scheduler policy.
     */
    enum class Policy : int {
        /**
         * A first-in, first-out "real-time" policy.
         */
        Fifo = SCHED_FIFO,
        /**
         * A roound-robin, "real-time" policy.
         */
        Rr = SCHED_RR
    };
 
    /**
     * Create with provided policy and priority.
     *
     * @param policy Scheduler policy.
     * @param priority Static priority with a valid range of 1 (low) to 99 (high).
     *
     * @throw std::system_error containing std::errc::invalid_argument if any argument is invalid.
     */
    explicit StaticScheduler(Policy policy, int priority);
 
    constexpr StaticScheduler(StaticScheduler&&) noexcept = default;
    constexpr StaticScheduler(StaticScheduler const&) noexcept = default;
    StaticScheduler& operator=(StaticScheduler&&) noexcept = default;
    StaticScheduler& operator=(StaticScheduler const&) noexcept = default;
 
    [[nodiscard]] bool operator==(StaticScheduler const& rhs) const noexcept {
        return m_policy == rhs.m_policy && m_prio == rhs.m_prio;
    }
    [[nodiscard]] bool operator!=(StaticScheduler const& rhs) const noexcept {
        return !(*this == rhs);
    }
 
    /**
     * Set static priority 0 - 99.
     * @param priority The priority to use. Valid range is 0 - 99.
     *
     * @return std::errc::invalid_argument if @c priority is invalid.
     */
    std::error_code SetPriority(int priority);
 
    /**
     * Set policy.
     *
     * @return std::errc::invalid_argument if policy is invalid.
     */
    std::error_code SetPolicy(Policy policy) noexcept;
 
    /**
     * Get static priority.
     */
    constexpr int GetPriority() const noexcept {
        return m_prio;
    }
 
    /**
     * @returns policy.
     */
    constexpr Policy GetPolicy() const noexcept {
        return m_policy;
    }
 
private:
    Policy m_policy;
    int m_prio;
};
 
/**
 * Formats @a scheduler and inserts it to @a os.
 *
 * @param os output stream to insert into.
 * @param scheduler StaticScheduler to format.
 * @returns @a os
 *
 * @relates StaticScheduler
 */
std::ostream& operator<<(std::ostream& os, StaticScheduler const& scheduler);
 
/**
 * Formats @a policy and inserts it to @a os.
 *
 * @param os output stream to insert into.
 * @param policy Policy to format.
 * @returns @a os
 *
 * @ingroup StaticScheduler
 * @headerfile <> <numapp/scheduler.hpp>
 */
std::ostream& operator<<(std::ostream& os, StaticScheduler::Policy const& policy);
 
/**
 * Normal non-realtime scheduler that use dynamic priority (nice value).
 *
 * @note The "nice" value is a type of inverse dynamic scheduling priority where lower values (less
 * nice) have higher priority.
 *
 * To apply a lower value requires CAP_SYS_NICE privilege.
 *
 * @manpages
 * @manpage{sched,7}
 * @manpage{setpriority,2}
 *
 * @ingroup numapp_sched
 * @headerfile <> <numapp/scheduler.hpp>
 */
class DynamicScheduler {
public:
    /**
     * Sheduler policy.
     */
    enum class Policy : int {
        /**
         * The standard round-robin time-sharing policy.
         *
         * This is referred to as @c SCHED_NORMAL in the kernel.
         */
        Other = SCHED_OTHER,
        /**
         * For "batch" style execution of processes.
         */
        Batch = SCHED_BATCH,
    };
 
    /**
     * @param policy Scheduling policy.
     * @param nice Niceness value with range [-20 - 19], where -20 is the highest priority and 19
     * lowest priority.
     *
     * @throws std::system_error with std::errc::invalid_argument on error.
     */
    explicit DynamicScheduler(Policy policy = Policy::Other, int nice = 0);
    constexpr DynamicScheduler(DynamicScheduler const&) noexcept = default;
    DynamicScheduler& operator=(DynamicScheduler const&) noexcept = default;
 
    [[nodiscard]] bool operator==(DynamicScheduler rhs) const {
        return m_policy == rhs.m_policy && m_priority == rhs.m_priority;
    }
 
    [[nodiscard]] bool operator!=(DynamicScheduler rhs) const {
        return !(*this == rhs);
    }
 
    /**
     * Set dynamic nice value (dynamic priority) of thread.
     *
     * Higher value means "more" nice and correspondingly lower scheduling priority.
     *
     * @param value the dynamic priority. Valid range is [-20 - 19].
     *
     * @return std::errc::invalid_argument if value is out of range.
     */
    std::error_code SetNice(int value) noexcept;
 
    /**
     * Set policy.
     *
     * @return std::errc::invalid_argument if policy is invalid.
     */
    std::error_code SetPolicy(Policy policy) noexcept;
 
    /**
     * Get dynamic nice value.
     */
    int GetNice() const noexcept;
 
    /**
     * @returns policy.
     */
    constexpr Policy GetPolicy() const noexcept {
        return m_policy;
    }
 
private:
    Policy m_policy;
    int m_priority;
};
 
/**
 * Formats @a scheduler and inserts it to @a os.
 *
 * @param os output stream to insert into.
 * @param scheduler DynamicScheduler to format.
 * @returns @a os
 *
 * @relates DynamicScheduler
 */
std::ostream& operator<<(std::ostream& os, DynamicScheduler const& scheduler);
 
/**
 * Formats @a policy and inserts it to @a os.
 *
 * @param os output stream to insert into.
 * @param policy Policy to format.
 * @returns @a os
 *
 * @relates DynamicScheduler
 */
std::ostream& operator<<(std::ostream& os, DynamicScheduler const& policy);
 
/**
 * Variant of possible schedulers.
 *
 * @ingroup numapp_sched
 * @headerfile <> <numapp/scheduler.hpp>
 */
using SchedulerVariant = std::variant<DynamicScheduler, StaticScheduler, IdleScheduler>;
 
/**
 * Formats @a scheduler and inserts it to @a os.
 *
 * @param os output stream to insert into.
 * @param scheduler Scheduler to format.
 * @returns @a os
 *
 * @ingroup numapp_sched
 * @headerfile <> <numapp/scheduler.hpp>
 */
std::ostream& operator<<(std::ostream& os, SchedulerVariant const& scheduler);
 
/**
 * A sum-type of all supported schedulers.
 *
 * @manpages
 * @manpage{sched,7}
 *
 * @ingroup numapp_sched
 * @headerfile <> <numapp/scheduler.hpp>
 */
class Scheduler {
public:
    explicit Scheduler(SchedulerVariant const& sched);
    Scheduler(IdleScheduler sched) noexcept;
    Scheduler(StaticScheduler sched) noexcept;
    Scheduler(DynamicScheduler sched) noexcept;
 
    explicit Scheduler(SchedulerVariant&& sched) noexcept;
    Scheduler(Scheduler&&) noexcept = default;
    Scheduler(Scheduler const&) = default;
 
    Scheduler& operator=(Scheduler&& rhs) noexcept = default;
    Scheduler& operator=(Scheduler const&) noexcept = default;
 
    [[nodiscard]] bool operator==(Scheduler const& rhs) const noexcept {
        return m_scheduler == rhs.m_scheduler;
    }
    [[nodiscard]] bool operator!=(Scheduler const& rhs) const noexcept {
        return !(*this == rhs);
    }
 
    /**
     * Query the held scheduler.
     *
     *     if (scheduler.HoldsScheduler<IdleScheduler>()) {
     *         // ...
     *     }
     */
    template <class T>
    [[nodiscard]] constexpr bool HoldsScheduler() const noexcept {
        return std::holds_alternative<T>(m_scheduler);
    }
 
    /**
     * Get the held scheduler.
     *
     *     idle_scheduler = scheduler.GetScheduler<IdleScheduler>(); // may throw
     *
     * @throw std::bad_variant_access if @c T does not match held scheduler.
     */
    template <class T>
    [[nodiscard]] constexpr T GetScheduler() const {
        return std::get<T>(m_scheduler);
    }
 
    /**
     * Return active scheduler policy for this thread.
     *
     * @throws std::system_error with std::errc::not_supported error if unknown policy is found..
     */
    [[nodiscard]] static Scheduler MakeFromActive();
 
    /**
     * Return active scheduler policy for thread with @a pid.
     *
     * @throws std::system_error with std::errc::not_supported error if unknown policy is found..
     */
    [[nodiscard]] static Scheduler MakeFromActive(pid_t pid);
 
    /**
     * Get the underlying scheduler.
     */
    SchedulerVariant const& Get() const noexcept {
        return m_scheduler;
    }
 
    /**
     * Enable implicit conversion to underlying SchedulerVariant.
     */
    operator SchedulerVariant() const noexcept;
 
private:
    SchedulerVariant m_scheduler;
};
 
/**
 * Formats @a scheduler and inserts it to @a os.
 *
 * @param os output stream to insert into.
 * @param scheduler Scheduler to format.
 * @returns @a os
 *
 * @relates Scheduler
 */
std::ostream& operator<<(std::ostream& os, Scheduler const& scheduler);
 
}  // namespace numapp
#endif  //#ifndef NUMAPP_SCHEDULER_HPP_