Pool - Documentation

new Pool(factory, optionsopt, injectablesopt)

Source:

Pool.js, line 50

Example

const Pool = require('thingy-pool');
const factory = require('./myObjectFactory')

const options = { maxSize: 5 }
const pool = new Pool(factory, options)

async function fetchSomething() { // or const fetchSomething = async () => {
 const thingy = await pool.acquire()
 const result = await thingy.fetchSomething()
 pool.release(thingy)
 return result
}

fetchSomething().then(result => console.log(result)) // something
fetchSomething().then(result => console.log(result)) // something

Parameters:

Name	Type	Default	Description
`factory`	Factory.<T>		Factory used by the pool
`options`_opt	Partial.<Options>	`Options`	Options for the pool
`injectables.objectQueue`_opt	ObjectQueue.<PooledObject.<T>>	`new DoubleEndedQueue()`	Queue that stores the available pooled objects. See ObjectQueue for more info
`injectables.requestQueue`_opt	RequestQueue.<PoolRequest.<T>>	`new PriorityQueue()`	PriorityQueue that stores pending requests. See RequestQueue for more info
`injectables.getTimestamp`_opt	function	`Date.now`	Function used by the pool to get the current timestamp. Useful for testing. See Date.now()

Extends

EventEmitter

Methods

(async) acquire(optionsopt) → {Promise.<T>}

Source:

Pool.js, line 614

Request an object from the Pool. If no objects are available and the pool is below the maximum size, a new one will be created

Example

const thingy = await pool.acquire()

// With custom priority
const thingy = await pool.acquire({ priority: 5 })

// With custom timeout
const thingy = await pool.acquire({ timeoutInMs: 5000 })

// With custom priority and timeout
const thingy = await pool.acquire({ priority: 10, timeoutInMs: 1000 })

Parameters:

Name	Type	Default	Description
`options.priority`_opt	number	`0`	The priority for the request. The higher the number the higher the priority
`options.timeoutInMs`_opt	number \| null	`30000`	Time in milliseconds before the request times out

Returns:

Type: Promise.<T>

(async) clear() → {Promise.<void>}

Source:

Pool.js, line 631

Destroys all pooled objects that are currently available. Resolves after objects have been destroyed

Example

pool.getInfo() // { size: 5, available: 2, borrowed: 3, ...moreInfo }
await pool.clear()
pool.getInfo() // { size: 3, available: 0, borrowed: 3, ...moreInfo }

Returns:

Type: Promise.<void>

getInfo() → {PoolInfo}

Source:

Pool.js, line 667

Current pool object counts and state

Example

pool.getInfo().available // 2
// or
const { available, borrowed, size, state } = pool.getInfo()

Returns:

Type: PoolInfo

getOptions() → {Options}

Source:

Pool.js, line 694

Current pool options

Example

pool.getOptions().defaultTimeoutInMs // 30000
// or
const { maxSize, maxPendingRequests } = pool.getOptions()

Returns:

Type: Options

getSize() → {number}

Source:

Pool.js, line 704

Total number of objects in the pool. Includes objects being created and excludes objects being destroyed

Example

pool.getSize() // 3

Returns:

Type: number

getState() → {PoolState}

Source:

Pool.js, line 714

Current pool state as a string

Example

pool.getState() // 'STARTED'

Returns:

Type: PoolState

has(object) → {boolean}

Source:

Pool.js, line 725

Checks if the object is part of the pool

Example

pool.has(thingy) // true

Parameters:

Name	Type	Description
`object`	T	The object to check

Returns:

Type: boolean

isBorrowed(object) → {boolean}

Source:

Pool.js, line 736

Checks if the object is currently borrowed

Example

pool.isBorrowed(thingy) // true

Parameters:

Name	Type	Description
`object`	T	The object to check

Returns:

Type: boolean

(async) release(object) → {Promise.<void>}

Source:

Pool.js, line 754

Returns the object back to the pool for future use

Example

const thingy = await pool.acquire()
pool.getInfo() // { size: 5, available: 2, borrowed: 3, ...moreInfo }
const result = await thingy.doSomethingAsync()
await pool.release(thingy)
pool.getInfo() // { size: 5, available: 3, borrowed: 2, ...moreInfo }

Parameters:

Name	Type	Description
`object`	T	The object to return

Returns:

Type: Promise.<void>

(async) releaseAndDestroy(object) → {Promise.<void>}

Source:

Pool.js, line 779

Returns the object to the pool and destroys it

Example

const thingy = await pool.acquire()
pool.getInfo() // { size: 5, available: 2, borrowed: 3, ...moreInfo }
const result = await thingy.doSomethingAsync()
await pool.releaseAndDestroy(thingy)
pool.getInfo() // { size: 4, available: 2, borrowed: 2, ...moreInfo }

Parameters:

Name	Type	Description
`object`	T	The object to return and destroy

Returns:

Type: Promise.<void>

start() → {Promise.<void>}

Source:

Pool.js, line 797

Starts the pool

Example

await pool.start()
const thingy = await pool.acquire()

Returns:

Resolves after pool is started

Type: Promise.<void>

stop() → {Promise.<void>}

Source:

Pool.js, line 815

Stops the pool

Example

const thingy = await pool.acquire()
const finalResult = await thingy.doSomethingAsync()
pool.release(thingy)
pool.stop()

Returns:

Resolves after pool is stopped

Type: Promise.<void>

(async) use(callback, optionsopt) → {Promise.<any>}

Source:

Pool.js, line 836

Use a pooled object with a callback and release to object automatically

Example

const result = await pool.use(thingy => thingy.doSomethingAsync())

Parameters:

Name	Type	Default	Description
`callback`	function
`options.priority`_opt	number	`0`	The priority for the request. The higher the number the higher the priority
`options.timeoutInMs`_opt	number \| null	`30000`	Time in milliseconds before the request times out

Returns:

Result from callback

Type: Promise.<any>

Type Definitions

PoolInfo

Source:

Pool.js, line 641

Properties:

Name	Type	Description
`available`	number	Number of objects that are available for requests
`beingCreated`	number	Number of objects being created
`beingDestroyed`	number	Number of objects being destroyed. Not included in the total pool size
`beingValidated`	number	Number of objects being validated. The sum of beingValidatedForDispatch and beingValidatedForReturn
`beingValidatedForDispatch`	number	Number of objects being validated before attempting to dispatch to a request
`beingValidatedForReturn`	number	Number of objects being validated before being returned to available objects
`pendingRequests`	number	Number of requests waiting for an object
`borrowed`	number	Number of objects currently borrowed
`notBorrowed`	number	Number of objects not currently borrowed
`size`	number	Total number of objects in the pool. Includes objects being created and excludes objects being destroyed
`state`	string	The current pool state

Type:

Object

PoolState

Source:

constants/PoolStates.js, line 2

The possible states:

CREATED
STARTING
STARTED
SHUTTING_DOWN
STOPPED

Type:

"CREATED" | "STARTING" | "STARTED" | "SHUTTING_DOWN" | "STOPPED"

Events

factoryCreateError

Source:

Pool.js, line 395

An error occurred while trying to create an object. Likely an error from factory.create

Parameters:

Name	Type	Description
`error`	Error	The error that occurred

factoryDestroyError

Source:

Pool.js, line 424

An error occurred while trying to destroy an object. Likely an error from factory.destroy

Parameters:

Name	Type	Description
`error`	Error	The error that occurred

factoryValidateError

Source:

Pool.js, line 451

An error occurred while trying to validate an object. Likely an error from factory.validate

Parameters:

Name	Type	Description
`error`	Error	The error that occurred

poolDidStart

Source:

Pool.js, line 519

Pool has started and initial objects have been created to reach the minimum pool size

poolDidStop

Source:

Pool.js, line 546

Pool has stopped and all objects have been destroyed