eviction.h

Go to the documentation of this file.

#pragma once
 
#include "evictable.h"
#include "graphics.h"
 
#include <memory>
#include <vector>
 
namespace gfx::eviction
{
 
using backing_buffer = std::shared_ptr<std::vector<std::uint8_t>>;
 
inline auto make_backing(const void* data, std::uint32_t size) -> backing_buffer
{
    const auto* bytes = static_cast<const std::uint8_t*>(data);
    return std::make_shared<std::vector<std::uint8_t>>(bytes, bytes + size);
}
 
inline void release_backing_ref(void* /*data*/, void* user_data)
{
    delete static_cast<backing_buffer*>(user_data);
}
 
inline auto make_backing_ref(const backing_buffer& backing) -> const memory_view*
{
    auto* bgfx_ref = new backing_buffer(backing);
    return gfx::make_ref((*bgfx_ref)->data(),
                         static_cast<std::uint32_t>((*bgfx_ref)->size()),
                         release_backing_ref,
                         bgfx_ref);
}
 
enum class init_status : std::uint8_t
{
    ok,          
    unnecessary, 
    unsupported, 
    failed,      
};
 
enum class strategy : std::uint8_t
{
    lru,           
    lfu,           
    largest_first, 
    age_ttl,       
};
 
enum class reclaim_result : std::uint8_t
{
    headroom,     
    reclaimed,    
    insufficient, 
};
 
constexpr auto to_string(reclaim_result r) -> const char*
{
    switch(r)
    {
        case reclaim_result::headroom:     return "headroom";
        case reclaim_result::reclaimed:    return "reclaimed";
        case reclaim_result::insufficient: return "insufficient";
    }
    return "unknown";
}
 
enum class reclaim_kind : std::uint8_t
{
    evictable,
    immediate,
};
 
struct budget_state
{
    std::uint64_t hard_limit_bytes = 0;
    std::uint64_t soft_budget_bytes = 0;
    std::uint64_t target_bytes = 0;
    std::uint64_t safety_margin_bytes = 0;
};
 
struct config
{
    strategy strat = strategy::lru;
    std::uint64_t budget_bytes = 0;
    std::uint64_t target_bytes = 0;
    std::uint32_t min_age_frames = 60;
    std::uint32_t max_idle_frames = 0;
    std::uint32_t max_evictions = 0;
};
 
struct stats
{
    std::uint64_t resident_count = 0;        
    std::uint64_t resident_bytes = 0;        
    std::uint64_t evicted_count = 0;         
    std::uint64_t evicted_bytes = 0;         
    std::uint64_t registered_count = 0;      
    std::uint64_t total_evictions = 0;       
    std::uint64_t total_restores = 0;        
    std::uint64_t total_bytes_evicted = 0;   
    std::uint64_t total_bytes_restored = 0;  
    std::uint64_t failed_restores = 0;       
    std::uint64_t thrash_events = 0;         
    std::uint64_t budget_bytes = 0;          
    std::uint64_t target_bytes = 0;          
    std::uint64_t budget_used_bytes = 0;     
    std::uint64_t last_pass_scanned = 0;     
    std::uint64_t last_pass_evicted = 0;     
    std::uint64_t last_pass_freed_bytes = 0; 
    std::uint64_t pending_release_bytes = 0; 
    double last_pass_ms = 0.0;               
    double last_restore_ms = 0.0;            
};
 
auto init(const config& cfg = {}) -> init_status;
 
auto is_supported() -> bool;
 
void shutdown();
 
auto evict(const config& cfg) -> stats;
 
auto evict() -> stats;
 
auto evict_bytes(std::uint64_t free_bytes,
                 strategy strat = strategy::lru,
                 std::uint32_t min_age_frames = 0,
                 std::uint32_t max_evictions = 0) -> stats;
 
auto evict_all() -> stats;
 
auto reclaim_for(std::uint64_t bytes, reclaim_kind kind = reclaim_kind::immediate) -> reclaim_result;
 
auto would_allocation_fit(std::uint64_t bytes) -> bool;
 
auto restore_all() -> stats;
 
void set_budget(const budget_state& budget, std::uint64_t used_bytes);
 
auto current_budget() -> budget_state;
 
auto peek_queued_bytes() -> std::uint64_t;
 
auto peek_pending_release_bytes() -> std::uint64_t;
 
auto peek_external_queued_bytes() -> std::uint64_t;
 
void note_pending_allocation(std::uint64_t bytes);
 
void clear_queued_allocations();
 
auto get_stats() -> stats;
 
void set_frame(std::uint64_t frame);
 
void advance_frame();
 
// --- Test / diagnostics ---------------------------------------------------------------------
 
auto debug_consume_memory(std::uint64_t bytes) -> std::uint64_t;
 
auto debug_simulate_budget(std::uint64_t target_free_bytes) -> std::uint64_t;
 
void debug_release_memory();
 
auto debug_consumed_bytes() -> std::uint64_t;
 
// --- Internal surface used by gfx::handle_impl ----------------------------------------------
 
void register_resource(ievictable* resource);
 
void register_evicted_resource(ievictable* resource);
 
void unregister_resource(ievictable* resource);
 
void restore_resource(ievictable* resource);
 
} // namespace gfx::eviction