NAME
    Tool::Bench - Tool Bench is a generic framework for running benchmarks.

SYNOPSIS
    Ok so I'm sure your asking your self, yet another benchmarking suit?
    Sure there are many others but this one is not specific to Perl. Think
    of Tool::Bench more as a jazzy version of the unix 'time' command it
    just happens to be written in perl. With 'time' you have a very simple
    wrap a clock around this command for one run. Tool::Bench goes a bit
    further by wrapping a clock around the execution of an number of
    CodeRef, run as many times as you want. Then because all these times are
    stored you can build reports from the results of all these runs.

    That said Tool::Bench is designed to just be the clock engine, you have
    to draw the line somewhere. So here's a quick example of usage.

      use Tool::Bench;
      my $bench = Tool::Bench->new;

      # simplest case: add a code ref with a name
      $bench->add_items( simple => sub{...} );

      # slightly more complex item: now with events
      $bench->add_items( complex => { startup  => sub{...},
                                      code     => sub{...},
                                      teardown => sub{...},
                                    },
                       );

      # add items can takes a hash so you can add more then one item
      $bench->add_items( name1 => sub{...}, 
                         name2 => { startup => sub{...},
                                    code    => sub{...},  
                                  },
                         name3 => sub{...},
                       );

      # now that your all set up, you'll want to run them
      # lets say that you want to run each item 3 times
      $bench->run(3);

      # now you've got a bunch of data stored off... lets do something with it.

      $bench->report(format => 'Text');

ATTRIBUTES
  items
    This is the store for all the items to be bench marked. When called
    directly you will get an arrayref of Item objects.

METHODS
  items_count
    Returns the count of the number of items currently stored.

  add_items
      $bench->add_items( $name => $coderef );
      $bench->add_items( $name => { startup  => $coderef,
                                    code     => $coderef,
                                    teardown => $coderef,
                                    #verify  => $coderef, # currently not implimented
                                  }
                         ...
                       );

    This method will take your input and build new Item objects and store
    them in the items stack. See Tool::Bench::Item for more info on the
    events.

    Returns items_count.

  run
    When you are done adding all your items, you'll want to run them. Run
    takes an int that refers to the number of times that you want to run
    each item, the default is 1.

      $bench->run; # fire off the run method of all known items in shuffled order
      $bench->run(3); # run all items 3 times, random order non-sequential runs

    Returns the number of times that it ran each item.

  report
    Lastly, once you've run the items, you'll likely want to mine them and
    build a report. The report method by default will return a Text report,
    though you can ask for other formats. The 'format' value is expected to
    be the last part of the class to generate the report.

      $bench->report(format => 'Text'); # uses Tool::Bench::Report::Text
      $bench->report(format => 'JSON'); # uses Tool::Bench::Report::JSON

    By using class names you can build your own report simply, see
    Tool::Bench::Report::Text for more info on how to build report types.

