You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
36 lines
1.3 KiB
Markdown
36 lines
1.3 KiB
Markdown
# Contain unsafety in small modules
|
|
|
|
## Description
|
|
|
|
If you have `unsafe` code, create the smallest possible module that can uphold
|
|
the needed invariants to build a minimal safe interface upon the unsafety. Embed
|
|
this into a larger module that contains only safe code and presents an ergonomic
|
|
interface. Note that the outer module can contain unsafe functions and methods
|
|
that call directly into the unsafe code. Users may use this to gain speed
|
|
benefits.
|
|
|
|
## Advantages
|
|
|
|
- This restricts the unsafe code that must be audited
|
|
- Writing the outer module is much easier, since you can count on the guarantees
|
|
of the inner module
|
|
|
|
## Disadvantages
|
|
|
|
- Sometimes, it may be hard to find a suitable interface.
|
|
- The abstraction may introduce inefficiencies.
|
|
|
|
## Examples
|
|
|
|
- The [`toolshed`](https://docs.rs/toolshed) crate contains its unsafe
|
|
operations in submodules, presenting a safe interface to users.
|
|
- `std`'s `String` class is a wrapper over `Vec<u8>` with the added invariant
|
|
that the contents must be valid UTF-8. The operations on `String` ensure this
|
|
behavior. However, users have the option of using an `unsafe` method to create
|
|
a `String`, in which case the onus is on them to guarantee the validity of the
|
|
contents.
|
|
|
|
## See also
|
|
|
|
- [Ralf Jung's Blog about invariants in unsafe code](https://www.ralfj.de/blog/2018/08/22/two-kinds-of-invariants.html)
|