time_nanosleep()

In this article, we will focus on the PHP time_nanosleep() function. We will cover its syntax, parameters and return values, show working examples, explain how to handle interruptions, and point you to related delay functions.

Introduction to the time_nanosleep() function

The time_nanosleep() function is a built-in PHP function that pauses the execution of a script for a given number of seconds and nanoseconds. Because it accepts nanosecond precision, it is the most fine-grained way to introduce a delay in PHP — far more precise than sleep(), which only accepts whole seconds.

A nanosecond is one billionth of a second (1e-9 s), so 1000000000 nanoseconds equal one full second. In practice the real precision is limited by your operating system's scheduler, but the function lets you request sub-microsecond delays.

time_nanosleep() is POSIX-based and is not available on Windows by default.

Syntax

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

Parameters

• $seconds — the number of whole seconds to pause. Must be a non-negative integer.
• $nanoseconds — the number of additional nanoseconds to pause, in the range 0 to 999999999. Values of 1000000000 or more cause a warning and the call fails.

Return values

• Returns true on success.
• Returns false on error (for example, when an argument is out of range).
• If the sleep is interrupted by a signal, it returns an associative array with two keys, seconds and nanoseconds, holding the amount of time still left to sleep. This is what lets you resume the delay where it was interrupted.

How to use the time_nanosleep() function

Call the function and pass the number of seconds and nanoseconds to pause. Here is a basic example:

In this example, we call time_nanosleep() with 1 second and 500000000 nanoseconds. This pauses the script for 1 second plus 500,000,000 nanoseconds (0.5 seconds), so 1.5 seconds in total. We print a message before the pause, wait for the specified time, then print another message when done.

Measuring the actual delay

Because the OS scheduler decides exactly when the process resumes, the real pause is at least the requested duration but may be slightly longer. You can verify this with microtime():

The printed value will be approximately 0.250 seconds (for example 0.250 or 0.251), confirming the requested quarter-second delay.

Resuming after a signal interruption

If a signal interrupts the sleep, time_nanosleep() returns the remaining time as an array instead of true. You can loop until the full delay has elapsed:

Without a signal handler the loop body never runs, but this is the correct pattern for scripts that register signal handlers with the pcntl extension.

Performance considerations

time_nanosleep() is efficient because it relies on the OS scheduler rather than busy-waiting, so it does not consume CPU cycles during the pause. Keep these points in mind:

• It is POSIX-only and not available on Windows by default. On Windows, use usleep() for microsecond delays.
• When calling it frequently, context-switching overhead can add up, so use it only when sub-second precision is actually required.
• The pause is a minimum, not an exact guarantee — never rely on it for hard real-time timing.

Related functions

• sleep() — pause execution for a whole number of seconds.
• usleep() — pause execution for a number of microseconds.
• time_sleep_until() — pause until a given Unix timestamp is reached.
• microtime() — get the current time with microsecond precision, useful for measuring delays.

Conclusion

In conclusion, the time_nanosleep() function is a powerful tool for creating delays with very precise timing. By understanding how to use the function and its performance considerations, you can take advantage of this feature to create precise timing delays in your PHP scripts.

Practice