docs: link Zeroable::zeroed and pin_init::zeroed in documentation#158
docs: link Zeroable::zeroed and pin_init::zeroed in documentation#158nicoan wants to merge 2 commits 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.
There was a problem hiding this comment.
You're correct. I created a topic https://rust-for-linux.zulipchat.com/#narrow/channel/561532-pin-init/topic/deprecate.20.60pin_init.3A.3Ainit_zeroed.60.3F/with/609626298 on whether we should keep or soft-deprecate the init_zeroed method. This PR can be purely about zeroed.
| /// assert_eq!(point.x, 0); | ||
| /// assert_eq!(point.y, 0); | ||
| /// ``` | ||
| #[inline] |
There was a problem hiding this comment.
The standalone zeroed should also be inlined. Also, could you split this to a separate commit please.
Modify the comments in the `pin_init::zeroed` and `Zeroable::zeroed` functions to cross-reference each other and make developers aware of both options. 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>
The `zeroed` function is a trivial wrapper around
`unsafe { core::mem::zeroed() }`. Mark it as `#[inline]` to avoid
generating unnecessary symbols for it.
Signed-off-by: Nicolás Antinori <nico.antinori.7@gmail.com>
nicoan
changed the title
2 participants
This PR contains two commits.
docs: link
Zeroable::zeroedandpin_init::zeroedin documentationModify the comments in the
pin_init::zeroedandZeroable::zeroedfunctions to cross-reference each other and make developers aware of
both options.
This also adapts the example code in
Zeroable::zeroeddoc comments touse that function.
mark
pin_init::zeroedas#[inline]The
zeroedfunction is a trivial wrapper aroundunsafe { core::mem::zeroed() }. Mark it as#[inline]to avoidgenerating unnecessary symbols for it.