diff --git a/cocos/core/algorithm/binary-search.ts b/cocos/core/algorithm/binary-search.ts index 291d18121e..ab35072235 100644 --- a/cocos/core/algorithm/binary-search.ts +++ b/cocos/core/algorithm/binary-search.ts @@ -28,7 +28,7 @@ * Searches the **ascending sorted** array for an element and returns the index of that element. * @param array The array to search in. * @param value The value to search. - * @return The index of the searched element in the sorted array, if found; + * @returns The index of the searched element in the sorted array, if found; * otherwise, returns the complement of the index of the next element greater than the element to be searched or, * returns the complement of array's length if no element is greater than the element to be searched or the array is empty. * @engineInternal @@ -42,7 +42,7 @@ export function binarySearch (array: number[], value: number) { * @param array The array to search in. * @param value The value to search. * @param EPSILON The epsilon to compare the numbers. Default to `1e-6`. - * @return The index of the searched element in the sorted array, if found; + * @returns The index of the searched element in the sorted array, if found; * otherwise, returns the complement of the index of the next element greater than the element to be searched or, * returns the complement of array's length if no element is greater than the element to be searched or the array is empty. * @engineInternal @@ -69,7 +69,7 @@ export function binarySearchEpsilon (array: Readonly>, value: * @param array The array to search in. * @param value The value to search. * @param lessThan Comparison function object which returns ​true if the first argument is less than the second. - * @return The index of the searched element in the sorted array, if found; + * @returns The index of the searched element in the sorted array, if found; * otherwise, returns the complement of the index of the next element greater than the searching element or, * returns the complement of array's length if no element is greater than the searching element or the array is empty. * @engineInternal diff --git a/cocos/core/algorithm/move.ts b/cocos/core/algorithm/move.ts index dde3d2a5cd..358f40791d 100644 --- a/cocos/core/algorithm/move.ts +++ b/cocos/core/algorithm/move.ts @@ -8,7 +8,7 @@ import { assertsArrayIndex } from '../data/utils/asserts'; * @param array @en The array to be rotated. @zh 被修改的数组。 * @param first @en The beginning of the original range. @zh 移动区间的起始坐标。 * @param last @en The end of the original range. @zh 移动区间的结束坐标。 - * @return @en The input array. @zh 输入的数组。 + * @returns @en The input array. @zh 输入的数组。 * @engineInternal */ export function shift (array: T[], first: number, last: number) { diff --git a/cocos/core/algorithm/murmurhash2_gc.ts b/cocos/core/algorithm/murmurhash2_gc.ts index 18824abd12..e6ab50a20c 100644 --- a/cocos/core/algorithm/murmurhash2_gc.ts +++ b/cocos/core/algorithm/murmurhash2_gc.ts @@ -39,6 +39,13 @@ const getUint8ForString = String.prototype.charCodeAt; function getUint8ForArray (this: Uint8Array, idx: number) { return this[idx]; } +/** + * @en JS Implementation of MurmurHash2. Original implementation is http://github.com/garycourt/murmurhash-js. + * @zh MurmurHash2 的 JS 实现。原始实现是 http://github.com/garycourt/murmurhash-js 。 + * @param input @en ASCII string or a Uint8Array to be hashed. @zh 希望被哈希的 ASCII 字符串或者 Uint8Array. + * @param seed @en Hash seed. Should be a positive integer. @zh 哈希种子。必须是个正整数。 + * @returns @en 32-bit positive integer hash. @zh 32位正整数哈希值。 + */ export function murmurhash2_32_gc (input: string | Uint8Array, seed: number) { let l = input.length; let h = seed ^ l; @@ -62,10 +69,15 @@ export function murmurhash2_32_gc (input: string | Uint8Array, seed: number) { } switch (l) { - case 3: h ^= (getUint8.call(input, i + 2) & 0xff) << 16; - case 2: h ^= (getUint8.call(input, i + 1) & 0xff) << 8; - case 1: h ^= (getUint8.call(input, i) & 0xff); + case 3: h ^= (getUint8.call(input, i + 2) & 0xff) << 16; break; + case 2: h ^= (getUint8.call(input, i + 1) & 0xff) << 8; break; + case 1: + h ^= (getUint8.call(input, i) & 0xff); h = (((h & 0xffff) * 0x5bd1e995) + ((((h >>> 16) * 0x5bd1e995) & 0xffff) << 16)); + break; + default: + // do nothing, just make VSCode happy. + break; } h ^= h >>> 13; diff --git a/cocos/core/memop/cached-array.ts b/cocos/core/memop/cached-array.ts index 1bfda8ce54..4f1eb154b4 100644 --- a/cocos/core/memop/cached-array.ts +++ b/cocos/core/memop/cached-array.ts @@ -1,5 +1,5 @@ /* - Copyright (c) 2020 Xiamen Yaji Software Co., Ltd. + Copyright (c) 2020-2022 Xiamen Yaji Software Co., Ltd. https://www.cocos.com/ @@ -36,17 +36,17 @@ import { ScalableContainer } from './scalable-container'; export class CachedArray extends ScalableContainer { /** * @en - * The array which stores actual content + * The array which stores actual content. * @zh - * 实际存储数据内容的数组 + * 实际存储数据内容的数组。 */ public array: T[]; /** * @en - * The actual count of data object + * The actual count of data object. * @zh - * 实际数据内容数量 + * 实际存储的元素数量。 */ public length = 0; @@ -54,8 +54,13 @@ export class CachedArray extends ScalableContainer { private _initSize = 0; /** - * @param length Initial length - * @param compareFn Comparison function for sorting + * @en Constructor. @zh 构造函数。 + * @param length @en Initial length of the CachedArray. @zh CachedArray 的初始长度。 + * @param compareFn @en Function used to determine the order of the elements. It is expected to return + * a negative value if the first argument is less than the second argument, zero if they're equal, and a positive + * value otherwise. If omitted, the elements are sorted in ascending, ASCII character order. + * @zh 用来确定元素顺序的函数。如果第一个参数小于第二个参数,它应该返回一个负值,如果它们相等,则返回0,否则返回一个正值。 + * 如果省略,元素将按 ASCII 字符升序排序。 */ constructor (length: number, compareFn?: (a: T, b: T) => number) { super(); @@ -67,10 +72,10 @@ export class CachedArray extends ScalableContainer { /** * @en - * Push an element to the end of the array + * Push an element to the end of the array. * @zh - * 向数组末尾添加一个元素 - * @param item The item to be added + * 向数组末尾添加一个元素。 + * @param item @en The item to be added. @zh 被添加到数组的元素。 */ public push (item: T) { this.array[this.length++] = item; @@ -80,8 +85,9 @@ export class CachedArray extends ScalableContainer { * @en * Pop the last element in the array. The [[length]] will reduce, but the internal array will keep its size. * @zh - * 弹出数组最后一个元素,CachedArray 的 [[length]] 会减少,但是内部数组的实际长度不变 - * @return The last element. + * 弹出数组最后一个元素,CachedArray 的 [[length]] 会减少,但是内部数组的实际长度不变。 + * @returns @en The last element of this CachedArray. If CachedArray is empty, will return undefined. + * @zh 数组的最后一个元素。如果数组为空,将返回 undefined。 */ public pop (): T | undefined { return this.array[--this.length]; @@ -89,11 +95,12 @@ export class CachedArray extends ScalableContainer { /** * @en - * Get the element at the specified index of the array + * Get the element at the specified index of the array. * @zh - * 得到数组中指定位置的元素 - * @param idx The index of the requested element - * @return The element at given index + * 获取数组中指定位置的元素。 + * @param idx @en The index of the requested element. @zh 用于获取数组元素的索引。 + * @returns @en The element at given index. If idx not in [0, [[length]]) or array is empty, will return undefined. + * @zh 数组下标对应的元素。如果 idx 超出 [0, [[length]]),或者数组是空的,将返回 undefined。 */ public get (idx: number): T | undefined { return this.array[idx]; @@ -111,9 +118,9 @@ export class CachedArray extends ScalableContainer { /** * @en - * Clear the cache. The [[length]] will be set to 0, and clear the internal array. + * Destroy the array. The [[length]] will be set to 0, and clear the internal array. * @zh - * 清空数组所有元素。[[length]] 会被设为 0,并且清空内部数组 + * 销毁数组。[[length]] 会被设为 0,并且清空内部数组。 */ public destroy () { this.length = 0; @@ -121,6 +128,10 @@ export class CachedArray extends ScalableContainer { super.destroy(); } + /** + * @en Requests the removal of unused capacity. + * @zh 尝试释放多余的内存。 + */ public tryShrink () { if (this.array.length >> 2 > this.length) { this.array.length = Math.max(this._initSize, this.array.length >> 1); @@ -129,9 +140,10 @@ export class CachedArray extends ScalableContainer { /** * @en - * Sort the existing elements in cache + * Sort the existing elements in cache by [[compareFn]] passed in constructor. + * If [[compareFn]] is not passed in, the elements are sorted in ascending, ASCII character order. * @zh - * 排序所有现有元素 + * 使用构造函数传入的 [[compareFn]] 排序所有现有元素。如果没有传入比较函数,将按照 ASCII 升序排序。 */ public sort () { this.array.length = this.length; @@ -140,10 +152,10 @@ export class CachedArray extends ScalableContainer { /** * @en - * Add all elements of a given array to the end of the current array + * Add all elements of a given array to the end of the current array. * @zh - * 添加一个指定数组中的所有元素到当前数组末尾 - * @param array The given array to be appended + * 添加一个指定数组中的所有元素到当前数组末尾。 + * @param array @en The given array to be appended. @zh 被添加的数组。 */ public concat (array: T[]) { for (let i = 0; i < array.length; ++i) { @@ -154,7 +166,9 @@ export class CachedArray extends ScalableContainer { /** * @en Delete the element at the specified location and move the last element to that location. * @zh 删除指定位置的元素并将最后一个元素移动至该位置。 - * @param idx The index of the element to be deleted + * @param idx @en The index of the element to be deleted. If idx out of range [0, length), there is + * not effect. + * @zh 希望被删除的索引。如果索引超出 [0, length),将没有效果。 */ public fastRemove (idx: number) { if (idx >= this.length || idx < 0) { @@ -165,9 +179,11 @@ export class CachedArray extends ScalableContainer { } /** - * @en Returns the first index at which a given element can be found in the array. - * @zh 返回在数组中可以找到一个给定元素的第一个索引。 - * @param val The element + * @en Returns the first index that compares equal to val. + * @zh 返回在数组中找到的第一个和 val 相等的元素的索引。 + * @param val @en Value to search for. @zh 搜索的值。 + * @returns The index to the first element that compares equal to val. If no elements match, returns -1. + * @zh 第一个和 val 相等的元素的索引。如果没找到,将返回 -1。 */ public indexOf (val: T) { for (let i = 0, len = this.length; i < len; ++i) { diff --git a/cocos/core/memop/container-manager.ts b/cocos/core/memop/container-manager.ts index a7957042c5..332c58707b 100644 --- a/cocos/core/memop/container-manager.ts +++ b/cocos/core/memop/container-manager.ts @@ -1,5 +1,5 @@ /* - Copyright (c) 2021 Xiamen Yaji Software Co., Ltd. + Copyright (c) 2021-2022 Xiamen Yaji Software Co., Ltd. https://www.cocos.com/ @@ -25,17 +25,32 @@ import { fastRemoveAt } from '../utils/array'; import { ScalableContainer } from './scalable-container'; +/** + * @en ContainerManager is a sequence container that stores ScalableContainers. + * It will shrink all managed ScalableContainer in a fixed interval. + */ class ContainerManager { private _pools: ScalableContainer[] = []; private _lastShrinkPassed = 0; + /** + * @en Shrink interval in seconds. + */ public shrinkTimeSpan = 5; + /** + * @en Add a ScalableContainer. Will add the same ScalableContainer instance once. + * @param pool @en The ScalableContainer to add. + */ addContainer (pool: ScalableContainer) { if (pool._poolHandle !== -1) return; pool._poolHandle = this._pools.length; this._pools.push(pool); } + /** + * @en Remove a ScalableContainer. + * @param pool @en The ScalableContainer to remove. + */ removeContainer (pool: ScalableContainer) { if (pool._poolHandle === -1) return; this._pools[this._pools.length - 1]._poolHandle = pool._poolHandle; @@ -43,12 +58,19 @@ class ContainerManager { pool._poolHandle = -1; } + /** + * @en Try to shrink all managed ScalableContainers. + */ tryShrink () { for (let i = 0; i < this._pools.length; i++) { this._pools[i].tryShrink(); } } + /** + * @en An update function invoked every frame. + * @param dt @en Delta time of frame interval in secondes. + */ update (dt: number) { this._lastShrinkPassed += dt; if (this._lastShrinkPassed > this.shrinkTimeSpan) { @@ -58,4 +80,7 @@ class ContainerManager { } } +/** + * @en A global ContainerManager instance. + */ export const containerManager = new ContainerManager(); diff --git a/cocos/core/memop/pool.ts b/cocos/core/memop/pool.ts index 3aac1723b5..cbbb8dddf1 100644 --- a/cocos/core/memop/pool.ts +++ b/cocos/core/memop/pool.ts @@ -1,5 +1,5 @@ /* - Copyright (c) 2020 Xiamen Yaji Software Co., Ltd. + Copyright (c) 2020-2022 Xiamen Yaji Software Co., Ltd. https://www.cocos.com/ @@ -36,15 +36,20 @@ export class Pool extends ScalableContainer { private _ctor: () => T; private _elementsPerBatch: number; private _nextAvail: number; - private _freepool: T[] = []; + private _freePool: T[] = []; private _dtor: ((obj: T) => void) | null; /** - * @en Constructor with the allocator of elements and initial pool size - * @zh 使用元素的构造器和初始大小的构造函数 - * @param ctor The allocator of elements in pool, it's invoked directly without `new` - * @param elementsPerBatch Initial pool size, this size will also be the incremental size when the pool is overloaded - * @param dtor The finalizer of element, it's invoked when this container is destroyed or shrunk + * @en Constructor with the allocator of elements and initial pool size. + * @zh 使用元素的构造器和初始大小的构造函数。 + * @param ctor @en The allocator of elements in pool, it's invoked directly without `new` in Pool. + * @zh 元素的构造器,Pool 内部使用该构造器直接创建实例。 + * @param elementsPerBatch @en Initial pool size, this size will also be the incremental size when + * the pool is overloaded. + * @zh 对象池的初始大小。当对象池扩容时,也会使用该值。 + * @param dtor @en The finalizer of element, it's invoked when this Pool is destroyed or shrunk if + * it is valid. + * @zh 元素的析构器。如果存在的话,当对象池销毁或者缩容时,会使用该析构器。 */ constructor (ctor: () => T, elementsPerBatch: number, dtor?: (obj: T) => void) { super(); @@ -54,56 +59,63 @@ export class Pool extends ScalableContainer { this._nextAvail = this._elementsPerBatch - 1; for (let i = 0; i < this._elementsPerBatch; ++i) { - this._freepool.push(ctor()); + this._freePool.push(ctor()); } } /** * @en Take an object out of the object pool. * @zh 从对象池中取出一个对象。 - * @return An object ready for use. This function always return an object. + * @returns @en An object ready for use. This function always returns an object. + * @zh 该函数总是返回一个可用的对象。 */ public alloc (): T { if (this._nextAvail < 0) { - this._freepool.length = this._elementsPerBatch; + this._freePool.length = this._elementsPerBatch; for (let i = 0; i < this._elementsPerBatch; i++) { - this._freepool[i] = this._ctor(); + this._freePool[i] = this._ctor(); } this._nextAvail = this._elementsPerBatch - 1; } - return this._freepool[this._nextAvail--]; + return this._freePool[this._nextAvail--]; } /** * @en Put an object back into the object pool. * @zh 将一个对象放回对象池中。 - * @param obj The object to be put back into the pool + * @param obj @en The object to be put back into the pool. + * @zh 放回对象池中的对象。 */ public free (obj: T) { - this._freepool[++this._nextAvail] = obj; + this._freePool[++this._nextAvail] = obj; } /** * @en Put multiple objects back into the object pool. * @zh 将一组对象放回对象池中。 - * @param objs An array of objects to be put back into the pool + * @param objs @en An array of objects to be put back into the pool. + * @zh 放回对象池中的一组对象。 */ public freeArray (objs: T[]) { - this._freepool.length = this._nextAvail + 1; - Array.prototype.push.apply(this._freepool, objs); + this._freePool.length = this._nextAvail + 1; + Array.prototype.push.apply(this._freePool, objs); this._nextAvail += objs.length; } + /** + * @en Try to shrink the object pool to reduce memory usage. + * @zh 尝试缩容对象池,以释放内存。 + */ public tryShrink () { if (this._nextAvail >> 1 > this._elementsPerBatch) { if (this._dtor) { for (let i = this._nextAvail >> 1; i <= this._nextAvail; i++) { - this._dtor(this._freepool[i]); + this._dtor(this._freePool[i]); } } - this._freepool.length = this._nextAvail >> 1; - this._nextAvail = this._freepool.length - 1; + this._freePool.length = this._nextAvail >> 1; + this._nextAvail = this._freePool.length - 1; } } @@ -117,10 +129,10 @@ export class Pool extends ScalableContainer { const readDtor = dtor || this._dtor; if (readDtor) { for (let i = 0; i <= this._nextAvail; i++) { - readDtor(this._freepool[i]); + readDtor(this._freePool[i]); } } - this._freepool.length = 0; + this._freePool.length = 0; this._nextAvail = -1; super.destroy(); } diff --git a/cocos/core/memop/recycle-pool.ts b/cocos/core/memop/recycle-pool.ts index 7ba42726e5..9f6be0e355 100644 --- a/cocos/core/memop/recycle-pool.ts +++ b/cocos/core/memop/recycle-pool.ts @@ -1,5 +1,5 @@ /* - Copyright (c) 2020 Xiamen Yaji Software Co., Ltd. + Copyright (c) 2020-2022 Xiamen Yaji Software Co., Ltd. https://www.cocos.com/ @@ -79,8 +79,8 @@ export class RecyclePool extends ScalableContainer { } /** - * @en Resets the object pool. Only changes the length to 0 - * @zh 清空对象池。目前仅仅会设置尺寸为 0 + * @en Resets the object pool. Only changes the length to 0. + * @zh 清空对象池。目前仅仅会设置尺寸为 0。 */ public reset () { this._count = 0; @@ -89,7 +89,7 @@ export class RecyclePool extends ScalableContainer { /** * @en Resize the object poo, and fills with new created elements. * @zh 设置对象池大小,并填充新的元素。 - * @param size The new size of the pool + * @param size @en The new size of the pool. @zh 新的对象池大小。 */ public resize (size: number) { if (size > this._data.length) { @@ -100,9 +100,8 @@ export class RecyclePool extends ScalableContainer { } /** - * @en Expand the object pool, the size will be increment to current size times two, and fills with new created elements. - * @zh 扩充对象池容量,会自动扩充尺寸到两倍,并填充新的元素。 - * @param idx + * @en Expand the array size to 2 times the original size, and fills with new created elements. + * @zh 扩充对象池容量,会自动扩充尺寸到原来的 2 倍,并填充新的元素。 */ public add () { if (this._count >= this._data.length) { @@ -112,6 +111,10 @@ export class RecyclePool extends ScalableContainer { return this._data[this._count++]; } + /** + * @en Destroy the object pool. Please don't use it any more after it is destroyed. + * @zh 销毁对象池。销毁后不能继续使用。 + */ public destroy () { if (this._dtor) { for (let i = 0; i < this._data.length; i++) { @@ -123,6 +126,10 @@ export class RecyclePool extends ScalableContainer { super.destroy(); } + /** + * @en Try to shrink the object pool to free memory. + * @zh 尝试回收没用的对象,释放内存。 + */ public tryShrink () { if (this._data.length >> 2 > this._count) { const length = Math.max(this._initSize, this._data.length >> 1); @@ -136,9 +143,9 @@ export class RecyclePool extends ScalableContainer { } /** - * @en Remove an element of the object pool. This will also decrease size of the pool - * @zh 移除对象池中的一个元素,同时会减小池子尺寸。 - * @param idx The index of the element to be removed + * @en Remove the element with the specified index from the object pool. This will decrease pool size. + * @zh 移除对象池中指定索引的元素,会减小池子尺寸。 + * @param idx @en The index of the element to remove. @zh 被移除的元素的索引。 */ public removeAt (idx: number) { if (idx >= this._count) {