@nimbus2d/core 0.0.1

package/src/core/PoolManager/ObjectPool.js

@@ -0,0 +1,326 @@
+// ============================================================================
+// Nimbus2D - 泛型对象池
+// ----------------------------------------------------------------------------
+// 职责：
+//   提供通用对象复用能力，支持任意类型的对象池化。
+//   通过 create 函数创建新对象，通过 reset 函数重置对象状态，
+//   通过 validate 函数校验归还的对象是否可复用。
+//
+// 设计决策：
+//   - 使用数组作为空闲列表（freeList），pop() 为 O(1)
+//   - 使用 Set 追踪使用中对象（inUse），has/delete 为 O(1)
+//   - maxSize 限制总对象数（空闲 + 使用中），防止内存无限增长
+//   - 池耗尽时触发 onExhausted 回调并抛出 PoolExhaustedError
+//   - validate 校验失败的对象被丢弃（不归还空闲列表）
+//   - drain() 排空所有空闲对象，shrink() 缩减到指定大小
+//   - 不继承 Subsystem，作为轻量级独立组件由 PoolManager 管理
+// ============================================================================
+
+import { PoolState, PoolError, PoolStateError, PoolExhaustedError } from './PoolTypes.js'
+
+class ObjectPool {
+  // --------------------------------------------------------------------------
+  // 构造函数
+  // --------------------------------------------------------------------------
+
+  /**
+   * 构造函数
+   * @param {Object} options - 池配置
+   * @param {string} [options.name='unnamed'] - 池名称（用于错误消息和事件）
+   * @param {Function} options.create - 创建函数 () => T
+   * @param {Function} [options.reset] - 重置函数 (obj: T) => void
+   * @param {Function} [options.validate] - 验证函数 (obj: T) => boolean（归还时校验）
+   * @param {Function} [options.onExhausted] - 池耗尽回调 (name: string, maxSize: number) => void
+   * @param {number} [options.initialSize=0] - 初始预分配数量
+   * @param {number} [options.maxSize=Infinity] - 最大容量（空闲+使用中总数）
+   * @throws {PoolError} create 函数缺失时抛出
+   */
+  constructor(options) {
+    // 参数校验
+    if (!options || typeof options.create !== 'function') {
+      throw new PoolError('create 函数是必需的')
+    }
+
+    /** @type {string} 池名称 */
+    this._name = options.name || 'unnamed'
+
+    /** @type {Function} 创建函数 */
+    this._create = options.create
+
+    /** @type {Function} 重置函数 */
+    this._reset = options.reset || (() => {})
+
+    /** @type {Function} 验证函数 */
+    this._validate = options.validate || (() => true)
+
+    /** @type {Function|null} 池耗尽回调（由 PoolManager 注册时设置） */
+    this._onExhausted = options.onExhausted || null
+
+    /** @type {number} 最大容量 */
+    this._maxSize = options.maxSize ?? Infinity
+
+    /** @type {PoolState} 池状态 */
+    this._state = PoolState.ACTIVE
+
+    /** @type {Array<T>} 空闲对象列表 */
+    this._freeList = []
+
+    /** @type {Set<T>} 正在使用的对象集合 */
+    this._inUse = new Set()
+
+    /** @type {Object} 统计信息 */
+    this._stats = {
+      /** @type {number} 总创建数量（空闲+使用中） */
+      size: 0,
+      /** @type {number} 可用数量 */
+      available: 0,
+      /** @type {number} 使用中数量 */
+      inUse: 0,
+      /** @type {number} 累计获取次数 */
+      totalAcquired: 0,
+      /** @type {number} 累计归还次数 */
+      totalReleased: 0,
+      /** @type {number} 累计创建次数 */
+      totalCreated: 0
+    }
+
+    // 预分配
+    if (options.initialSize > 0) {
+      this.preallocate(options.initialSize)
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // Getter
+  // --------------------------------------------------------------------------
+
+  /**
+   * 池名称
+   * @type {string}
+   */
+  get name() {
+    return this._name
+  }
+
+  /**
+   * 最大容量
+   * @type {number}
+   */
+  get maxSize() {
+    return this._maxSize
+  }
+
+  /**
+   * 池状态
+   * @type {PoolState}
+   */
+  get state() {
+    return this._state
+  }
+
+  /**
+   * 当前可用对象数量
+   * @type {number}
+   */
+  get available() {
+    return this._stats.available
+  }
+
+  /**
+   * 当前使用中对象数量
+   * @type {number}
+   */
+  get inUseCount() {
+    return this._stats.inUse
+  }
+
+  /**
+   * 总对象数量（空闲+使用中）
+   * @type {number}
+   */
+  get size() {
+    return this._stats.size
+  }
+
+  /**
+   * 是否已销毁
+   * @type {boolean}
+   */
+  get isDestroyed() {
+    return this._state === PoolState.DESTROYED
+  }
+
+  // --------------------------------------------------------------------------
+  // 核心方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 预分配对象
+   * 在池初始化或需要提前创建对象时调用
+   * @param {number} count - 预分配数量
+   * @returns {void}
+   */
+  preallocate(count) {
+    // 已销毁的池不允许预分配
+    if (this._state === PoolState.DESTROYED) return
+
+    for (let i = 0; i < count && this._stats.size < this._maxSize; i++) {
+      const obj = this._create()
+      this._freeList.push(obj)
+      this._stats.size++
+      this._stats.available++
+      this._stats.totalCreated++
+    }
+  }
+
+  /**
+   * 从池中获取对象
+   * 优先从空闲列表取出，空闲列表为空则创建新对象，
+   * 达到 maxSize 限制时触发耗尽回调并抛出 PoolExhaustedError
+   * @returns {T} 获取的对象
+   * @throws {PoolExhaustedError} 池已满且无可用对象
+   */
+  acquire() {
+    // 已销毁的池不允许获取
+    if (this._state === PoolState.DESTROYED) {
+      throw new PoolExhaustedError(this._name, 0)
+    }
+
+    // 已排空的池不允许获取（需要先重新预分配或重建）
+    if (this._state === PoolState.DRAINED) {
+      throw new PoolStateError(`对象池 '${this._name}' 已排空，无法获取对象`)
+    }
+
+    let obj
+
+    if (this._freeList.length > 0) {
+      // 从空闲列表取出
+      obj = this._freeList.pop()
+      this._stats.available--
+    } else if (this._stats.size < this._maxSize) {
+      // 创建新对象
+      obj = this._create()
+      this._stats.size++
+      this._stats.totalCreated++
+    } else {
+      // 池已耗尽：触发回调并抛出专用错误
+      if (this._onExhausted) {
+        this._onExhausted(this._name, this._maxSize)
+      }
+      throw new PoolExhaustedError(this._name, this._maxSize)
+    }
+
+    this._inUse.add(obj)
+    this._stats.inUse++
+    this._stats.totalAcquired++
+    return obj
+  }
+
+  /**
+   * 将对象归还到池
+   * 归还时会调用 reset 重置对象状态，然后调用 validate 校验对象是否可复用。
+   * 校验失败的对象被丢弃（不归还空闲列表，size 递减）。
+   * @param {T} obj - 归还的对象
+   * @returns {void}
+   */
+  release(obj) {
+    // 已销毁的池忽略归还
+    if (this._state === PoolState.DESTROYED) return
+
+    if (!this._inUse.has(obj)) {
+      // 归还未知对象始终警告（可能是重复归还或归还了非本池对象，属于编程错误）
+      console.warn(`[ObjectPool '${this._name}'] 尝试归还不属于本池的对象`)
+      return
+    }
+
+    this._inUse.delete(obj)
+    this._stats.inUse--
+
+    // 重置对象状态
+    this._reset(obj)
+
+    // 验证对象（可选）
+    if (this._validate(obj)) {
+      this._freeList.push(obj)
+      this._stats.available++
+    } else {
+      // 验证失败，丢弃对象
+      this._stats.size--
+    }
+
+    this._stats.totalReleased++
+  }
+
+  /**
+   * 排空池中所有空闲对象
+   * 使用中的对象不受影响，size 调整为使用中数量
+   * @returns {void}
+   */
+  drain() {
+    if (this._state === PoolState.DESTROYED) return
+
+    this._freeList.length = 0
+    this._stats.available = 0
+    this._stats.size = this._stats.inUse
+    this._state = PoolState.DRAINED
+  }
+
+  /**
+   * 缩减池到指定大小
+   * 仅移除空闲列表末尾的对象，使用中的对象不受影响
+   * @param {number} targetSize - 目标大小（空闲+使用中总数）
+   * @returns {void}
+   */
+  shrink(targetSize) {
+    if (this._state === PoolState.DESTROYED) return
+    if (typeof targetSize !== 'number' || targetSize < 0) return
+
+    while (this._freeList.length > 0 && this._stats.size > targetSize) {
+      this._freeList.pop()
+      this._stats.size--
+      this._stats.available--
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // 统计
+  // --------------------------------------------------------------------------
+
+  /**
+   * 获取统计信息
+   * 返回统计信息的浅拷贝，避免外部修改内部状态
+   * @returns {Object} 统计信息对象
+   */
+  getStats() {
+    return { ...this._stats }
+  }
+
+  // --------------------------------------------------------------------------
+  // 销毁
+  // --------------------------------------------------------------------------
+
+  /**
+   * 销毁对象池
+   * 清空所有列表和集合，释放引用，状态标记为 DESTROYED
+   * 使用中的对象不会被自动释放（由调用方负责）
+   * @returns {void}
+   */
+  destroy() {
+    if (this._state === PoolState.DESTROYED) return
+
+    this._freeList.length = 0
+    this._inUse.clear()
+    this._stats.size = 0
+    this._stats.available = 0
+    this._stats.inUse = 0
+    this._state = PoolState.DESTROYED
+
+    // 释放函数引用
+    this._create = null
+    this._reset = null
+    this._validate = null
+    this._onExhausted = null
+  }
+}
+
+export { ObjectPool }

package/src/core/PoolManager/PoolManager.js

@@ -0,0 +1,253 @@
+// ============================================================================
+// Nimbus2D - 对象池管理器
+// ----------------------------------------------------------------------------
+// 职责：
+//   提供通用对象池注册和管理能力。采用池注册表模式——PoolManager
+//   不预知任何对象类型，插件通过 register() 注册自己的对象池，
+//   通过 unregister() 注销。
+//
+// 继承关系：
+//   EventEmitter → Subsystem → PoolManager
+//
+// 设计决策：
+//   - 池注册表模式：PoolManager 只管理注册/注销，不关心对象类型
+//   - register() 时自动为池设置耗尽回调（onExhausted），使 ObjectPool
+//     在耗尽时通过 PoolManager 广播事件
+//   - unregister() 时自动调用 pool.drain() 排空池
+//   - destroy() 时排空并注销所有池
+//   - 事件通过全局 EventBus 广播（pool:registered/pool:unregistered/pool:exhausted）
+//   - 在 PluginSystem 之前初始化，确保插件安装时池管理器已就绪
+// ============================================================================
+
+import { Subsystem } from '../../base/Subsystem.js'
+import { ObjectPool } from './ObjectPool.js'
+import { PoolError, PoolStateError } from './PoolTypes.js'
+import { validateDev, isNonEmptyString } from '../../utils/Validator.js'
+
+class PoolManager extends Subsystem {
+  // --------------------------------------------------------------------------
+  // 构造函数
+  // --------------------------------------------------------------------------
+
+  /**
+   * 构造函数
+   * @param {import('../../core/EventBus/EventBus.js').EventBus} eventBus - 全局事件总线
+   * @param {import('../../core/ConfigSystem/ConfigSystem.js').ConfigSystem} config - 配置系统
+   * @param {import('../../core/Logger/Logger.js').Logger|null} [logger=null] - 日志系统
+   */
+  constructor(eventBus, config, logger = null) {
+    super(eventBus, config, logger)
+
+    /** @type {Map<string, ObjectPool>|null} 池注册表（name → ObjectPool） */
+    this._pools = null
+
+    /** @type {Object} 统计信息 */
+    this._stats = null
+  }
+
+  // --------------------------------------------------------------------------
+  // Getter
+  // --------------------------------------------------------------------------
+
+  /**
+   * 子系统名称
+   * @type {string}
+   */
+  get name() {
+    return 'poolManager'
+  }
+
+  // --------------------------------------------------------------------------
+  // 池管理
+  // --------------------------------------------------------------------------
+
+  /**
+   * 注册对象池
+   * @param {string} name - 池名称（如 'collider'、'physicsBody'）
+   * @param {ObjectPool} pool - 对象池实例
+   * @returns {PoolManager} - this（链式调用）
+   * @throws {PoolError} 名称已存在、池已销毁或参数无效
+   */
+  register(name, pool) {
+    // 已销毁检查
+    if (this.isDestroyed) {
+      throw new PoolError('PoolManager 已销毁，无法注册对象池')
+    }
+
+    // 开发模式：初始化状态守卫（PoolManager 必须先初始化才能注册对象池）
+    validateDev(this._config, this.isInitialized, 'PoolManager 尚未初始化，无法注册对象池', PoolStateError)
+
+    // 开发模式：完整参数校验
+    validateDev(this._config, isNonEmptyString(name), '池名称必须是非空字符串', PoolError)
+    validateDev(this._config, pool && typeof pool.acquire === 'function', 'pool 必须是 ObjectPool 实例', PoolError)
+
+    // 生产模式：仅检查 name 存在性
+    if (!name) {
+      throw new PoolError('池名称不能为空')
+    }
+
+    if (this._pools.has(name)) {
+      throw new PoolError(`对象池 '${name}' 已存在`)
+    }
+
+    // 设置池耗尽回调，使 ObjectPool 在耗尽时通过 PoolManager 广播事件
+    if (!pool._onExhausted) {
+      pool._onExhausted = (poolName, maxSize) => {
+        this._eventBus.emit('pool:exhausted', { name: poolName, maxSize })
+      }
+    }
+
+    this._pools.set(name, pool)
+    this._stats.totalRegistered++
+    this._eventBus.emit('pool:registered', { name, pool })
+
+    this._logger.debug('PoolManager.register', `对象池 '${name}' 已注册`)
+    return this
+  }
+
+  /**
+   * 注销对象池
+   * 注销时默认调用 pool.drain() 排空池中空闲对象。
+   * 若 options.destroy 为 true，则额外调用 pool.destroy() 彻底销毁池对象，
+   * 释放内部函数引用和统计信息，防止内存泄漏。
+   *
+   * @param {string} name - 池名称
+   * @param {Object} [options={}] - 注销选项
+   * @param {boolean} [options.destroy=true] - 是否彻底销毁池对象（默认 true）
+   *                                           true: drain() + destroy()，彻底释放
+   *                                           false: 仅 drain()，保留池对象供复用
+   * @returns {boolean} - 是否注销成功（池不存在时返回 false）
+   */
+  unregister(name, options = {}) {
+    // 已销毁检查
+    if (this.isDestroyed) return false
+
+    if (!this._pools.has(name)) return false
+
+    // 参数容错：options 为 null 时使用空对象
+    /** @type {Object} 安全的 options 对象 */
+    const safeOptions = options || {}
+    /** @type {boolean} 是否彻底销毁池对象（默认 true） */
+    const shouldDestroy = safeOptions.destroy !== false
+
+    const pool = this._pools.get(name)
+    pool.drain()
+    if (shouldDestroy) {
+      // 彻底销毁池对象，释放内部函数引用和统计信息
+      pool.destroy()
+    }
+    this._pools.delete(name)
+    this._eventBus.emit('pool:unregistered', { name })
+
+    this._logger.debug('PoolManager.unregister', `对象池 '${name}' 已注销${shouldDestroy ? '（已销毁）' : '（仅排空）'}`)
+    return true
+  }
+
+  /**
+   * 获取对象池
+   * @param {string} name - 池名称
+   * @returns {ObjectPool|undefined} 对象池实例，不存在时返回 undefined
+   */
+  get(name) {
+    if (!this._pools) return undefined
+    return this._pools.get(name)
+  }
+
+  /**
+   * 检查池是否存在
+   * @param {string} name - 池名称
+   * @returns {boolean}
+   */
+  has(name) {
+    if (!this._pools) return false
+    return this._pools.has(name)
+  }
+
+  /**
+   * 列出所有已注册的池名称
+   * @returns {string[]}
+   */
+  list() {
+    if (!this._pools) return []
+    return Array.from(this._pools.keys())
+  }
+
+  // --------------------------------------------------------------------------
+  // 统计
+  // --------------------------------------------------------------------------
+
+  /**
+   * 获取所有池的统计信息
+   * @returns {Object} 包含 totalRegistered 和各池统计的对象
+   */
+  getStats() {
+    if (!this._pools) {
+      return { totalRegistered: 0, pools: {} }
+    }
+
+    const stats = {}
+    for (const [name, pool] of this._pools) {
+      stats[name] = pool.getStats()
+    }
+    return {
+      totalRegistered: this._pools.size,
+      pools: stats
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // 生命周期（继承自 Subsystem）
+  // --------------------------------------------------------------------------
+
+  /**
+   * 初始化对象池管理器
+   * 创建池注册表和统计信息
+   * @returns {Promise<void>}
+   */
+  async initialize() {
+    await super.initialize()
+
+    this._pools = new Map()
+    this._stats = { totalRegistered: 0 }
+
+    this._logger.info('PoolManager.initialize', '对象池管理器已初始化')
+  }
+
+  /**
+   * 每帧更新
+   * 池操作由 acquire/release 同步完成，无需每帧逻辑
+   * @param {number} delta - 距上一帧的时间增量（秒）
+   * @returns {void}
+   */
+  update(delta) {
+    // 空实现——池操作由 acquire/release 同步完成
+  }
+
+  /**
+   * 销毁对象池管理器
+   * 排空并注销所有已注册的池
+   * @returns {Promise<void>}
+   */
+  async destroy() {
+    if (this.isDestroyed) return
+
+    // 排空并销毁所有已注册的池
+    if (this._pools) {
+      for (const [name, pool] of this._pools) {
+        pool.drain()
+        pool.destroy()
+        this._eventBus.emit('pool:unregistered', { name })
+      }
+      this._pools.clear()
+    }
+
+    this._pools = null
+    this._stats = null
+
+    this._logger.info('PoolManager.destroy', '对象池管理器已销毁')
+
+    await super.destroy()
+  }
+}
+
+export { PoolManager }

package/src/core/PoolManager/PoolTypes.js

@@ -0,0 +1,92 @@
+// ============================================================================
+// Nimbus2D - 对象池类型定义
+// ----------------------------------------------------------------------------
+// 定义对象池模块的枚举类型和错误类。
+//
+// 包含：
+//   - PoolState：对象池状态枚举
+//   - PoolError：对象池错误基类（继承 NimbusError）
+//   - PoolStateError：对象池状态错误
+//   - PoolExhaustedError：对象池已满错误
+// ============================================================================
+
+import { NimbusError } from '../../errors/NimbusError.js'
+
+// ----------------------------------------------------------------------------
+// 枚举
+// ----------------------------------------------------------------------------
+
+/**
+ * 对象池状态枚举
+ * @enum {string}
+ */
+const PoolState = {
+  /** 正常运行 */
+  ACTIVE: 'ACTIVE',
+  /** 已排空 */
+  DRAINED: 'DRAINED',
+  /** 已销毁 */
+  DESTROYED: 'DESTROYED'
+}
+
+// ----------------------------------------------------------------------------
+// 错误类
+// ----------------------------------------------------------------------------
+
+/**
+ * 对象池错误基类
+ * @extends NimbusError
+ */
+class PoolError extends NimbusError {
+  /**
+   * 构造函数
+   * @param {string} message - 错误信息
+   * @param {string} [code='POOL_ERROR'] - 错误码
+   * @param {Error|null} [cause=null] - 原始错误
+   */
+  constructor(message, code = 'POOL_ERROR', cause = null) {
+    super(message, code, 'PoolManager', cause)
+  }
+}
+
+/**
+ * 对象池状态错误
+ * 当对处于无效状态的对象池执行操作时抛出
+ * @extends PoolError
+ */
+class PoolStateError extends PoolError {
+  /**
+   * 构造函数
+   * @param {string} message - 错误信息
+   */
+  constructor(message) {
+    super(message, 'POOL_STATE_ERROR')
+  }
+}
+
+/**
+ * 对象池已满错误
+ * 当 acquire() 时池已达最大容量且无可用对象时抛出
+ * @extends PoolError
+ */
+class PoolExhaustedError extends PoolError {
+  /**
+   * 构造函数
+   * @param {string} poolName - 池名称
+   * @param {number} maxSize - 最大容量
+   */
+  constructor(poolName, maxSize) {
+    super(`对象池 '${poolName}' 已满（maxSize=${maxSize}）`, 'POOL_EXHAUSTED')
+    /** @type {string} 池名称 */
+    this.poolName = poolName
+    /** @type {number} 最大容量 */
+    this.maxSize = maxSize
+  }
+}
+
+export {
+  PoolState,
+  PoolError,
+  PoolStateError,
+  PoolExhaustedError
+}

package/src/core/PoolManager/index.js

@@ -0,0 +1,15 @@
+// ============================================================================
+// Nimbus2D - 对象池模块入口
+// ----------------------------------------------------------------------------
+// 统一导出 PoolManager 模块的所有公开类、枚举和错误类。
+// ============================================================================
+
+export { PoolManager } from './PoolManager.js'
+export { ObjectPool } from './ObjectPool.js'
+export {
+  PoolState,
+  PoolError,
+  PoolStateError,
+  PoolExhaustedError
+} from './PoolTypes.js'
+export { PoolDefaultConfig } from './DefaultConfig.js'