PHPのusleep()は、プログラムの実行をマイクロ秒単位で一時停止するための関数です。
1秒未満の細かな待機時間を設定したい場合に便利で、ループ処理やリトライ処理、APIへのアクセス間隔を調整したいときなどに利用できます。
usleep()では、待機時間を「秒」ではなく「マイクロ秒」で指定します。
1マイクロ秒は100万分の1秒です。
usleep関数の基本的な使い方
usleepの構文
usleep()の基本構文は次のとおりです。
usleep(int $microseconds): void
引数の$microsecondsには、待機させたい時間をマイクロ秒単位で指定します。
戻り値はありません。
たとえば、0.5秒間処理を停止したい場合は次のように記述します。
<?php
echo "処理開始\n";
usleep(500000);
echo "処理再開\n";
500000マイクロ秒は0.5秒に相当するため、usleep()の実行後、おおむね0.5秒経過してから次の処理が実行されます。
マイクロ秒と秒の換算方法
usleep()を使う場合は、秒やミリ秒をマイクロ秒へ換算する必要があります。
主な換算は次のとおりです。
| 時間 | マイクロ秒 | 記述例 |
|---|---|---|
| 1ミリ秒 | 1,000 | usleep(1000); |
| 10ミリ秒 | 10,000 | usleep(10000); |
| 100ミリ秒 | 100,000 | usleep(100000); |
| 0.5秒 | 500,000 | usleep(500000); |
| 1秒 | 1,000,000 | usleep(1000000); |
1秒は1,000,000マイクロ秒です。
また、1ミリ秒は1,000マイクロ秒なので、ミリ秒から変換する場合は次の式を使えます。
ミリ秒 × 1000 = マイクロ秒
たとえば250ミリ秒待機させたい場合は、次のようになります。
usleep(250000);
usleepでミリ秒単位の待機を設定する方法
100ミリ秒待機する
100ミリ秒は100,000マイクロ秒です。
<?php
usleep(100000);
このコードでは、おおむね0.1秒間処理が停止します。
500ミリ秒待機する
500ミリ秒の場合は次のように記述します。
<?php
usleep(500000);
約0.5秒間待機します。
変数を使ってミリ秒を指定する
ミリ秒単位で時間を管理したい場合は、次のように書くとコードの意味が分かりやすくなります。
<?php
$milliseconds = 300;
usleep($milliseconds * 1000);
この例では、300ミリ秒、つまり約0.3秒間待機します。
ループ処理でusleepを使う方法
一定時間ごとに処理を実行する
usleep()は、繰り返し処理の間隔を空けたい場合にも利用できます。
<?php
for ($i = 1; $i <= 5; $i++) {
echo $i . PHP_EOL;
usleep(500000);
}
このコードでは、各ループの間に約0.5秒の待機時間が入ります。
短時間に連続して処理を実行したくない場合に便利です。
APIアクセスの間隔を調整する
外部APIへ繰り返しアクセスする場合、一定の間隔を設ける目的でusleep()を使用できます。
<?php
$urls = [
'https://example.com/api/1',
'https://example.com/api/2',
'https://example.com/api/3',
];
foreach ($urls as $url) {
echo $url . PHP_EOL;
// APIへのリクエスト処理
usleep(500000);
}
この例では、APIへのアクセスごとに約0.5秒待機しています。
ただし、実際にAPIを利用する場合は、usleep()だけでアクセス頻度を調整するのではなく、そのAPIが定めているレート制限やRetry-Afterなどの仕様に従うことが重要です。
usleepとsleepの違い
時間を指定する単位が異なる
PHPには、usleep()と似た関数としてsleep()があります。
両者の主な違いは、待機時間を指定する単位です。
| 関数 | 指定単位 | 主な用途 |
|---|---|---|
sleep() | 秒 | 秒単位で待機する |
usleep() | マイクロ秒 | 1秒未満など細かな時間で待機する |
たとえば2秒待機する場合は、次のようにsleep()を使います。
sleep(2);
一方、0.2秒待機したい場合はusleep()を使います。
usleep(200000);
1秒を超える待機にはsleepを検討する
PHP公式マニュアルでは、usleep()に1,000,000マイクロ秒を超える値を指定した場合、OSによってサポートされない可能性があるとされています。
そのため、数秒単位の待機が必要な場合はsleep()を使うほうが適切です。
たとえば3秒待機する場合は、
usleep(3000000);
とするよりも、
sleep(3);
と記述するほうが分かりやすく、環境依存の問題も避けやすくなります。
秒とマイクロ秒を組み合わせて待機する方法
1.5秒待機する
1秒以上の時間と1秒未満の時間を組み合わせたい場合は、sleep()とusleep()を併用できます。
<?php
sleep(1);
usleep(500000);
このコードでは、合計で約1.5秒待機します。
たとえば次のように使用できます。
<?php
echo "開始\n";
sleep(1);
usleep(500000);
echo "約1.5秒後に実行\n";
usleepを関数化して使いやすくする方法
ミリ秒指定の関数を作成する
usleep()ではマイクロ秒を指定するため、コードを見ただけでは待機時間が分かりにくい場合があります。
そのような場合は、ミリ秒単位で指定できる関数を作ると便利です。
<?php
function sleepMilliseconds(int $milliseconds): void
{
usleep($milliseconds * 1000);
}
sleepMilliseconds(500);
この方法であれば、
usleep(500000);
と書くよりも、
sleepMilliseconds(500);
と書いたほうが「500ミリ秒待機する」という意図を理解しやすくなります。
usleepでランダムな待機時間を設定する方法
random_intと組み合わせる
処理によっては、毎回同じ時間ではなくランダムな待機時間を設定したい場合があります。
たとえば100～500ミリ秒の範囲で待機させる場合は、次のように記述できます。
<?php
$delay = random_int(100000, 500000);
usleep($delay);
random_int()で100,000～500,000マイクロ秒の値を生成しているため、おおむね0.1～0.5秒の間で待機時間が変化します。
なお、Webスクレイピングなどで待機時間を入れる場合でも、対象サイトの利用規約やrobots.txt、アクセス制限などを確認する必要があります。
usleepでリトライ処理の間隔を空ける方法
失敗した処理を一定時間後に再実行する
usleep()は、処理が失敗した場合のリトライ間隔を設定する用途にも使用できます。
<?php
for ($attempt = 1; $attempt <= 3; $attempt++) {
echo "試行回数: {$attempt}\n";
$success = false;
// 実際の処理
if ($success) {
break;
}
if ($attempt < 3) {
usleep(500000);
}
}
このコードでは、処理に失敗した場合、約0.5秒待ってから再試行します。
実際のシステムでは、アクセス集中や外部サービスの障害に対応するため、試行回数が増えるごとに待機時間を長くする「指数バックオフ」が使われることもあります。
usleepを使うときの注意点
指定した時間ぴったりに処理が再開されるとは限らない
usleep()に指定する時間は、厳密な処理再開時刻を保証するものではありません。
たとえば、
usleep(100000);
と指定しても、必ず正確に0.1秒後に処理が再開されるとは限りません。
OSのスケジューリングやシステム負荷、タイマーの精度などによって、実際の待機時間が指定値より長くなることがあります。
そのため、usleep()を高精度なタイマーとして使用するのは適していません。
長時間の待機には向いていない
Webアプリケーションでusleep()を使って長時間待機すると、その間もPHPの処理が終了しないため、実行中のワーカーなどのリソースを占有する可能性があります。
たとえば、大量のアクセスがあるWebアプリケーションで各リクエストを数秒ずつ待機させる設計は、パフォーマンス低下につながる可能性があります。
長時間の待機や大量の遅延処理が必要な場合は、次のような仕組みを検討するとよいでしょう。
- ジョブキュー
- cron
- メッセージキュー
- 非同期処理
- イベントループ
- バックグラウンドジョブ
用途によっては、usleep()で処理を止めるよりも、処理そのものを分離する設計のほうが適しています。
usleepの実際の待機時間を確認する方法
hrtimeと組み合わせる
実際にどの程度待機したかを確認したい場合は、hrtime()などを利用できます。
<?php
$start = hrtime(true);
usleep(500000);
$end = hrtime(true);
$elapsedNanoseconds = $end - $start;
$elapsedSeconds = $elapsedNanoseconds / 1_000_000_000;
echo $elapsedSeconds . "秒\n";
この例では、理論上は約0.5秒の待機になります。
ただし、実際の結果はOSやシステムの負荷によって0.5秒より少し長くなる場合があります。
usleepとtime_nanosleepの違い
time_nanosleepはナノ秒を指定できる
PHPには、より細かな単位で待機時間を指定できるtime_nanosleep()も用意されています。
time_nanosleep()では、秒とナノ秒を指定して待機時間を設定できます。
たとえば次のように記述します。
<?php
time_nanosleep(0, 500000000);
この例では、0秒と500,000,000ナノ秒を指定しているため、約0.5秒待機します。
ただし、ナノ秒を指定できるからといって、処理がナノ秒単位で正確に再開されることを保証するものではありません。
usleepが向いているケース
短時間の待機処理に適している
usleep()は、主に次のような用途に向いています。
- ループ処理の間隔を空ける
- APIアクセスの間隔を調整する
- ポーリング処理の間隔を設定する
- CLIスクリプトで短時間待機する
- リトライ処理の間隔を設定する
- テスト用に処理を意図的に遅らせる
特に、数十ミリ秒から数百ミリ秒程度の短い待機時間を簡単に設定したい場合に便利です。
usleepが向いていないケース
大量の待機処理には注意する
次のような処理を大量に実行する場合は注意が必要です。
while (true) {
// 状態を確認
usleep(10000);
}
短い間隔で何度も状態を確認するポーリング処理は、システムの規模によってはCPUやプロセスなどのリソースを無駄に消費する可能性があります。
リアルタイム性が求められる大規模なシステムでは、イベント駆動型の処理やジョブキュー、メッセージキューなどを検討したほうが適切な場合があります。
PHPのusleep関数の使い方まとめ
PHPのusleep()は、プログラムの実行をマイクロ秒単位で一時停止するための関数です。
基本的な使い方は次のとおりです。
usleep(500000);
この場合、約0.5秒間処理が停止します。
覚えておきたい時間の換算は次のとおりです。
1秒 = 1,000,000マイクロ秒
1ミリ秒 = 1,000マイクロ秒
そのため、代表的な指定方法は次のようになります。
usleep(1000); // 約1ミリ秒
usleep(10000); // 約10ミリ秒
usleep(100000); // 約0.1秒
usleep(500000); // 約0.5秒
1秒を超える待機については、OSによってusleep()の大きな値が適切に扱われない可能性があるため、基本的にはsleep()を使用するほうが適しています。
また、usleep()は指定した時間どおりに正確に処理を再開することを保証する関数ではありません。
短時間の待機や処理間隔の調整には便利ですが、長時間の待機や大量の並行処理が必要なシステムでは、ジョブキューや非同期処理など、別の仕組みも検討するとよいでしょう。
以上、PHPのusleep関数の使い方についてでした。
最後までお読みいただき、ありがとうございました。
