resource-puddle

Reference counted resource management with batched garbage collection.

Open a resource by id and release it when you are done. A resource is opened once and shared between everyone who opens it — open and release are synchronous and just move a ref counter. Once no one is holding a resource any more it goes idle, and idle resources are garbage collected together on an interval (after staying idle for gcIdleTicks ticks).

npm install resource-puddle

Usage

const ResourcePuddle = require('resource-puddle')

const rooms = new ResourcePuddle({
  open: (id) => openMyThing(id), // open a new resource (sync)
  gc: async (resources) => {
    // close all the idle resources passed in
    for (const r of resources) await r.close()
  },
  gcInterval: 5000
})

const room = rooms.open('foo') // opens 'foo', refs = 1
const same = rooms.open('foo') // noop, same resource, refs = 2

rooms.release('foo') // refs = 1
rooms.release('foo') // refs = 0, goes idle and gets gc'ed on a later tick

await rooms.destroy() // stop the gc timer and gc everything that is left

API

const pool = new ResourcePuddle(options)

Options include:

{
  // Open a resource for an id. Called once per id, receives the extra args
  // passed to pool.open(id, ...args). Whatever it returns is the resource.
  // Synchronous - if your resource needs async setup, return something with
  // its own ready()/open() and await that yourself.
  open (id, ...args) {},
  // Close a batch of idle resources. Called on each gc tick with all the
  // resources that have been idle long enough to collect.
  gc (resources) {},
  // How often to run the garbage collector, in ms. Set to 0 to disable the
  // timer and only gc manually. Defaults to 5000.
  gcInterval: 5000,
  // How many consecutive gc ticks a resource must stay idle before it is
  // collected. Reset to 0 whenever it is reopened. Defaults to 4.
  gcIdleTicks: 4
}

const resource = pool.open(id, ...args)

Open a resource for id, incrementing its ref count, and return it synchronously. The first call for an id calls the open hook with (id, ...args); subsequent calls return the same resource and ignore the extra args. Opening an idle resource revives it and resets its idle counter.

pool.release(id)

Decrement the ref count for id. When it reaches zero the resource goes idle and becomes eligible for garbage collection once it has stayed idle for gcIdleTicks ticks.

Throws if the id is not open or has already been fully released.

await pool.gc()

Run the garbage collector now. Bumps the idle counter of every idle resource, collects the ones that have reached gcIdleTicks, removes them from the pool, and passes them to the gc hook as a single batch. Runs automatically every gcInterval ms.

pool.pauseGC()

Stop the automatic gc timer. Resources still ref count and go idle, they just won't be collected until gc is resumed (or gc() is called manually).

pool.resumeGC()

Restart the automatic gc timer after a pauseGC().

await pool.destroy()

Stop the gc timer and garbage collect everything that is left, regardless of ref count.

pool.size

Number of resources currently tracked.

pool.idle

Number of resources currently idle (released, awaiting collection).

License

Apache-2.0