Usage

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

timeit( code, [options,] clbk )

Times a snippet.

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.

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.

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.

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,

setTimeout( done, 0 );

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

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

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.

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();
}