<?php

declare(strict_types=1);

namespace App\Framework\DateTime;

use App\Framework\Core\ValueObjects\Duration;

/**
 * Interface for high-resolution timing operations using hrtime() with Value Objects
 *
 * This interface provides monotonic, high-precision timing capabilities
 * that are perfect for performance measurements and are unaffected by
 * system clock changes. All methods return or accept Value Objects for type safety.
 */
interface HighResolutionClock
{
    /**
     * Get high-resolution time as Duration
     * Uses hrtime() for monotonic, high-precision timing
     *
     * @return Duration High-resolution Duration since arbitrary point
     */
    public function hrtime(): Duration;

    /**
     * Measure duration of a callable execution
     *
     * @param callable $callback Function to measure
     * @return array{result: mixed, duration: Duration} Result and duration
     */
    public function measureDuration(callable $callback): array;

    /**
     * High-resolution benchmark helper
     *
     * @param callable $callback Function to benchmark
     * @param int $iterations Number of iterations
     * @return array{total: Duration, average: Duration, min: Duration, max: Duration}
     */
    public function benchmark(callable $callback, int $iterations = 1): array;
}
