ardus

The mother of all profilers

npm install ardus
26 downloads in the last week
27 downloads in the last month

Ardus is still under development, so be careful. There is at least one known issue that could bite you.

You've been warned...

pinch

Overview

Ardus is a module that provides easy access to helpful functionality. There are currently four types of functionality exposed by Ardus:

  • Collections - Provide a consistent API to collections of useful objects
  • Decorators - Wrap functions and methods with valuable behavior
  • Globals - Provide a simple way to apply decorators to all compiled code
  • Helpers - functions that make life easier

Collections

There are currently two types of collections:

  • Profiles - All the data collected during a profiling run
  • Hashes - A key-value collection of hash values and their associated functions

These collections are currently used only for profiling. They've been pulled out in case they can be used anywhere else.

Decorators

This is Ardus' meat & potatoes. Decorators are simply functions that wrap (or decorate) other functions.

An example of a decorator is:

function decorate (fn) {
  return function () {
    console.log('Calling ' + fn.name);

    fn.apply(this, arguments);

    console.log(fn.name + ' completed');   
  };
}

function foo() {
  console.log("I'm running!");
}

var decorated = decorate(foo);

decorated();

Executing the above code would produce:

Calling foo
I'm running!
foo completed

There are currently two decorators:

  • Profiler - Records runtime execution information for decorated functions
  • Require - Wraps code loaded via node's require statement in a profiler decorator

Globals

Globals simply apply a decorator (or multiple decorators) to all compiled code.

Ardus currently one global: the global profiler.

Core node code doesn't get wrapped via globals

It's important to note that core node code does not get decorated when using a global. This is because the core node code is compiled prior to the global's compilation, and therefore can't be decorated. To decorate core node code, please use the require decorator.

Helpers

Helpers are basic utility functions. They exist solely to make life easier for you.

There are currently three helpers:

  • sha1 - The hashing algorithm used by the Hashes collection
  • summary - A human readable version of the output from a run of the profiler decorator
  • uuid - A Universally Unique ID generator for functions

Usage

Ardus has singular and pluralized methods for accessing all of the above-specified functionality.

For example, to get the profiler decorator:

var profile = require('ardus').decorator('profiler');

Typing: less is more

There is a shortcut for accessing decorators:

var profile = require('ardus').profiler;

Pluralized methods

The pluralized method works as follows:

var decorators = require('ardus').decorators('profiler', 'require');

The above would return an object literal who's properties are the specified decorators:

decorators.profiler // The profiler decorator
decorators.require  // The require decorator

A complete example

var ardus      = require('ardus'),
    decorators = ardus.decorators('profiler', 'require'),
    profiled   = decorators.profiler(function test () { console.log('This is a ' + this.name) }),
    my         = decorators.require('path');

var thereYouAre = my.path.resolve('.');

console.log('Where are you? ' + thereYouAre);

profiled();

// We hook into the process exit event to make sure all callbacks have completed
process.on('exit', function() {
    ardus.helper('summary').generate();
});

Reporting issues

I know you'll find issues, report them here. KTHX

Contributing

If there's anything you want to add/change, please feel free!

Simply:

  • Fork Ardus
  • Create a topic local branch - git checkout -b topic_branch
  • Push to your local branch - git push origin topic_branch
  • Create a pull request: github.com/USERNAME/Ardus/pull/new/master
  • Sing, drink, and be happy

License

Ardus is Copyright © 2012 Bryan Maynard. It is free software, and may be redistributed under the terms specified in the MIT LICENSE file.

npm loves you