Skip to content

Improve safety documentation for unsafe traits #288

Closed
@joshlf

Description

@joshlf

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:

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions