Add performance note for read_to_end and read_to_string #27213
Conversation
|
Hmmm, while this is nice to say, once it's in the documentation, it's part of the spec. @alexcrichton what do you think? |
|
Very good point! At the least it would be better to couch it in terms of 'may' rather than 'will' - depends on if there's an overriding implementation after all. I guess I'm partly concerned about first impressions - if a user comes along, tests reading in a file, and finds that it's significantly slower than a different language's less pure implementation, then it ought to be obvious from the documentation how to achieve better performance. |
|
I think this may want to be worded in such a way as this is a pretty standard behavior of vectors rather than being special to just these two functions. If you pass In that sense I'm not sure this note is really needed? |
|
I guess what I would mean here is that it was non-obvious to me (although it may be just me!) that the implementation of read_to_end for File wouldn't just handle optimal allocation of the Vec for me - in my thoughts at the time there was no reason why it couldn't. The point regarding not wanting to use stat() is obviously a legitimate reason not to change the code, but I suspect that users coming from slightly higher level languages wouldn't really know to consider that when using the function - the fact that the implementation is relatively bare-bones is only revealed by looking at the code. |
|
Also I realise that I might be labouring the point rather between two PRs - my apologies if so. Happy to close it if it's not a clear gain! |
| @@ -458,7 +458,8 @@ pub trait Read { | |||
| /// All bytes read from this source will be appended to the specified buffer | |||
| /// `buf`. This function will continuously call `read` to append more data to | |||
| /// `buf` until `read` returns either `Ok(0)` or an error of | |||
| /// non-`ErrorKind::Interrupted` kind. | |||
| /// non-`ErrorKind::Interrupted` kind. If the size of the input is known in | |||
| /// advance, performance will be improved by pre-reserving capacity in `buf`. | |||
There was a problem hiding this comment.
Is there a difference between reserving and pre-reserving? Both are things that happen in advance isn't it?
|
I'm going to assume that we're leaving this one out, closing for now! |
In light of #27159, I thought it might be appropriate to add a little note to Read::read_to_end and Read::read_to_string regarding the fact that it's faster to size the buffer in advance where possible.
r? @steveklabnik