nbqueue v0.0.5

nbqueue

super simple queue module for executing async functions in node.js. nbqueue was created as a module for nodebee, a pure javascript database.

installation

npm install nbqueue

uses

limiting the number of functions being executed

when accessing large amounts of files asynchronously, bad things can happen. for example, take a directory with 20,000 files in it and try accessing them all at once.

with nbqueue you can set the maxProcesses to a sane amount, like 100, and it will execute a maximum of 100 functions at a time. functions added after the limit has been reached will execute as the previous functions finish up.

this is also crucial for maintaining a sane level of forked child processes.

var fs = require( 'fs' )

var Queue = require( 'nbqueue' )

fs.readdir( directory, function ( err, files )
	{
		// set maxProcesses to 100
		var queue = new Queue( 100 )

		files.forEach( function ( file )
			{
				queue.add( function ( next )
					{
						fs.readFile( file, function ( err, data )
							{
								next( err, data )
							}
						)

						// because next takes the same arguments as the readFile callback, you could do
						// fs.readFile( file, next )
					}
				)
			}
		)

		queue.done( function ( err, results )
			{
				if ( err )
				{
					// if there were errors, they will be in an array
					console.log( err )
				}

				// results contains an array of the results passed to next()
				console.log( results )
			}
		)
	}
)

executing async functions in order

setting maxProcesses to 1 will ensure only 1 function can be executed at a time.

queues within queues

queue up multiple sets of async functions, and let a the master queue know when they're all finished. here's a not very useful example:

var masterQueue = new Queue()

masterQueue.add( function ( nextMaster )
	{
		FS.readdir( '/path/to/directory1', function ( err, files )
			{
				if ( err )
				{
					return nextMaster( err )
				}

				var queue1 = new Queue( 50 )

				files.forEach( function ( file )
					{
						queue1.add( function ( next )
							{
								// do some other stuff here

								next( null, file )
							}
						)
					}
				)

				queue1.done( function ( err, results )
					{
						nextMaster( err, results )
					}
				)
			}
		)
	}
)

masterQueue.add( function ( nextMaster )
	{
		FS.readdir( '/path/to/directory2', function ( err, files )
			{
				if ( err )
				{
					return nextMaster( err )
				}

				var queue2 = new Queue( 50 )

				files.forEach( function ( file )
					{
						queue2.add( function ( next )
							{
								// do some other stuff here

								next( null, file )
							}
						)
					}
				)

				queue2.done( function ( err, results )
					{
						nextMaster( err, results )
					}
				)
			}
		)
	}
)

masterQueue.done( function ( err, results )
	{
		if ( err )
		{
			return console.log( err )
		}

		// results contains the filenames from both directories
		console.log( results )
	}
)