extra-pool 0.1.1 → 0.1.3

package/lib/pool.js

@@ -75,7 +75,7 @@ class Pool {
         async function useItem(item) {
             if (item.cancelScheduledDeletion) {
                 item.cancelScheduledDeletion();
-                delete item.cancelScheduledDeletion;
+                item.cancelScheduledDeletion = undefined;
             }
             try {
                 return await item.instance.use(fn);

package/lib/pool.js.map

@@ -1 +1 @@
-{"version":3,"file":"pool.js","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pool.js","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "extra-pool",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "A library that helps you create object/thread/connection pools",
   "keywords": [
     "pool",
@@ -9,7 +9,8 @@
     "connection"
   ],
   "files": [
-    "lib"
+    "lib",
+    "src"
   ],
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -37,7 +38,6 @@
     }
   },
   "devDependencies": {
-    "@blackglory/jest-matchers": "^0.5.0",
     "@commitlint/cli": "^17.3.0",
     "@commitlint/config-conventional": "^17.3.0",
     "@types/jest": "^29.2.3",

package/src/index.ts

@@ -0,0 +1 @@
+export * from './pool'

package/src/instance.ts

@@ -0,0 +1,133 @@
+import { go, assert, Awaitable } from '@blackglory/prelude'
+import { Deferred } from 'extra-promise'
+import { ObservableFiniteStateMachine } from 'extra-fsm'
+import { firstValueFrom } from 'rxjs'
+import { filter } from 'rxjs/operators'
+
+export enum InstanceState {
+  Creating = 'creating'
+, Idle = 'idle'
+, Using = 'using'
+, Destroying = 'destroying'
+, Destroyed = 'destroyed'
+}
+
+type InstanceEvent =
+| 'created'
+| 'use'
+| 'idle'
+| 'destroy'
+| 'destroyed'
+
+const instanceSchema = {
+  [InstanceState.Creating]: {
+    created: InstanceState.Idle
+  }
+, [InstanceState.Idle]: {
+    use: InstanceState.Using
+  , destroy: InstanceState.Destroying
+  }
+, [InstanceState.Using]: {
+    idle: InstanceState.Idle
+  }
+, [InstanceState.Destroying]: {
+    destroyed: InstanceState.Destroyed
+  }
+, [InstanceState.Destroyed]: {}
+}
+
+export class Instance<T> {
+  private fsm: ObservableFiniteStateMachine<InstanceState, InstanceEvent>
+  private _users = 0
+  readonly _instance: Deferred<T>
+
+  get users(): number {
+    return this._users
+  }
+
+  constructor(
+    createInstance: () => Awaitable<T>
+  , private destroyInstance?: (value: T) => Awaitable<void>
+  ) {
+    this._instance = new Deferred<T>()
+    this.fsm = new ObservableFiniteStateMachine<InstanceState, InstanceEvent>(
+      instanceSchema
+    , InstanceState.Creating
+    )
+
+    go(async () => {
+      try {
+        const instance = await createInstance()
+        this.fsm.send('created')
+        this._instance.resolve(instance)
+      } catch (e) {
+        this._instance.reject(e)
+      }
+    })
+  }
+
+  async waitForCreated(): Promise<void> {
+    await this._instance
+  }
+
+  getState(): InstanceState {
+    return this.fsm.state
+  }
+
+  async use<U>(fn: (instance: T) => Awaitable<U>): Promise<U> {
+    // 不要尝试将此处的代码改编成switch管道, 很难正确编写.
+
+    assert(
+      this.fsm.state !== InstanceState.Destroying &&
+      this.fsm.state !== InstanceState.Destroyed
+    , 'The instance is not available'
+    )
+
+    this._users++
+
+    if (this.fsm.state === InstanceState.Creating) {
+      await this._instance
+    }
+
+    if (this.fsm.state === InstanceState.Idle) {
+      this.fsm.send('use')
+    }
+
+    assert(this.fsm.state === InstanceState.Using, 'The instance state should be using')
+    const instance = await this._instance
+    try {
+      const result = await fn(instance)
+      return result
+    } finally {
+      if ((--this._users) === 0) {
+        this.fsm.send('idle')
+      }
+    }
+  }
+
+  async destroy(): Promise<void> {
+    if (
+      this.fsm.state === InstanceState.Creating ||
+      this.fsm.state === InstanceState.Using
+    ) {
+      await firstValueFrom(
+        this.fsm.observeStateChanges().pipe(
+          filter(state => state.newState === InstanceState.Idle)
+        )
+      )
+    }
+
+    if (this.fsm.state === InstanceState.Idle) {
+      this.fsm.send('destroy')
+      // 如果destroyed过程报错, 则程序崩溃, 这是预期行为.
+      await this.destroyInstance?.(await this._instance)
+      this.fsm.send('destroyed')
+    } else if (this.fsm.state === InstanceState.Destroying) {
+      await firstValueFrom(
+        this.fsm.observeStateChanges().pipe(
+          filter(state => state.newState === InstanceState.Destroyed)
+        )
+      )
+    }
+  }
+}

package/src/pool.ts

@@ -0,0 +1,194 @@
+import { CustomError } from '@blackglory/errors'
+import { go, Awaitable } from '@blackglory/prelude'
+import { Queue } from '@blackglory/structures'
+import { FiniteStateMachine } from 'extra-fsm'
+import { Deferred } from 'extra-promise'
+import { toArray, filter } from 'iterable-operator'
+import { setTimeout } from 'extra-timers'
+import { Instance, InstanceState } from './instance'
+
+interface IPoolOptions<T> {
+  create: () => Awaitable<T>
+
+  /**
+   * 该函数用于销毁实例.
+   * 它是可选的, 有一些实例可能不需要销毁或不需要手动销毁.
+   */
+  destroy?: (value: T) => Awaitable<void>
+
+  /**
+   * 池中实例的最高数量, 默认为Infinity.
+   */
+  maxInstances?: number
+
+  /**
+   * 池中实例的最低数量, 默认为0.
+   * 注意, 非零值不意味着最低数量的实例会与池一同被创建,
+   * 该值的主要作用是防止空闲实例被全部销毁(导致下次使用时需要重新创建实例).
+   */
+  minInstances?: number
+
+  /**
+   * 空闲实例的存活时间(毫秒).
+   * 默认为0, 空闲实例会被立即销毁.
+   */
+  idleTimeout?: number
+
+  /**
+   * 每个实例的并发数.
+   * 默认为1, 每个实例只能同时有一个用户.
+   */
+  concurrencyPerInstance?: number
+}
+
+interface IPoolItem<T> {
+  instance: Instance<T>
+
+  /**
+   * 空闲实例会在idleTimeout之后被删除, 该函数用于取消预定的删除操作.
+   */
+  cancelScheduledDeletion?: () => void
+}
+
+enum PoolState {
+  Running = 'running'
+, Destroying = 'destroying'
+, Destroyed = 'destroyed'
+}
+
+type PoolEvent =
+| 'destroy'
+| 'destroyed'
+
+const poolSchema = {
+  [PoolState.Running]: {
+    destroy: PoolState.Destroying
+  }
+, [PoolState.Destroying]: {
+    destroyed: PoolState.Destroyed
+  }
+, [PoolState.Destroyed]: {}
+}
+
+export class Pool<T> {
+  private createInstance: () => Awaitable<T>
+  private destroyInstance?: (value: T) => Awaitable<void>
+  private fsm = new FiniteStateMachine<PoolState, PoolEvent>(
+    poolSchema
+  , PoolState.Running
+  )
+  private waitingUsers: Queue<Deferred<IPoolItem<T>>> = new Queue()
+  private items: Set<IPoolItem<T>> = new Set()
+  private maxInstances: number
+  private minInstances: number
+  private idleTimeout: number
+  private concurrencyPerInstance: number
+
+  get size(): number {
+    return this.items.size
+  }
+
+  constructor(options: IPoolOptions<T>) {
+    this.createInstance = options.create
+    this.destroyInstance = options.destroy
+    this.maxInstances = options.maxInstances ?? Infinity
+    this.minInstances = options.minInstances ?? 0
+    this.idleTimeout = options.idleTimeout ?? 0
+    this.concurrencyPerInstance = options.concurrencyPerInstance ?? 1
+  }
+
+  /**
+   * 如果所有实例都不空闲, 该函数会通过返回Promise来阻塞使用者, 直到有空闲的实例.
+   * 函数的使用者应该尊重阻塞, 否则会意外制造大量非必要的Promise.
+   */
+  async use<U>(fn: (instance: T) => Awaitable<U>): Promise<U> {
+    const self = this
+
+    const item = go(() => {
+      const candidateItems = toArray(filter(
+        this.items
+      , item => item.instance.users < this.concurrencyPerInstance
+      ))
+
+      if (candidateItems.length) {
+        return candidateItems.reduce((previous, current) => {
+          if (current.instance.users < previous.instance.users) {
+            return current
+          } else {
+            return previous
+          }
+        })
+      }
+    })
+
+    if (item) {
+      return await useItem(item)
+    } else {
+      if (this.items.size < this.maxInstances) {
+        const instance = new Instance(this.createInstance, this.destroyInstance)
+        const item: IPoolItem<T> = { instance }
+        this.items.add(item)
+        return await useItem(item)
+      } else {
+        const waitingUser = new Deferred<IPoolItem<T>>()
+        this.waitingUsers.enqueue(waitingUser)
+        const item = await waitingUser
+        return await useItem(item)
+      }
+    }
+
+    async function useItem(item: IPoolItem<T>): Promise<U> {
+      // 由于使用该实例, 取消其预定的删除动作.
+      if (item.cancelScheduledDeletion) {
+        item.cancelScheduledDeletion()
+        item.cancelScheduledDeletion = undefined
+      }
+
+      try {
+        return await item.instance.use(fn)
+      } finally {
+        const waitingUser = self.waitingUsers.dequeue()
+        if (waitingUser) {
+          waitingUser.resolve(item)
+        } else {
+          if (
+            item.instance.users === 0 &&
+            self.items.size > self.minInstances
+          ) {
+            if (self.idleTimeout > 0) {
+              item.cancelScheduledDeletion = setTimeout(
+                self.idleTimeout
+              , deleteInstance
+              )
+            } else {
+              await deleteInstance()
+            }
+          }
+        }
+      }
+
+      async function deleteInstance(): Promise<void> {
+        self.items.delete(item)
+        await item.instance.destroy()
+      }
+    }
+  }
+
+  async destroy(): Promise<void> {
+    this.fsm.send('destroy')
+
+    for (const item of this.items) {
+      await item.instance.destroy()
+    }
+    this.items.clear()
+
+    let deferred: Deferred<IPoolItem<T>> | undefined
+    while (deferred = this.waitingUsers.dequeue()) {
+      deferred.reject(new UnavailablePool())
+    }
+
+    this.fsm.send('destroyed')
+  }
+}
+
+export class UnavailablePool extends CustomError {}