docs: document preferences for Zeroable::zeroed vs pin_init::zeroed#158
docs: document preferences for Zeroable::zeroed vs pin_init::zeroed#158nicoan wants to merge 1 commit into
Conversation
| /// [`core::mem::zeroed()`] or using `MaybeUninit<T>::zeroed().assume_init()`. | ||
| /// | ||
| /// This function is preferred over [`pin_init::zeroed()`], unless initializing in a | ||
| /// `const` context or if the object is pinned. |
There was a problem hiding this comment.
What do you mean when "if the object is pinned"?
There was a problem hiding this comment.
My understanding is that it refers to an object that is pinned in memory and initialized in-place. I tried not to deviate too much from Alexandre's comment in the mailing list thread.
| /// Whenever a type implements [`Zeroable`], this function should be preferred over | ||
| /// [`core::mem::zeroed()`] or using `MaybeUninit<T>::zeroed().assume_init()`. | ||
| /// | ||
| /// This function should be used in `const` contexts (as it is a `const fn`) or when |
There was a problem hiding this comment.
I prefer to just gently steer people towards Zeroable::zeroed and not be too explicit. Saying something like "This function is a const version of [Zeroable::zeroed] while const trait is unstable" would be better.
Also, you should add that to init_zeroed, too.
There was a problem hiding this comment.
Does the distinction of a const context apply to init_zeroed as well? I don't see a const fn init_zeroed. I looked for usages in the Linux kernel of when pin_init::init_zeroed vs Zeroable::init_zeroed is used, and I saw that pin_init::init_zeroed is usually used within the init! or pin_init! macros along with the <- operator, and Zeroable::init_zeroed in struct update syntax.
Comment aside, can zeroed be inlined? I see the macro for init_zeroed but not for zeroed
Apologies if the questions are not quite right, I am still wrapping my head around the kernel.
| /// Whenever a type implements [`Zeroable`], this function should be preferred over | ||
| /// [`core::mem::zeroed()`] or using `MaybeUninit<T>::zeroed().assume_init()`. | ||
| /// | ||
| /// This function is preferred over [`pin_init::zeroed()`], unless initializing in a |
There was a problem hiding this comment.
Similar to the other comment, this just needs to hint to people about existence of another function. Say something like "As const trait is not yet stable, [pin_init::zeroed] can be used in const context" is sufficient. Also need to change init_zeroed.
Modify the comments in `pin_init::zeroed` and `Zeroable::zeroed` functions to clarify to the user when one is preferred over the other. This also adapts the example code in `Zeroable::zeroed` doc comments to use that function. Link: https://lore.kernel.org/rust-for-linux/CANiq72m80vip+hz5RngvgH4VxU30amzS-ePr6KVKwKvhf3=Ycg@mail.gmail.com/T/#t Suggested-by: Miguel Ojeda <ojeda@kernel.org> Signed-off-by: Nicolás Antinori <nico.antinori.7@gmail.com>
2 participants
Modify the comments in
pin_init::zeroedandZeroable::zeroedfunctions to clarify to the user when one is preferred over the other.This also adapts the example code in
Zeroable::zeroeddoc comments to use that function.Link: https://lore.kernel.org/rust-for-linux/CANiq72m80vip+hz5RngvgH4VxU30amzS-ePr6KVKwKvhf3=Ycg@mail.gmail.com/T/#t
Suggested-by: Miguel Ojeda ojeda@kernel.org