PHP usleep() Function – Definition | Examples

What is PHP usleep() Function?

If you make a script delay for few microseconds, not for few seconds, use PHP usleep() function. The usleep() function delays the execution of your code for a specified number of microseconds. A microsecond is one millionth of a second (1/1,000,000 of 1 second). A millisecond is one thousandth of a second (1/1,000 of 1 second).

Syntax:

usleep(microseconds)

Parameters:

microseconds (Required): Number of microseconds to make the script delay.

Return Values:

The function returns no value.

Examples:

Example 1:

<?php
$pause_time = 500000;
echo "Script starts on: ". (new DateTime('now'))->format('h:i:s.u') . "<br />";
usleep($pause_time);
echo "It pauses for " . $pause_time . " microseconds." . "<br />";
echo "And, it completes on: " . (new DateTime('now'))->format('h:i:s.u') . "<br />";
?>

Output:

Script starts on: 06:59:58.343
It pauses for 500000 microseconds.
And, it completes on: 06:59:58.856

Explanation:

The usleep() function delays the code execution for 500000 microseconds. For this, we see the time difference between before (06:59:58.343) and after (06:59:58.856) the usleep() function is 511801 microseconds. Note: the extra milliseconds (11801) are the time taken to print the lines.

Example 2:

<?php
echo usleep(-500000);
?>

Output:

Fatal error: Uncaught ValueError: usleep(): Argument #1 ($microseconds) must be greater than or equal to 0 in D:\xampp\htdocs\php\usleep function.php:2 Stack trace: #0 D:\xampp\htdocs\php\usleep.php(2): usleep(-500000) #1 {main} thrown in D:\xampp\htdocs\php\usleep.php on line 2

Explanation:

As the usleep() function doesn’t take a negative number as arguments, so it throws the ValueError error.

Explanation:

Practical Usages of usleep() Function:

Controlling processing time: In some actions like polling, you might want to add an interval after each shot. Use usleep() in this case like this-
```
<?php
if(isPoleCompleted()){
    usleep(750000);
}
?>
```
Reducing CPU overload: A script that performs heavy data processing and computation takes huge CPU resources. To reduce CPU overload, we can add delay with usleep() function like this-
```
<?php
foreach($dataPile as $data){
    doComputation($data);
    sleep(750000);
}
?>
```
Restricting calls on API request: APIs often have restrictions on the number of requests you can make to them within a time frame. To stay within this limit, you can add delays between calls using usleep() function like this-
```
<?php
foreach($apiRequests as $request){
    apiCall($request);
    sleep(500000);
}
?>
```

Notes on usleep() Function:

If you need to use more than 1,000,000 microseconds in this parameter, the usleep() function may not work in your operating system. In this case, use sleep() function.

Caution:

As usleep() function uses CPU cycles, it could be expensive. So, use this function carefully only when it is necessary.

PHP Version Support:

PHP 4, PHP 5, PHP 7, PHP 8

Summary: PHP usleep() Function

usleep(), which is one of the built-in PHP misc functions, is very useful function to accomplish many tasks.

Reference:

https://www.php.net/manual/en/function.usleep.php