dajiangroute/tiles/TracePoint/circQueue.js

/*==============================================================================================================
 *
 * 												CircQueue_t
 * 
 * =============================================================================================================
 * 描述：
 * 		这是一个环形队列, 支持入队、出队、丢弃数据等操作。
 * 		支持深拷贝入队数据，避免外部修改影响队列内部数据。
 * 		支持最大内存限制，超过限制则拒绝入队。
 * 		支持异步入队和出队操作，适用于异步场景。
 * 		支持 JSON 序列化，方便调试和存储。
 * 注意事项：
 *   	1. 队列满时入队会失败，需处理返回值
 *  	2. 出队时返回深拷贝对象，避免修改影响队列
 * 		3. 异步操作时需注意超时处理，避免死循环
 * 		4. 仅支持可序列化对象, 深拷贝基于 JSON 方法，可能无法处理函数、循环引用等复杂对象
 * 		5. 内存限制基于估算的 JSON 字符串长度
 * 示例：
 *   	const queue = new CircQueue(5, { deepCopy: true, maxMemoryBytes: 1024 }); 	// 创建容量为5的队列，启用深拷贝，最大内存限制1KB
 *   	queue.enter({ name: "Alice" });												// 入队一个对象
 *  	const item = queue.out();													// 出队一个对象，返回深拷贝							
 *  	queue.discard(2);															// 丢弃队尾2个对象
 * 		queue.send({ msg: "async item" }, 1000); 									// 异步入队，超时1秒
 * 		queue.recv(1000); 															// 异步出队，超时1秒
 * 		console.log(JSON.stringify(queue)); 										// 序列化队列内容
 *=============================================================================================================*/
class CircQueue 
{
	/**
	 * 构造函数
	 * capacity		：队列可容纳的最大项目数
	 * options		：可选的配置对象，用于自定义环形队列的行为。它支持以下配置项：
	 * 					deepCopy		：控制入队时是否深拷贝元素, 默认 true
	 * 					maxMemoryBytes	：队列的最大内存限制 (单位：字节)，默认 Infinity, 不限制内存
	 * 									  若传 1024 * 1024 代表限制 1 M ,超出则队满, 队列会拒绝入队
	 */
	constructor(capacity, options = {}) 
	{
		this.capacity = capacity;						/* 队列容量 (最多存储项目数) */
		this.buffer = new Array(capacity);				/* 队列存储区，使用数组存任意对象 */
		this.head = 0;									/* 队头索引 */
		this.tail = 0;									/* 队尾索引 */
		this.isFull = false;							/* 队满标志 */

		this.deepCopy = options.deepCopy ?? true;					/* 是否启用深拷贝 (默认启用) */
		this.maxMemoryBytes = options.maxMemoryBytes ?? Infinity;	/* 队列最大内存限制 (单位：字节) */
		this.currentMemoryBytes = 0;								/* 当前已使用内存大小 (单位：字节) */
	}

	/* 判断队列是否为空 */
	isEmpty() 
	{
		return this.head === this.tail && !this.isFull;
	}

	/* 判断队列是否已满 */
	isFullFn() 
	{
		return this.isFull;
	}

	/* 估算对象大小 (以 JSON 字符串的 UTF-8 编码长度作为近似值) */
	_estimateSize(obj) 
	{
		try 
		{
			return Buffer.byteLength(JSON.stringify(obj), 'utf8');	/* Node.js 中用于计算字节长度 */
		}
		catch 
		{
			return 0;												/* 若对象不可序列化，返回 0 (避免出错) */
		}
	}

	/* 深拷贝对象 (基于 JSON 的方式，仅支持可序列化对象) */
	_deepClone(obj)
	{
		return this.deepCopy ? JSON.parse(JSON.stringify(obj)) : obj;
	}

	/* 入队操作：将对象放入队尾 */
	enter(item)
	{
		const itemSize = this._estimateSize(item);			/* 估算项目内存大小 */
		if (this.isFullFn() || (this.currentMemoryBytes + itemSize > this.maxMemoryBytes))
		{
			return false;									/* 若队满或超过内存限制则入队失败 */
		}

		const clone = this._deepClone(item);				/* 深拷贝入队数据 (避免外部修改影响队列) */
		this.buffer[this.tail] = clone;						/* 存入队尾 */
		this.tail = (this.tail + 1) % this.capacity;		/* 环形增长 tail */
		this.currentMemoryBytes += itemSize;				/* 增加当前内存使用 */

		if (this.tail === this.head) this.isFull = true;	/* 若尾追头，表示队满 */
		return true;
	}

	/* 出队操作：从队头取出一个对象, 返回深拷贝 */
	out()
	{
		if (this.isEmpty()) return null;						/* 队空返回 null */

		const item = this.buffer[this.head];					/* 读取队头项目 */
		this.currentMemoryBytes -= this._estimateSize(item);	/* 更新内存使用 */
		this.head = (this.head + 1) % this.capacity;			/* 环形增长 head */
		this.isFull = false;									/* 出队必然队不满 */
		return this._deepClone(item);							/* 返回深拷贝，保护队列内部数据 */
	}

	/* 丢弃数据：从队尾向前丢弃 len 项 (反向移动 tail) */
	discard(len)
	{
		for (let i = 0; i < len; i++)
		{
			if (this.isEmpty()) return false;								/* 队空则不能继续丢弃 */

			/* 定位最后一项 */
			const item = this.buffer[(this.tail - 1 + this.capacity) % this.capacity];
			this.currentMemoryBytes -= this._estimateSize(item);			/* 减去内存大小 */
			this.tail = (this.tail - 1 + this.capacity) % this.capacity;	/* tail 回退 */
			this.isFull = false;
		}
		return true;
	}

	/* 获取当前队列中元素个数 */
	getDepth()
	{
		return this.isFull
			? this.capacity
			: (this.tail + this.capacity - this.head) % this.capacity;
	}

	/**
	 * 异步入队，支持超时退出,不会阻塞主线程, 可用于异步场景
	 * buf			: 需要发送的数据
	 * timeoutMs	: 超时时间
	 */
	async send(item, timeoutMs = 0)
	{
		const start = Date.now();

		/* 循环直到成功入队或超时 */
		while (!this.enter(item))
		{
			if (Date.now() - start >= timeoutMs) return false;		/* 超时退出 */
			await new Promise(resolve => setTimeout(resolve, 1));	/* 异步轮询, 自旋加 sleep 挂起 1ms */
		}
		return true;
	}

	/**
	 * 异步出队，支持超时退出,不会阻塞主线程, 可用于异步场景
	 * buf			: 需要发送的数据
	 * timeoutMs	: 超时时间
	 * 返回值：成功取出一个对象(深拷贝)或 null (超时)
	 */
	async recv(timeoutMs = 0)
	{
		const start = Date.now();
		while (true)	
		{
			const item = this.out();
			if (item !== null) return item;							/* 成功取出则返回 */
			if (Date.now() - start >= timeoutMs) return null;		/* 超时退出 */
			await new Promise(resolve => setTimeout(resolve, 1));	/* 异步轮询, 自旋加 sleep 挂起 1ms */
		}
	}

	/* JSON 序列化接口，用于 JSON.stringify(queue) */
	toJSON()
	{
		const result = [];
		let i = this.head;
		let count = this.getDepth();
		while (count-- > 0)
		{
			result.push(this._deepClone(this.buffer[i]));			/* 复制每个元素 */
			i = (i + 1) % this.capacity;							/* 移动到下一个元素 */
		}
		return result;
	}
}
export default CircQueue;
// module.exports = CircQueue;