cspray/precision-stopwatch

A small library for keeping track of the duration between precise points in time.

0.2.0 2023-05-13 18:36 UTC

Requires

• php: ^8.1

Requires (Dev)

• cspray/phinal: ^2.0
• phpunit/phpunit: ^10.1
• vimeo/psalm: ^5.11

MIT

• Charles Sprayberry

README

Precisely time PHP scripts and code, down to the nanosecond, by utilizing the hrtime function.

Installing

Composer is the only supported method for installing this library.

composer require cspray/precision-stopwatch

Usage Guide

Using the provided functionality involves the following steps:

1. Create a new instance of Cspray\PrecisionStopwatch\Stopwatch
2. Call Stopwatch::start()
3. Do the thing that you're timing!
4. Call Stopwatch::mark() (optional, see Marking Time)
5. Call Stopwatch::stop()
6. Retrieve information about how long the Stopwatch ran with Cspray\PrecisionStopwatch\Metrics

The code examples below can be executed by cloning this repo and running the scripts available in ./examples.

Basic Usage

<?php declare(strict_types=1);

use Cspray\PrecisionStopwatch\Stopwatch;

require_once __DIR__ . '/vendor/autoload.php';

$stopwatch = new Stopwatch();

$stopwatch->start();

sleep(3);

$metrics = $stopwatch->stop();

echo 'Duration (ns): ', $metrics->getTotalDuration()->timeTakenInNanoseconds(), PHP_EOL;
echo 'Duration (ms): ', $metrics->getTotalDuration()->timeTakenInMilliseconds(), PHP_EOL;

If you execute this example you should see output similar to the following:

% > php ./examples/usage-without-marks.php
Total time taken (ns): 1000584755
Total time taken (ms): 1000.584755

Marking Time

Marking time allows you to retrieve the duration that a Stopwatch has ran to a certain point, while allowing the Stopwatch to continue running. Calling Stopwatch::mark() will return a Cspray\PrecisionStopwatch\Marker instance. In addition to retrieving the duration up to a certain point, available on the Marker instance, you can retrieve the duration between markers with the Metrics returned from Stopwatch::stop().

<?php declare(strict_types=1);

use Cspray\PrecisionStopwatch\Stopwatch;

require_once dirname(__DIR__) . '/vendor/autoload.php';

// .75 seconds
$sleepTime = 750_000;

$stopwatch = new Stopwatch();

$stopwatch->start();

usleep($sleepTime);

$mark1 = $stopwatch->mark();

usleep($sleepTime);

$mark2 = $stopwatch->mark();

usleep($sleepTime);

$mark3 = $stopwatch->mark();

usleep($sleepTime);

$metrics = $stopwatch->stop();

echo 'Total time taken (ns): ', $metrics->getTotalDuration()->timeTakenInNanoseconds(), PHP_EOL;
echo 'Total time taken (ms): ', $metrics->getTotalDuration()->timeTakenInMilliseconds(), PHP_EOL;

echo PHP_EOL;

$between1And3 = $metrics->getDurationBetweenMarkers($mark1, $mark3);
echo 'Time take between 1st and 3rd mark (ns): ', $between1And3->timeTakenInNanoseconds(), PHP_EOL;
echo 'Time take between 1st and 3rd mark (ms): ', $between1And3->timeTakenInMilliseconds(), PHP_EOL;

echo PHP_EOL;

echo 'Time taken up to 3rd mark (ns): ', $mark3->getDuration()->timeTakenInNanoseconds(), PHP_EOL;
echo 'Time taken up to 3rd mark (ms): ' , $mark3->getDuration()->timeTakenInMilliseconds(), PHP_EOL;

If you execute this example you should see output similar to the following:

% > php ./examples/usage-without-marks.php
Total time taken (ns): 3000608258
Total time taken (ms): 3000.608258

Time take between 1st and 3rd mark (ns): 1500407710
Time take between 1st and 3rd mark (ms): 1500.40771

Time taken up to 3rd mark (ns): 2250497069
Time taken up to 3rd mark (ms): 2250.497069