index/src/Performance/Timings.php

<?php
// Timings.php
// Created: 2022-02-16
// Updated: 2024-08-01

namespace Index\Performance;

use InvalidArgumentException;

/**
 * Represents a Stopwatch with timing points.
 */
class Timings {
    private Stopwatch $sw;
    private int|float $lastLapTicks;
    private array $laps;

    /**
     * @param ?Stopwatch $sw Stopwatch to measure timing points from, null to start a new one.
     */
    public function __construct(?Stopwatch $sw = null) {
        $this->sw = $sw ?? Stopwatch::startNew();
        $this->lastLapTicks = $this->sw->getElapsedTicks();
    }

    /**
     * Gets the underlying stopwatch object.
     *
     * @return Stopwatch Stopwatch object.
     */
    public function getStopwatch(): Stopwatch {
        return $this->sw;
    }

    /**
     * Returns timing points.
     *
     * @return TimingPoint[] Timing points.
     */
    public function getLaps(): array {
        return $this->laps;
    }

    /**
     * Starts the underlying stopwatch.
     */
    public function start(): void {
        $this->sw->start();
    }

    /**
     * Stops the underlying stopwatch.
     */
    public function stop(): void {
        $this->sw->stop();
    }

    /**
     * Checks whether the underlying stopwatch is running.
     *
     * @return bool true if it is running.
     */
    public function isRunning(): bool {
        return $this->sw->isRunning();
    }

    /**
     * Record a timing point.
     *
     * @param string $name Timing point name, must be alphanumeric.
     * @param string $comment Timing point comment.
     * @throws InvalidArgumentException If $name is not alphanumeric.
     */
    public function lap(string $name, string $comment = ''): void {
        if(!ctype_alnum($name))
            throw new InvalidArgumentException('$name must be alphanumeric.');

        $lapTicks = $this->sw->getElapsedTicks();
        $elapsed = $lapTicks - $this->lastLapTicks;
        $this->lastLapTicks = $lapTicks;

        $this->laps[] = new TimingPoint(
            $lapTicks,
            $elapsed,
            $name,
            $comment
        );
    }
}