usleep()

In this article, we will focus on the PHP usleep() function. We will provide you with an overview of the function, how it works, and examples of its use.

Introduction to the usleep() function

The usleep() function is a built-in function in PHP that was used to pause the execution of a script for a specified number of microseconds. It allowed for delays with very precise timing.

Note: usleep() was deprecated in PHP 8.1 and removed in PHP 8.2. For modern PHP, use time_nanosleep() or time_sleep_until() instead.

The usleep() function takes a single argument, which is the number of microseconds to pause the execution of the script. A microsecond is one millionth of a second, so 1000000 microseconds equals one second. This finer granularity is what distinguishes usleep() from sleep(), which only accepts whole seconds.

Syntax

usleep(int $microseconds): void

How to use the usleep() function

Using the usleep() function is very simple. You just need to call the function and pass the number of microseconds to pause the execution of the script. Here is an example:

How to use the usleep() function?

In this example, we call the usleep() function with an argument of 500000 for the number of microseconds to pause the execution of the script. This pauses the execution of the script for 500 milliseconds (0.5 seconds). We then output a message to the console indicating that we are sleeping, wait for the specified time, and then output another message indicating that we are done sleeping.

Measuring the delay

Because microseconds are easy to miscount, it helps to measure the real elapsed time with microtime(). The example below sleeps for a quarter of a second and prints the actual duration:

<?php
$start = microtime(true);
usleep(250000); // 250000 microseconds = 0.25 seconds
$elapsed = microtime(true) - $start;
echo "Slept for " . round($elapsed, 3) . " seconds\n";
?>

The output is approximately Slept for 0.25 seconds — it may be marginally longer because the operating system decides when to wake the process.

When to use usleep()

usleep() is useful whenever a whole-second pause from sleep() is too coarse:

• Rate limiting — adding a small gap between repeated API calls or loop iterations to stay under a request quota.
• Polling — waiting a fraction of a second before re-checking a file, lock, or queue.
• Throttling output — slowing down a CLI animation or progress display so it is readable.

For pauses measured in nanoseconds, or when you need the call to resume reliably after a signal, prefer time_nanosleep(). To pause until a specific wall-clock moment, use time_sleep_until().

Performance considerations

The usleep() function is lightweight and uses OS sleep calls, so it has negligible CPU overhead. However, the actual pause duration depends on the OS scheduler, meaning sub-millisecond precision is not guaranteed. For higher precision or modern PHP practices, consider time_nanosleep() or time_sleep_until().

Conclusion

In conclusion, the usleep() function is a straightforward way to pause script execution in legacy PHP environments. By understanding its unit requirements, OS-dependent timing behavior, and deprecation status, you can use it effectively for simple delays or migrate to modern alternatives like time_nanosleep() or time_sleep_until().

Practice