host_admission.h

Go to the documentation of this file.

 
#pragma once
 
#include <neograph/api.h>
#include <neograph/graph/cancel.h>
 
#include <asio/awaitable.hpp>
 
#include <chrono>
#include <cstdint>
#include <memory>
#include <optional>
#include <stdexcept>
#include <string>
#include <string_view>
#include <vector>
 
namespace neograph {
 
struct NEOGRAPH_API HostResourceVector {
    std::uint64_t cpu_millis          = 0;
    std::uint64_t memory_bytes        = 0;
    std::uint64_t gpu_slots           = 0;
    std::uint64_t gpu_memory_bytes    = 0;
    std::uint64_t processes           = 0;
    std::uint64_t threads             = 0;
    std::uint64_t file_descriptors    = 0;
    std::uint64_t disk_bytes          = 0;
    std::uint64_t network_connections = 0;
    std::uint64_t tool_slots          = 0;
    std::uint64_t provider_requests   = 0;
    std::uint64_t model_tokens        = 0;
    std::uint64_t monetary_microunits = 0;
    std::uint64_t wall_time_ms        = 0;
 
    bool operator==(const HostResourceVector&) const = default;
 
    [[nodiscard]] bool empty() const noexcept;
    [[nodiscard]] bool fits_within(const HostResourceVector& limit) const noexcept;
    [[nodiscard]] static HostResourceVector componentwise_min(const HostResourceVector& lhs,
                                                               const HostResourceVector& rhs) noexcept;
    [[nodiscard]] static HostResourceVector saturating_add(const HostResourceVector& lhs,
                                                            const HostResourceVector& rhs) noexcept;
    [[nodiscard]] static HostResourceVector subtract_clamped(const HostResourceVector& lhs,
                                                              const HostResourceVector& rhs) noexcept;
};
 
enum class HostResourceConfidence : std::uint8_t {
    Measured,
    Estimated,
    ConservativeFallback,
};
 
NEOGRAPH_API std::string_view to_string(HostResourceConfidence confidence) noexcept;
 
struct NEOGRAPH_API HostResourceEvidence {
    std::string                 source;
    HostResourceConfidence      confidence = HostResourceConfidence::ConservativeFallback;
    std::int64_t                observed_at_ms = 0;
    bool                        cgroup_limited = false;
 
    bool operator==(const HostResourceEvidence&) const = default;
};
 
struct NEOGRAPH_API HostResourceProfileData {
    std::string                 profile_id;
    HostResourceVector          capacity;
    HostResourceVector          safety_reserve;
    HostResourceEvidence        evidence;
};
 
class NEOGRAPH_API HostResourceProfile {
public:
    static constexpr std::uint32_t SCHEMA_VERSION = 1;
 
    static HostResourceProfile create(HostResourceProfileData data);
    static HostResourceProfile detect_current();
    static HostResourceProfile intersect(const std::vector<HostResourceProfile>& profiles,
                                         std::string profile_id);
    HostResourceProfile scaled_available(std::uint8_t percent,
                                         std::string profile_id) const;
    const std::string&          profile_id() const noexcept;
    const HostResourceVector&   capacity() const noexcept;
    const HostResourceVector&   safety_reserve() const noexcept;
    HostResourceVector          available_capacity() const noexcept;
    const HostResourceEvidence& evidence() const noexcept;
    std::string                 serialize_canonical() const;
 
private:
    explicit HostResourceProfile(HostResourceProfileData data);
    HostResourceProfileData data_;
};
 
enum class HostPressureLevel : std::uint8_t {
    Normal,
    Elevated,
    Critical,
};
NEOGRAPH_API std::string_view to_string(HostPressureLevel level) noexcept;
 
struct NEOGRAPH_API HostPressureSample {
    HostPressureLevel          level = HostPressureLevel::Normal;
    std::int64_t               observed_at_ms = 0;
    std::string                source;
};
 
enum class HostAdmissionFailure : std::uint8_t {
    InvalidRequest,
    CapacityExceeded,
    QueueFull,
    QueueTimeout,
    Shutdown,
};
 
NEOGRAPH_API std::string_view to_string(HostAdmissionFailure failure) noexcept;
 
class NEOGRAPH_API HostAdmissionError final : public std::runtime_error {
public:
    HostAdmissionError(HostAdmissionFailure failure, std::string detail);
    [[nodiscard]] HostAdmissionFailure failure() const noexcept;
 
private:
    HostAdmissionFailure failure_;
};
 
struct NEOGRAPH_API HostAdmissionRequest {
    std::string                 owner_scope;
    std::string                 operation_id;
    HostResourceVector          resources;
    std::uint8_t                priority = 0;
    std::uint32_t               max_pending = 0;
    std::chrono::milliseconds   queue_timeout{0};
    std::uint8_t                fairness_weight = 1;
};
 
struct NEOGRAPH_API HostAdmissionSnapshot {
    HostResourceProfile profile = HostResourceProfile::detect_current();
    HostResourceVector  reserved;
    HostResourceVector  available;
    std::uint32_t       queued = 0;
    bool                overcommitted = false;
    HostPressureLevel   pressure = HostPressureLevel::Normal;
    std::uint8_t        pressure_scale_percent = 100;
    std::int64_t        pressure_changed_at_ms = 0;
    std::string         pressure_source;
};
 
struct NEOGRAPH_API HostAdmissionControllerConfig {
    std::optional<HostResourceProfile> profile;
    std::uint32_t                      max_pending = 1024;
    std::chrono::milliseconds          aging_quantum{100};
    std::uint8_t                       elevated_capacity_percent = 75;
    std::uint8_t                       critical_capacity_percent = 50;
    std::uint8_t                       recovery_step_percent = 10;
    std::chrono::milliseconds          recovery_quiet_period{5000};
};
 
namespace detail {
class HostAdmissionControllerImpl;
}
 
class NEOGRAPH_API HostResourceLease {
public:
    HostResourceLease() = default;
    HostResourceLease(const HostResourceLease&) = delete;
    HostResourceLease& operator=(const HostResourceLease&) = delete;
    HostResourceLease(HostResourceLease&& other) noexcept;
    HostResourceLease& operator=(HostResourceLease&& other) noexcept;
    ~HostResourceLease() noexcept;
 
    [[nodiscard]] bool held() const noexcept;
    [[nodiscard]] const HostResourceVector& resources() const noexcept;
    [[nodiscard]] std::uint8_t priority_hint() const noexcept;
    void release() noexcept;
 
private:
    friend class HostAdmissionController;
    HostResourceLease(std::shared_ptr<detail::HostAdmissionControllerImpl> impl,
                      std::uint64_t reservation_id,
                      HostResourceVector resources) noexcept;
 
    std::shared_ptr<detail::HostAdmissionControllerImpl> impl_;
    std::uint64_t                                        reservation_id_ = 0;
    HostResourceVector                                   resources_;
};
class NEOGRAPH_API HostAdmissionController {
public:
    explicit HostAdmissionController(HostAdmissionControllerConfig config = {});
    ~HostAdmissionController();
 
    HostAdmissionController(const HostAdmissionController&) = delete;
    HostAdmissionController& operator=(const HostAdmissionController&) = delete;
 
    asio::awaitable<HostResourceLease> reserve_async(
        HostAdmissionRequest request,
        std::shared_ptr<graph::CancelToken> cancel_token = {});
 
    std::optional<HostResourceLease> try_reserve(HostAdmissionRequest request);
 
    void update_profile(HostResourceProfile profile);
    void observe_pressure(HostPressureSample sample);
    [[nodiscard]] HostAdmissionSnapshot snapshot() const;
    void shutdown() noexcept;
 
private:
    std::shared_ptr<detail::HostAdmissionControllerImpl> impl_;
};
 
}  // namespace neograph