Skip to content

Improve safety documentation for unsafe traits #288

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

Closed
joshlf opened this issue Aug 25, 2023 · 1 comment
Closed

Improve safety documentation for unsafe traits #288

joshlf opened this issue Aug 25, 2023 · 1 comment
Labels
compatibility-nonbreaking Changes that are (likely to be) non-breaking

Comments

@joshlf
Copy link
Member

joshlf commented Aug 25, 2023

Currently, the safety documentation for FromZeroes, FromBytes, and AsBytes specifies a) what unsafe code may assume about types which implement those traits and, b) what must hold in order for our custom derives to accept a type as soundly implementing those traits (although this is misleadingly presented as the conditions that must hold in order for any impl to be sound).

We should change this layout to the following:

  • What unsafe code is allowed to assume about the trait (this is the raison d'etre for the trait)
  • What properties a type must satisfy in order to allow the preceding to be sound. Unlike what's currently in the documentation, this is more abstract and doesn't refer to specific types. For example, for AsBytes, this might be:
    • No bytes that can be uninitialized
    • No UnsafeCell
  • Rules for specific types (structs, enums, unions, etc) that, if met, satisfy the preceding properties
  • Rules for specific types that are sufficient for our custom derive to recognize the type as soundly implementing the trait

We may want to combine the last two if it makes sense (e.g., inline, call out specific cases where the derive is less powerful).

It may also be useful to call out certain notable types which don't satisfy the requirements (e.g., MaybeUninit might be uninitialized).

Finally, this would be a good opportunity to consider ways that we could make the derives smarter.

This issue was inspired by the following PR comments by @kupiakos:

@joshlf joshlf added the compatibility-nonbreaking Changes that are (likely to be) non-breaking label Aug 25, 2023
@joshlf
Copy link
Member Author

joshlf commented May 3, 2024

Done, mostly by @jswrenn.

@joshlf joshlf closed this as completed May 3, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
compatibility-nonbreaking Changes that are (likely to be) non-breaking
Projects
None yet
Development

No branches or pull requests

1 participant