Usage

`javascript
var timeit = require( '@stdlib/utils-timeit' );
`

#### timeit( code, \[options,] clbk )

Times a snippet.

`javascript
var code = 'var x = Math.pow( Math.random(), 3 );';
code += 'if ( x !== x ) {';
code += 'throw new Error( \'Something went wrong.\' );';
code += '}';

timeit( code, done );

function done( error, results ) {
if ( error ) {
throw error;
}
console.dir( results );
/* e.g., =>
{
'iterations': 1000000,
'repeats': 3,
'min': [0,135734733], // [seconds,nanoseconds]
'elapsed': 0.135734733, // seconds
'rate': 7367311.062526641, // iterations/second
'times': [ // raw timing results
[0,145641393],
[0,135734733],
[0,140462721]
]
}
*/
}
`

The function supports the following options:

- before: setup code. Default: "".
- after: cleanup code. Default: "".
- iterations: number of iterations. If null, the number of iterations is determined by trying successive powers of 10 until the total time is at least 0.1 seconds. Default: 1e6.
- repeats: number of repeats. Default: 3.
- asynchronous: boolean indicating whether a snippet is asynchronous. Default: false.

To perform any setup or initialization, provide setup code.

`javascript
var setup = 'var randu = require( \'@stdlib/random-base-randu\' );';
setup += 'var pow = require( \'@stdlib/math-base-special-pow\' );';

var code = 'var x = pow( randu(), 3 );';
code += 'if ( x !== x ) {';
code += 'throw new Error( \'Something went wrong.\' );';
code += '}';

var opts = {
'before': setup
};

timeit( code, opts, done );

function done( error, results ) {
if ( error ) {
throw error;
}
console.dir( results );
}
`

To perform any cleanup, provide cleanup code.

`javascript
var setup = 'var randu = require( \'@stdlib/random-base-randu\' );';
setup += 'var hypot = require( \'@stdlib/math-base-special-hypot\' );';

var code = 'var h = hypot( randu()10, randu()10 );';
code += 'if ( h < 0 || h > 200 ) {';
code += 'throw new Error( \'Something went wrong.\' );';
code += '}';

var cleanup = 'if ( h !== h ) {';
cleanup += 'throw new Error( \'Something went wrong.\' );';
cleanup += '}';

var opts = {
'before': setup,
'after': cleanup
};

timeit( code, opts, done );

function done( error, results ) {
if ( error ) {
throw error;
}
console.dir( results );
}
`

To time an asynchronous snippet, set the asynchronous option to true.

`javascript
var code = 'var x = Math.pow( Math.random(), 3 );';
code += 'if ( x !== x ) {';
code += 'var err = new Error( \'Something went wrong.\' );';
code += 'next( err );';
code += '}';
code += 'process.nextTick( next );';

var opts = {
'iterations': 1e2,
'asynchronous': true
};

timeit( code, opts, done );

function done( error, results ) {
if ( error ) {
throw error;
}
console.dir( results );
}
`

If asynchronous is true, the implementation assumes that before, after, and code snippets are all asynchronous. Accordingly, these snippets should invoke a next( [error] ) callback once complete. For example, given the following snippet,

`javascript
setTimeout( done, 0 );

function done( error ) {
if ( error ) {
return next( error );
}
next();
}
`

the implementation wraps the snippet within a function having the following signature

`javascript
function wrapped( state, next ) {
setTimeout( done, 0 );

function done( error ) {
if ( error ) {
return next( error );
}
next();
}
}
`

The state parameter is simply an empty {} which allows the before, after, and code snippets to share state.

`javascript
function before( state, next ) {
state.counter = 0;
}

function code( state, next ) {
setTimeout( done, 0 );

function done( error ) {
if ( error ) {
return next( error );
}
state.counter += 1;
next();
}
}

function after( state, next ) {
var err;
if ( state.counter !== state.counter ) {
err = new Error( 'Something went wrong!' );
return next( err );
}
next();
}
`