-
Notifications
You must be signed in to change notification settings - Fork 12.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add doc aliases for memory allocations #79233
Conversation
(rust_highfive has picked a reviewer for you, use r? to override) |
This is a great idea! For Also consider aliases for I'd love to see PRs like this for other common C functions as well, such as the |
I've updated with @joshtriplett's feedback. @Manishearth @GuillaumeGomez did you resolve the conversation in #79211? -- I'm tempted to tag both libs and docs on this for review, but wanted to check before doing so. |
@yoshuawuyts yeah mostly "ping both @GuillaumeGomez and the libs team for doc changes". Hopefully they can form a libs-docs team eventually. Feel free to tag the docs team, it's just kinda defunct right now and you'd be tagging more people than you need. |
No need. Just |
Got it, thanks heaps! |
☔ The latest upstream changes (presumably #80530) made this pull request unmergeable. Please resolve the merge conflicts. |
Triage: there's merge conflicts now. |
Oh dang, this is because of the new |
Resolved the merge conflicts; a simple rebase was enough. This is again ready for review! |
@@ -828,6 +833,7 @@ impl<T, A: Allocator> Vec<T, A> { | |||
/// } | |||
/// # process_data(&[1, 2, 3]).expect("why is the test harness OOMing on 12 bytes?"); | |||
/// ``` | |||
#[doc(alias = "realloc")] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Even though this realloc
alias makes sense, having so many of it is kinda killing its purpose, no?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Rust has no canonical "realloc" function; instead it's split up between various different methods which perform specific kinds of reallocations. Someone searching for "realloc" may not be aware of this, and sharing the various ways in which vectors can be reallocated may be helpful.
Conversely an experienced Rust programmer may not recall the exact name of a specific reallocation they're trying to perform (or may want to validate whether a vec method indeed reallocates) and searching for "realloc" may provide them with an answer.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fine by me, let's give it a try like this then!
- Vec::with_capacity / Box::new -> alloc + malloc - Box::new_zeroed -> calloc - Vec::{reserve,reserve_exact,try_reserve_exact,shrink_to_fit,shrink_to} -> realloc
Thanks! @bors: r+ |
📌 Commit 7d10238 has been approved by |
☀️ Test successful - checks-actions |
This patch adds doc aliases for various C allocation functions, making it possible to search for the C-equivalent of a function and finding the (safe) Rust counterpart:
Vec::with_capacity
/Box::new
/vec!
-> alloc + malloc, allocates memoryBox::new_zeroed
-> calloc, allocates zeroed-out memoryVec::{reserve,reserve_exact,try_reserve_exact,shrink_to_fit,shrink_to}
-> realloc, reallocates a previously allocated slice of memoryIt's worth noting that
Vec::new
does not allocate, so we don't link to it. Instead people are probably looking forVec::with_capacity
orvec!
. I hope this will allow people comfortable with the system allocation APIs to make it easier to find what they may be looking for.Thanks!