Update documentation for std::fs::read_to_string to reflect performan…

[fiveseven-lambda]

…ce improvements on Windows

Closes #130600.

This pull request updates the documentation for std::fs::read_to_string to clarify its performance advantages on Windows compared to the combination of std::fs::File::open and std::io::Read::read_to_string.

In PR #110655, optimizations were introduced to improve the performance of std::fs::read_to_string on Windows. However, the current documentation does not reflect these improvements, potentially misleading users into thinking that using File::open and Read::read_to_string would have the same performance characteristics.

The updated documentation now explicitly mentions that std::fs::read_to_string offers better performance on Windows than manually opening the file and using std::io::Read::read_to_string.

r? workingjubilee

[rustbot]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @workingjubilee (or someone else) some time within the next two weeks.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

• @rustbot author: the review is finished, PR author should check the comments and take action accordingly
• @rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

[the8472]

potentially misleading users into thinking that using File::open and Read::read_to_string would have the same performance characteristics.

Considering the buffers use exponential growing the allocation behavior should hardly make a difference. I don't think it's worth pointing this out in the documentation (guaranteeing any implementation details) unless the advantage is tremendous.

Do you have any numbers that show that it's worth steering users in this direction and tying our hands regarding future implementation changes?

See also #130600 (comment)

[workingjubilee]

Considering the buffers use exponential growing the allocation behavior should hardly make a difference.

? Er, do they? If you use with_capacity you get an allocation of that size if you allocate a sufficiently large allocation, because there's no benefit to fitting a large allocation of multiple megabytes to the next exponential size category.

[the8472]

It's O(1) vs. O(log(n)) allocations, which sometimes makes a difference, but when you're doing IO then I'd expect the IO overhead to dwarf the allocation overhead.

The changes were motivated not by allocation behavior but by repeated initialization costs in the windows kernel (#110650).

I could be wrong. Perhaps the default allocator on windows is slow enough that it's noticeable. That's why I asked for numbers

[fiveseven-lambda]

I see... as you say, it doesn't seem like the performance difference is as significant as I initially thought, especially since IO tends to be the bottleneck in such cases. I raised this issue just because I was surprised by the source code and the issue #110650 when I searched about read_to_string to use in my own project. So I don’t have specific numbers...

[fiveseven-lambda]

@ducktherapy (who raised issue #110650) had posted a related question on reddit and StackOverflow.
https://stackoverflow.com/questions/76055481/why-does-fileread-to-end-get-slower-the-larger-the-buffer-capacity
They mentioned observing "a huge (50x+ on this machine) performance difference" with the cost increasing linearly.

[the8472]

That was before the fix.

[workingjubilee]

I'm still game to accept this but it's a "should have better performance" or "may be faster and more efficient" rather than "is definitely going to have better performance for (specific implementation detail)" because of OS-specific differences.

[fiveseven-lambda]

To clarify, which part are you referring to by saying "may be faster and more efficient"?

Cf. #130600 (comment)

The only optimization that fs::read_to_string has is that it can use the size from the file metadata directly and doesn't need to retrieve the current seek position of the file handle.

[workingjubilee]

@rustbot author

[alex-semenyuk]

@fiveseven-lambda
From wg-triage. Is it ready for review?

[fiveseven-lambda]

I intended to close the PR but forgot to do so. I’ll go ahead and close it now. I am sorry for any inconvenience caused.