using System.Threading.Channels;

namespace CoreAgent.WebSocketTransport.Interfaces;

/// <summary>
/// 消息通道接口，用于抽象消息队列操作
/// </summary>
/// <typeparam name="T">消息类型</typeparam>
public interface IMessageChannel<T> : IDisposable
{
    /// <summary>
    /// 获取通道容量
    /// </summary>
    int Capacity { get; }
    
    /// <summary>
    /// 获取当前队列长度
    /// </summary>
    int Count { get; }
    
    /// <summary>
    /// 获取通道是否已完成
    /// </summary>
    bool IsCompleted { get; }
    
    /// <summary>
    /// 异步添加消息到队列
    /// </summary>
    /// <param name="message">消息</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>写入任务</returns>
    ValueTask WriteAsync(T message, CancellationToken cancellationToken = default);
    
    /// <summary>
    /// 尝试添加消息到队列（非阻塞）
    /// </summary>
    /// <param name="message">消息</param>
    /// <returns>是否成功添加</returns>
    bool TryWrite(T message);
    
    /// <summary>
    /// 异步读取消息
    /// </summary>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>消息</returns>
    ValueTask<T> ReadAsync(CancellationToken cancellationToken = default);
    
    /// <summary>
    /// 尝试读取消息（非阻塞）
    /// </summary>
    /// <param name="message">输出消息</param>
    /// <returns>是否成功读取</returns>
    bool TryRead(out T message);
    
    /// <summary>
    /// 等待消息可读
    /// </summary>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>是否有数据可读</returns>
    ValueTask<bool> WaitToReadAsync(CancellationToken cancellationToken = default);
    
    /// <summary>
    /// 完成通道，不再接受新消息
    /// </summary>
    void Complete();
    
    /// <summary>
    /// 清空队列中的所有消息
    /// </summary>
    void Clear();
}