PHP time_nanosleep() 高精度延遲函數詳解與使用示例

函數原型

time_nanosleep(int $seconds, int $nanoseconds): array|bool

參數說明

返回值

• 成功：返回 true
• 失敗：返回 false (參數無效)
• 被信號中斷：返回關聯數組 ['seconds' => 剩餘秒, 'nanoseconds' => 剩餘納秒]

平台支持

基本示例

<?php
// 延遲 3.5 秒 (3 秒 + 500,000,000 納秒)
if (time_nanosleep(3, 500000000) === true) {
    echo "暫停 3.5 秒完成\n";
}

// 精確延遲 100 毫秒
time_nanosleep(0, 100000000);

// 處理信號中斷
$remain = time_nanosleep(10, 0);
if (is_array($remain)) {
    echo "被中斷，剩餘 {$remain['seconds']} 秒 {$remain['nanoseconds']} 納秒\n";
    // 可選：繼續睡眠剩餘時間
    time_nanosleep($remain['seconds'], $remain['nanoseconds']);
}
?>

對比：sleep / usleep / time_nanosleep

實戰：精確速率限制器

<?php
class RateLimiter {
    private $intervalNs; // 納秒間隔

    public function __construct(float $maxPerSecond) {
        $this->intervalNs = (int)(1_000_000_000 / $maxPerSecond);
    }

    public function wait() {
        static $lastTime = 0;
        $now = hrtime(true); // 納秒級單調時鐘
        $elapsed = $now - $lastTime;
        if ($elapsed < $this->intervalNs) {
            $sleepNs = $this->intervalNs - $elapsed;
            $sec = (int)($sleepNs / 1_000_000_000);
            $ns = $sleepNs % 1_000_000_000;
            time_nanosleep($sec, $ns);
        }
        $lastTime = hrtime(true);
    }
}

// 限制每秒最多 50 次
$limiter = new RateLimiter(50);
for ($i = 0; $i < 100; $i++) {
    $limiter->wait();
    // 執行任務
    echo "Task $i at " . date('H:i:s.u') . "\n";
}
?>

注意事項

1. 精度受限於系統調度器：納秒延遲僅為請求值，實際喚醒時間取決於內核調度精度 (通常 1ms 級)。
2. 不要用於長時間睡眠：長延遲請用 sleep()，避免納秒參數溢出。
3. Windows 替代方案：usleep($microseconds) 或 com_dotnet 調用 Sleep() API。
4. 信號處理：長時間睡眠易被信號中斷，生產代碼應檢查返回值並決定是否重試。