strml / async-limiter

A minimal library for throttling async concurrency.

Async-Limiter

A module for limiting concurrent asynchronous actions in flight. Forked from queue.

This module exports a class Limiter that implements some of the Array API. Pass async functions (ones that accept a callback or return a promise) to an instance's additive array methods.

Motivation

Certain functions, like zlib, have undesirable behavior when run at infinite concurrency.

In this case, it is actually faster, and takes far less memory, to limit concurrency.

This module should do the absolute minimum work necessary to queue up functions. PRs are welcome that would make this module faster or lighter, but new functionality is not desired.

Style should confirm to nodejs/node style.

Example

var Limiter = require('async-limiter');

var t = new Limiter({ concurrency: 2 });
var results = [];

// add jobs using the familiar Array API
t.push(function(cb) {
  results.push('two');
  cb();
});

t.push(
  function(cb) {
    results.push('four');
    cb();
  },
  function(cb) {
    results.push('five');
    cb();
  }
);

t.unshift(function(cb) {
  results.push('one');
  cb();
});

t.splice(2, 0, function(cb) {
  results.push('three');
  cb();
});

// Jobs run automatically on the next tick.
// If you want a callback when all are done, call 'onDone()'.
t.onDone(function() {
  console.log('all done:', results);
});

Zlib Example

const zlib = require('zlib');
const Limiter = require('async-limiter');

const message = { some: 'data' };
const payload = new Buffer(JSON.stringify(message));

// Try with different concurrency values to see how this actually
// slows significantly with higher concurrency!
//
// 5:        1398.607ms
// 10:       1375.668ms
// Infinity: 4423.300ms
//
const t = new Limiter({ concurrency: 5 });
function deflate(payload, cb) {
  t.push(function(done) {
    zlib.deflate(payload, function(err, buffer) {
      done();
      cb(err, buffer);
    });
  });
}

console.time('deflate');
for (let i = 0; i < 30000; ++i) {
  deflate(payload, function(err, buffer) {});
}
t.onDone(function() {
  console.timeEnd('deflate');
});

Install

npm install async-limiter

Test

npm test

API

var t = new Limiter([opts])

Constructor. opts may contain inital values for:

• t.concurrency

Instance methods

t.onDone(fn)

fn will be called once and only once, when the queue is empty. If the queue is empty on the next tick, onDone() will be called.

Instance methods mixed in from Array

Mozilla has docs on how these methods work here.

t.push(element1, ..., elementN)

t.unshift(element1, ..., elementN)

t.splice(index , howMany[, element1[, ...[, elementN]]])

On the next tick, job processing will start.

Properties

t.concurrency

Max number of jobs the queue should process concurrently, defaults to Infinity.

t.length

Jobs pending + jobs to process (readonly).

async-limiter's Issues

The module as conveyed by npm seems oddly huge

While the index.js file is an amazing 1234 bytes (even if that's with some comments to get it there. Love it), it looks like the npm-hosted version of this library is fifty times that size, which is... probably unnecessary?

Looking at what it serves, it contains a coverage dir, which probably comes from running coverage tests without having added coverage to the .npmignore file at the time it got published.

Would it be possible to run a new npm version patch and git push master --tags + npm publish to get the lean version on npm instead?

Example does not work

npm run example

produces the following error:

TypeError: t.start is not a function