hrtime()

Este artigo aborda a função PHP hrtime(): o que ela faz, como seus dois modos de retorno diferem, por que seu relógio monotônico a torna a ferramenta certa para benchmarking e exemplos práticos que você pode executar.

Introdução à função hrtime()

hrtime() é uma função nativa disponível no PHP 7.3 e versões posteriores. Ela lê o temporizador de alta resolução do sistema e retorna o tempo atual com precisão de nanossegundos. Seu principal objetivo é o benchmarking — medir quanto tempo um trecho de código leva para ser executado.

A palavra-chave é monotônico. Um relógio monotônico avança apenas para frente, em ritmo constante; ele não é afetado por mudanças no relógio do sistema, ajustes de NTP ou transições de horário de verão. Isso é exatamente o que você precisa para medir o tempo decorrido. Funções de relógio de parede como microtime() e time() podem saltar para trás ou para frente se o relógio do sistema for corrigido durante uma medição, o que corromperia um benchmark.

Note que hrtime() mede o tempo desde uma época arbitrária (geralmente o boot do sistema). O valor absoluto não tem significado por si só — ele só é útil como uma diferença entre duas leituras.

Sintaxe e valores de retorno

hrtime(bool $as_number = false): array|int|false

• $as_number — quando false (padrão), retorna um array de dois elementos [seconds, nanoseconds]. Quando true, retorna um único inteiro: o tempo total em nanossegundos.
• Retorna false se o temporizador de alta resolução não estiver disponível.

A forma de inteiro único (hrtime(true)) é a mais conveniente para benchmarking porque você pode subtrair duas leituras diretamente.

Benchmarking com hrtime(true)

A lógica é: capturar $start, executar o código, capturar $end e então calcular a diferença. Como as leituras são em nanossegundos, divida por 1e6 (1.000.000) para obter milissegundos, ou por 1e9 para obter segundos. O resultado para uma pausa de 1,5 ms será aproximadamente 1.5 ms (o valor exato varia ligeiramente conforme a sobrecarga do sistema).

Lendo o array [seconds, nanoseconds]

Chamada sem argumento, hrtime() retorna um array que você pode desestruturar:

<?php
[$seconds, $nanoseconds] = hrtime();

echo "Seconds since epoch:     $seconds\n";
echo "Nanoseconds component:   $nanoseconds\n";

// Combine both parts into total nanoseconds yourself
$totalNs = $seconds * 1e9 + $nanoseconds;
echo "Total nanoseconds:       $totalNs\n";
?>

Esta forma raramente é necessária na prática — hrtime(true) já fornece o valor combinado — mas ela mostra o que o temporizador realmente está reportando.

Quando usar hrtime() vs microtime()

• Use hrtime() para micro-benchmarks e qualquer medição onde a precisão importa. Ele é monotônico e oferece resolução de nanossegundos.
• Use microtime() quando precisar de um timestamp de relógio de parede (segundos desde a época Unix) em vez de uma duração decorrida.

Armadilhas

• Precisão da aritmética com float. Dividir nanossegundos por 1e6 produz um float, que é suficiente para exibição, mas pode perder precisão em intervalos muito longos. Mantenha a diferença em nanossegundos inteiros durante a medição e converta apenas ao final.
• Scripts de longa execução. Em uma build de 32 bits, o inteiro de nanossegundos pode causar overflow. Para diferenças arbitrariamente grandes, use as extensões bcmath ou gmp para aritmética precisa.
• Não trate o valor como uma data. Ele não é um timestamp Unix; você não pode formatá-lo com date().

Conclusão

hrtime() é a ferramenta certa para medir quanto tempo o código PHP leva para ser executado. Use hrtime(true) para capturar uma leitura em nanossegundos antes e depois do código, subtraia e converta para a unidade desejada. Seu relógio monotônico torna o resultado confiável mesmo quando o relógio do sistema muda — algo que microtime() não pode garantir.

Prática