hoaproject / bench

The Hoa\Bench library.

---

Hoa is a modular, extensible and structured set of PHP libraries.
Moreover, Hoa aims at being a bridge between industrial and research worlds.

Hoa\Bench

This library allows to analyze performance of algorithms or programs by placing some “marks” in the code. Furthermore, this library provides some DTrace programs.

Learn more.

Installation

With Composer, to include this library into your dependencies, you need to require hoa/bench:

$ composer require hoa/bench '~3.0'

For more installation procedures, please read the Source page.

Testing

Before running the test suites, the development dependencies must be installed:

$ composer install

Then, to run all the test suites:

$ vendor/bin/hoa test:run

For more information, please read the contributor guide.

Quick usage

We propose a quick overview of two usages: The library itself and one DTrace program.

Benchmark

All we have to do is to place different marks in the code. A mark can be started, paused, stopped and reset. The class Hoa\Bench\Bench proposes a quick statistic graph that could be helpful:

$bench = new Hoa\Bench\Bench();

// Start two marks: “one” and “two”.
$bench->one->start();
$bench->two->start();

usleep(50000);

// Stop the mark “two” and start the mark “three”.
$bench->two->stop();
$bench->three->start();

usleep(25000);

// Stop all marks.
$bench->three->stop();
$bench->one->stop();

// Print statistics.
echo $bench;

/**
 * Will output:
 *     __global__  ||||||||||||||||||||||||||||||||||||||||||||||||||||    77ms, 100.0%
 *     one         ||||||||||||||||||||||||||||||||||||||||||||||||||||    77ms,  99.8%
 *     two         ||||||||||||||||||||||||||||||||||                      51ms,  65.9%
 *     three       ||||||||||||||||||                                      26ms,  33.9%
 */

More operations are available, such as iterating over all marks, deleting a mark, filters marks etc.

DTrace

An interesting DTrace program is hoa://Library/Bench/Dtrace/Execution.d that shows the call trace, errors and exceptions during an execution. For example, if we consider the Dtrace.php file that contains the following code:

<?php

function f() { g(); h(); }
function g() { h();      }
function h() {           }

f();

Then, we can run DTrace like this:

$ exed=`hoa protocol:resolve hoa://Library/Bench/Dtrace/Execution.d`
$ sudo $exed -c "php Dtrace.php"
Request start
     2ms ➜ f()        …/Dtrace.php:007
    37ms   ➜ g()      …/Dtrace.php:003
    26ms     ➜ h()    …/Dtrace.php:004
    28ms     ← h()
    37ms   ← g()
    44ms   ➜ h()      …/Dtrace.php:003
    25ms   ← h()
    30ms ← f()
Request end

Another program shows statistics about an execution: Each function that has been called, how many times, how long the execution has taken etc.

Documentation

The hack book of Hoa\Bench contains detailed information about how to use this library and how it works.

To generate the documentation locally, execute the following commands:

$ composer require --dev hoa/devtools
$ vendor/bin/hoa devtools:documentation --open

More documentation can be found on the project's website: hoa-project.net.

Getting help

There are mainly two ways to get help:

• On the #hoaproject IRC channel,
• On the forum at users.hoa-project.net.

Contribution

Do you want to contribute? Thanks! A detailed contributor guide explains everything you need to know.

License

Hoa is under the New BSD License (BSD-3-Clause). Please, see LICENSE for details.

Related projects

The following projects are using this library:

• Symfony Bench Bundle, The Hoa\Bench Symfony 2 bundle.

bench's Issues

English documentation of #30

Write english documentation for #30

• new Bench methods

    /**
     * Pause all marks.
     *
     * @return  array
     */
    public function pause();

    /**
     * Resume all marks.
     *
     * @param   array  $runningMarks    The marks to resume.
     * @return  void
     */
    public function resume($runningMarks);

Include memory information when outputting Hoa\Bench.

This is a feature request. We're using Hoa\Bench to measure how slow we are for a number of things.

We manually also output PHP memory right at the bottom, as you can see here:

https://github.com/fruux/sabre-vobject/blob/master/bin/bench_freebusygenerator.php#L61

I was wondering if this could also be a good Hoa\Bench built-in feature =)

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

If the execution is < 1ms then global > 100 %

Sample :

use Hoa\Bench;


$tab = \SplFixedArray::fromArray(['Gg', 'est', 'le', 'plus', 'beau']);

$bench = new Bench();

$bench->one->start();

for($i=0;$i<$tab->count();$i++){

    echo $tab[$i];

}

$bench->one->stop();


$bench->two->start();

//le foreach

foreach($tab as $value){

    echo $value;
}

$bench->two->stop();


echo $bench;

Result :

global |||||||||||||||||||||||||||||||||||||||||||||||||||||| 0ms, 104.1%
one |||||||||||||||||||||| 0ms, 43.2%
two |||||||||| 0ms, 19.1%

Doc: broken link

This library allows to analyze performance of algorithms or programs by placing some “marks” in the code. Furthermore, this library proposes some >>>>> DTrace <<<<< programs.

DTrace is a link to http://opensolaris.org/os/community/dtrace/ which no longer works

Rename isRunning to isStarted in Bench.php

Renamming property and method isRunning to isStarted should be more explicit.
For a while isRunning() should be depricated.

cf https://github.com/hoaproject/Bench/pull/30/files#r36389896

French documentation of #30

Write french documentation for #30

• new Bench methods

    /**
     * Pause all marks.
     *
     * @return  array
     */
    public function pause();

    /**
     * Resume all marks.
     *
     * @param   array  $runningMarks    The marks to resume.
     * @return  void
     */
    public function resume($runningMarks);

Update the documentation, related to #5

#5