video-pc/AvPlayer2/interfaces/IBufferManager.h

#ifndef IBUFFERMANAGER_H
#define IBUFFERMANAGER_H

#include <memory>
#include <functional>
#include <chrono>
#include <string>
#include <vector>

namespace AVPlayer2 {
namespace Core {

/**
 * 缓冲区状态枚举
 */
enum class BufferState {
    Empty,          // 空缓冲区
    Filling,        // 填充中
    Ready,          // 准备就绪
    Full,           // 缓冲区满
    Draining,       // 排空中
    Error           // 错误状态
};

/**
 * 缓冲区类型枚举
 */
enum class BufferType {
    Audio,          // 音频缓冲区
    Video,          // 视频缓冲区
    Subtitle,       // 字幕缓冲区
    Packet,         // 数据包缓冲区
    Frame           // 帧缓冲区
};

/**
 * 缓冲策略枚举
 */
enum class BufferStrategy {
    FixedSize,      // 固定大小
    DynamicSize,    // 动态大小
    TimeBased,      // 基于时间
    AdaptiveSize    // 自适应大小
};

} // namespace Core

namespace Types {

/**
 * 缓冲区配置
 */
struct BufferConfig {
    Core::BufferType type;              // 缓冲区类型
    Core::BufferStrategy strategy;      // 缓冲策略
    size_t maxSize;                     // 最大大小（字节）
    size_t minSize;                     // 最小大小（字节）
    int maxCount;                       // 最大数量
    int minCount;                       // 最小数量
    std::chrono::milliseconds maxDuration;     // 最大时长
    std::chrono::milliseconds minDuration;     // 最小时长
    double lowWaterMark;                // 低水位标记（0.0-1.0）
    double highWaterMark;               // 高水位标记（0.0-1.0）
    bool enablePreallocation;           // 启用预分配
    bool enableMemoryPool;              // 启用内存池
    
    BufferConfig() {
        type = Core::BufferType::Audio;
        strategy = Core::BufferStrategy::FixedSize;
        maxSize = 1024 * 1024;  // 1MB
        minSize = 64 * 1024;    // 64KB
        maxCount = 100;
        minCount = 10;
        maxDuration = std::chrono::milliseconds(5000);  // 5秒
        minDuration = std::chrono::milliseconds(1000);  // 1秒
        lowWaterMark = 0.2;
        highWaterMark = 0.8;
        enablePreallocation = true;
        enableMemoryPool = true;
    }
};

/**
 * 缓冲区统计信息
 */
struct BufferStats {
    Core::BufferType type;              // 缓冲区类型
    Core::BufferState state;            // 当前状态
    size_t currentSize;                 // 当前大小（字节）
    size_t maxSize;                     // 最大大小（字节）
    int currentCount;                   // 当前数量
    int maxCount;                       // 最大数量
    std::chrono::milliseconds currentDuration;  // 当前时长
    std::chrono::milliseconds maxDuration;      // 最大时长
    double fillLevel;                   // 填充级别（0.0-1.0）
    double utilizationRate;             // 利用率（0.0-1.0）
    int underrunCount;                  // 下溢次数
    int overrunCount;                   // 上溢次数
    double averageInputRate;            // 平均输入速率（字节/秒）
    double averageOutputRate;           // 平均输出速率（字节/秒）
    std::chrono::microseconds lastInputTime;    // 最后输入时间
    std::chrono::microseconds lastOutputTime;   // 最后输出时间
    
    BufferStats() {
        type = Core::BufferType::Audio;
        state = Core::BufferState::Empty;
        currentSize = 0;
        maxSize = 0;
        currentCount = 0;
        maxCount = 0;
        currentDuration = std::chrono::milliseconds(0);
        maxDuration = std::chrono::milliseconds(0);
        fillLevel = 0.0;
        utilizationRate = 0.0;
        underrunCount = 0;
        overrunCount = 0;
        averageInputRate = 0.0;
        averageOutputRate = 0.0;
        lastInputTime = std::chrono::microseconds(0);
        lastOutputTime = std::chrono::microseconds(0);
    }
};

/**
 * 缓冲区项目信息
 */
struct BufferItem {
    std::string id;                     // 项目ID
    std::shared_ptr<void> data;         // 数据指针
    size_t size;                        // 数据大小
    std::chrono::microseconds timestamp;        // 时间戳
    std::chrono::microseconds duration;         // 持续时间
    int priority;                       // 优先级
    std::map<std::string, std::string> metadata;  // 元数据
    
    BufferItem() {
        size = 0;
        timestamp = std::chrono::microseconds(0);
        duration = std::chrono::microseconds(0);
        priority = 0;
    }
};

/**
 * 内存池统计信息
 */
struct MemoryPoolStats {
    size_t totalAllocated;              // 总分配内存
    size_t totalUsed;                   // 总使用内存
    size_t totalFree;                   // 总空闲内存
    int allocationCount;                // 分配次数
    int deallocationCount;              // 释放次数
    int poolHitCount;                   // 池命中次数
    int poolMissCount;                  // 池未命中次数
    double fragmentationRatio;          // 碎片率
    
    MemoryPoolStats() {
        totalAllocated = 0;
        totalUsed = 0;
        totalFree = 0;
        allocationCount = 0;
        deallocationCount = 0;
        poolHitCount = 0;
        poolMissCount = 0;
        fragmentationRatio = 0.0;
    }
};

} // namespace Types

namespace Core {

/**
 * 缓冲区管理器抽象接口
 * 提供统一的缓冲区管理功能
 */
class IBufferManager {
public:
    virtual ~IBufferManager() = default;

    /**
     * 初始化缓冲区管理器
     * @param configs 缓冲区配置列表
     * @return 是否初始化成功
     */
    virtual bool initialize(const std::vector<Types::BufferConfig>& configs) = 0;

    /**
     * 释放缓冲区管理器
     */
    virtual void release() = 0;

    /**
     * 启动缓冲区管理器
     * @return 是否启动成功
     */
    virtual bool start() = 0;

    /**
     * 停止缓冲区管理器
     */
    virtual void stop() = 0;

    /**
     * 重置所有缓冲区
     */
    virtual void reset() = 0;

    // ========== 缓冲区操作 ==========
    
    /**
     * 创建缓冲区
     * @param name 缓冲区名称
     * @param config 缓冲区配置
     * @return 是否创建成功
     */
    virtual bool createBuffer(const std::string& name, const Types::BufferConfig& config) = 0;

    /**
     * 销毁缓冲区
     * @param name 缓冲区名称
     * @return 是否销毁成功
     */
    virtual bool destroyBuffer(const std::string& name) = 0;

    /**
     * 清空缓冲区
     * @param name 缓冲区名称
     * @return 是否清空成功
     */
    virtual bool clearBuffer(const std::string& name) = 0;

    /**
     * 调整缓冲区大小
     * @param name 缓冲区名称
     * @param newConfig 新配置
     * @return 是否调整成功
     */
    virtual bool resizeBuffer(const std::string& name, const Types::BufferConfig& newConfig) = 0;

    // ========== 数据操作 ==========
    
    /**
     * 向缓冲区写入数据
     * @param name 缓冲区名称
     * @param item 缓冲区项目
     * @param blocking 是否阻塞等待
     * @return 是否写入成功
     */
    virtual bool writeData(const std::string& name, const Types::BufferItem& item, bool blocking = false) = 0;

    /**
     * 从缓冲区读取数据
     * @param name 缓冲区名称
     * @param item 输出的缓冲区项目
     * @param blocking 是否阻塞等待
     * @return 是否读取成功
     */
    virtual bool readData(const std::string& name, Types::BufferItem& item, bool blocking = false) = 0;

    /**
     * 预览缓冲区数据（不移除）
     * @param name 缓冲区名称
     * @param item 输出的缓冲区项目
     * @param index 预览索引（0为最前面）
     * @return 是否预览成功
     */
    virtual bool peekData(const std::string& name, Types::BufferItem& item, int index = 0) = 0;

    /**
     * 跳过指定数量的数据项
     * @param name 缓冲区名称
     * @param count 跳过数量
     * @return 实际跳过的数量
     */
    virtual int skipData(const std::string& name, int count) = 0;

    /**
     * 根据时间戳跳转
     * @param name 缓冲区名称
     * @param timestamp 目标时间戳
     * @return 是否跳转成功
     */
    virtual bool seekToTimestamp(const std::string& name, std::chrono::microseconds timestamp) = 0;

    // ========== 状态查询 ==========
    
    /**
     * 获取缓冲区状态
     * @param name 缓冲区名称
     * @return 缓冲区状态
     */
    virtual BufferState getBufferState(const std::string& name) = 0;

    /**
     * 获取缓冲区统计信息
     * @param name 缓冲区名称
     * @return 统计信息
     */
    virtual Types::BufferStats getBufferStats(const std::string& name) = 0;

    /**
     * 获取所有缓冲区统计信息
     * @return 所有缓冲区统计信息
     */
    virtual std::vector<Types::BufferStats> getAllBufferStats() = 0;

    /**
     * 检查缓冲区是否存在
     * @param name 缓冲区名称
     * @return 是否存在
     */
    virtual bool hasBuffer(const std::string& name) = 0;

    /**
     * 检查缓冲区是否为空
     * @param name 缓冲区名称
     * @return 是否为空
     */
    virtual bool isEmpty(const std::string& name) = 0;

    /**
     * 检查缓冲区是否已满
     * @param name 缓冲区名称
     * @return 是否已满
     */
    virtual bool isFull(const std::string& name) = 0;

    /**
     * 检查缓冲区是否达到低水位
     * @param name 缓冲区名称
     * @return 是否达到低水位
     */
    virtual bool isLowWaterMark(const std::string& name) = 0;

    /**
     * 检查缓冲区是否达到高水位
     * @param name 缓冲区名称
     * @return 是否达到高水位
     */
    virtual bool isHighWaterMark(const std::string& name) = 0;

    /**
     * 获取缓冲区可用空间
     * @param name 缓冲区名称
     * @return 可用空间（字节）
     */
    virtual size_t getAvailableSpace(const std::string& name) = 0;

    /**
     * 获取缓冲区已用空间
     * @param name 缓冲区名称
     * @return 已用空间（字节）
     */
    virtual size_t getUsedSpace(const std::string& name) = 0;

    /**
     * 获取缓冲区数据项数量
     * @param name 缓冲区名称
     * @return 数据项数量
     */
    virtual int getItemCount(const std::string& name) = 0;

    /**
     * 获取缓冲区时长
     * @param name 缓冲区名称
     * @return 缓冲区时长
     */
    virtual std::chrono::milliseconds getBufferDuration(const std::string& name) = 0;

    // ========== 内存池管理 ==========
    
    /**
     * 启用内存池
     * @param enable 是否启用
     */
    virtual void enableMemoryPool(bool enable) = 0;

    /**
     * 获取内存池统计信息
     * @return 内存池统计信息
     */
    virtual Types::MemoryPoolStats getMemoryPoolStats() = 0;

    /**
     * 清理内存池
     */
    virtual void cleanupMemoryPool() = 0;

    /**
     * 预分配内存
     * @param size 预分配大小（字节）
     * @param count 预分配数量
     * @return 是否预分配成功
     */
    virtual bool preallocateMemory(size_t size, int count) = 0;

    // ========== 回调设置 ==========
    
    /**
     * 设置缓冲区状态变化回调
     * @param callback 状态变化回调函数
     */
    virtual void setBufferStateChangedCallback(
        std::function<void(const std::string&, BufferState, BufferState)> callback) = 0;

    /**
     * 设置低水位回调
     * @param callback 低水位回调函数
     */
    virtual void setLowWaterMarkCallback(
        std::function<void(const std::string&)> callback) = 0;

    /**
     * 设置高水位回调
     * @param callback 高水位回调函数
     */
    virtual void setHighWaterMarkCallback(
        std::function<void(const std::string&)> callback) = 0;

    /**
     * 设置缓冲区满回调
     * @param callback 缓冲区满回调函数
     */
    virtual void setBufferFullCallback(
        std::function<void(const std::string&)> callback) = 0;

    /**
     * 设置缓冲区空回调
     * @param callback 缓冲区空回调函数
     */
    virtual void setBufferEmptyCallback(
        std::function<void(const std::string&)> callback) = 0;

    /**
     * 设置错误回调
     * @param callback 错误回调函数
     */
    virtual void setErrorCallback(
        std::function<void(const std::string&, const std::string&)> callback) = 0;
};

/**
 * 缓冲区管理器工厂接口
 */
class IBufferManagerFactory {
public:
    virtual ~IBufferManagerFactory() = default;

    /**
     * 创建缓冲区管理器实例
     * @param name 管理器名称
     * @return 缓冲区管理器智能指针
     */
    virtual std::unique_ptr<IBufferManager> createBufferManager(const std::string& name = "") = 0;

    /**
     * 获取默认缓冲区配置
     * @param type 缓冲区类型
     * @return 默认配置
     */
    virtual Types::BufferConfig getDefaultConfig(BufferType type) = 0;

    /**
     * 获取推荐的缓冲区大小
     * @param type 缓冲区类型
     * @return 推荐大小（字节）
     */
    virtual size_t getRecommendedBufferSize(BufferType type) = 0;
};

} // namespace Core
} // namespace AVPlayer2

#endif // IBUFFERMANAGER_H