image_cache.hpp

Go to the documentation of this file.

#pragma once
 
// Image cache.
//
// URI-keyed cache for decoded images consumed by ImageView and related
// paint paths. The cache is backend-agnostic: callers provide decode and
// release callbacks, while the cache owns lookup, stats, LRU trimming, and
// clear-on-memory-pressure behavior.
//
// Keys:
//   string URI ("file:///…", "resource://…", "memory://sha256=…")
//   combined with mtime/size for file URIs so a rebuilt image
//   invalidates automatically.
 
#include <cstddef>
#include <cstdint>
#include <functional>
#include <mutex>
#include <optional>
#include <string>
#include <unordered_map>
#include <vector>
 
namespace pulp::view {
 
struct DecodedImage {
    uint32_t width = 0;
    uint32_t height = 0;
    void* native_handle = nullptr;
    std::size_t bytes = 0;
};
 
struct ImageCacheStats {
    std::size_t entry_count = 0;
    std::size_t total_bytes = 0;
    std::size_t hits = 0;
    std::size_t misses = 0;
    std::size_t evictions = 0;
};

using ImageDecodeFn = std::function<std::optional<DecodedImage>(const std::string& uri)>;

using ImageReleaseFn = std::function<void(DecodedImage&)>;
 
class ImageCache {
public:
    ImageCache() = default;
 
    void set_decoder(ImageDecodeFn fn) { decoder_ = std::move(fn); }
    void set_releaser(ImageReleaseFn fn) { releaser_ = std::move(fn); }

    void set_byte_budget(std::size_t bytes) { budget_ = bytes; try_trim_(); }

    const DecodedImage* get(const std::string& uri);

    void clear();
 
    ImageCacheStats stats() const;
 
private:
    struct Entry {
        DecodedImage image;
        uint64_t last_used = 0;
    };
 
    void evict_one_();
    void try_trim_();
 
    mutable std::mutex mu_;
    std::unordered_map<std::string, Entry> entries_;
    ImageDecodeFn decoder_;
    ImageReleaseFn releaser_;
    std::size_t total_bytes_ = 0;
    std::size_t budget_ = 0;
    uint64_t tick_ = 0;
    ImageCacheStats stats_{};
};
 
}  // namespace pulp::view