PHP: rfc:sleep_function_float_support

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: Support for Floats in Sleep Function ======
  * Version: 0.2-dev
  * Date: 2024-02-25
  * Author: Hans Henrik Bergan (hans@loltek.net), Michael Voříšek (?)
  * Status: Draft
  * First Published at: http://wiki.php.net/rfc/sleep_function_float_support , https://github.com/php/php-src/pull/13401

===== Introduction =====

This RFC introduces 3 enhancements to the PHP `sleep()` function, aimed at increasing its flexibility, precision, and cross-platform consistency.

1/3: **Enhancement of Precision**: The first proposal seeks to  extend the PHP `sleep()` function to accept both integers and floats, enabling delays with sub-second precision.


2/3: **Normalized Return Values on Windows**: Make sleep's return value consistent across operating systems (specifically Windows)

3/3: **Enhanced Return Value Precision**: This RFC proposes to refine the return value of `sleep()` to include sub-second precision.


===== Proposal =====

The proposed changes are designed to make `sleep()` more versatile, precise, and consistent across different operating systems.

1/3: **Acceptance of Float Arguments for Sub-Second Precision**: The core of this proposal is to extend the `sleep()` function to accept both integers and floats as arguments. This modification will enable developers to specify sleep durations with sub-second precision, a feature currently unavailable with the integer-only parameter. By adopting float values, `sleep()` will become a more powerful tool for precise timing operations, eliminating the need to resort to the more complex `usleep()` and `time_nanosleep()` functions for finer-grained delays. This change will maintain the simplicity and ease of use of `sleep()`, while expanding its functionality.

2/3: **Normalized Return Values on Windows**: Presently, when a `sleep()` operation is interrupted on Windows, it returns a static value of 192, reflecting the WAIT_IO_COMPLETION constant from the Windows API. This behavior diverges from that on other platforms, where `sleep()` returns the number of seconds left if interrupted. To address this inconsistency, we propose to standardize the return value of `sleep()` across all platforms by making it return the number of seconds remaining, even on Windows. This adjustment will enhance the portability of PHP scripts and ensure consistent behavior of the `sleep()` function in cross-platform development.

3/3: **Return Value Precision Enhancement**: The current implementation of `sleep()` returns the number of seconds remaining upon interruption with an integer precision. This proposal seeks to improve the precision of the return value to include fractions of a second. Enhancing the return value precision will allow developers to have a more accurate understanding of the timing and duration of interruptions.

These proposed enhancements are intended to bolster the `sleep()` function's capability. By increasing precision, ensuring consistency across platforms, and maintaining simplicity, we aim to significantly improve the utility of `sleep()`.

===== Backward Incompatible Changes =====

Minimal impact is expected on existing codebases. However, there are specific areas where changes in behavior should be noted:

1/3: **Handling of Float Arguments**: The extension of `sleep()` to accept float arguments represents a change from its current integer-only input. Previously, under `strict_types=0`, passing a float to `sleep()` would result in an E_DEPRECATED warning due to the implicit conversion of the float to an integer, causing a loss of precision and initiating a sleep for the truncated integer value. Under `strict_types=1`, passing a float would lead to a TypeError, as `sleep()` strictly expected an integer. With the proposed changes, `sleep()` will accept float values directly, enabling precise sleep durations without generating warnings or errors. This modification enhances the function's usability without disrupting existing integer-based usage.

2/3: **Windows Platform Behavior**: The current return value of 192 on Windows when `sleep()` is interrupted (reflecting the WAIT_IO_COMPLETION constant) will be changed to return the actual number of seconds remaining, aligning with the behavior on other platforms. This change ensures consistency across operating systems but alters the specific return value Windows developers might have previously expected in their interrupt handling logic.

3/3: **Return Value Precision**: Enhancing the return value precision of `sleep()` to include fractions of a second (when the sleep is interrupted) modifies the current behavior, which returns an integer. While this change provides more detailed information, it may affect existing code that expects an integer return value. 

===== Proposed PHP Version(s) =====
Next PHP Minor (currently 8.4) and next PHP Major (currently PHP9)

===== RFC Impact =====

==== To SAPIs ====

No impact on SAPIs is anticipated.

==== To Existing Extensions ====

No existing extensions are expected to be affected by this change.

==== To Opcache ====

No impact on Opcache is anticipated.

==== New Constants ====

No new constants will be introduced by this RFC.

==== php.ini Defaults ====

This RFC does not introduce or alter any php.ini settings.

===== Open Issues =====

There are no open issues related to this RFC.

===== Proposed Voting Choices =====

### 1. Enhancement of Precision: Float Arguments for Sub-Second Precision

**Should we extend `sleep()` to accept floats for sub-second delays?**
- Yes
- No

**Which PHP version should implement this feature if accepted?**
- 8.4
- 9.0

### 2. Normalized Return Values on Windows

**Should we modify `sleep()` on Windows for consistent return values?**
- Yes
- No

**Which PHP version should implement this feature if accepted?**
- 8.4
- 9.0

### 3. Enhanced Return Value Precision

**Should we increase `sleep()` return value precision to include fractions of a second?**
- Yes
- No

**Which PHP version should implement this feature if accepted?**
- 8.4
- 9.0


===== Patches and Tests =====

A pull request has already been submitted and is available for review at: https://github.com/php/php-src/pull/13401

===== Implementation =====

Upon acceptance, the feature will be merged into the specified PHP version, and all relevant documentation will be updated accordingly.

===== References =====
- Discussion on the PHP Internals mailing list: https://externals.io/message/122388
- PHP Manual on `sleep()`: https://www.php.net/manual/en/function.sleep.php
Page Tools
