|
|
|
|
# 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 ergonomi
|
|
|
|
|
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)
|
