Archives/patterns
2
1
Fork 0
mirror of https://github.com/rust-unofficial/patterns synced 2024-11-14 18:12:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

new pattern: Contain Unsafety in Small Modules

Browse Source
This commit is contained in:
Andre Bogus 2018-11-21 13:28:52 +01:00
parent 45ad4031e9
commit 0989fe893d
2 changed files with 25 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
README.md
View File

@ -36,6 +36,7 @@ language.
* [Visitor](patterns/visitor.md)
* [Fold](patterns/fold.md)
* [Prefer small crates](patterns/small-crates.md)
* [Contain Unsafety in Small Modules](patterns/unsafe-mods.md)
* TODO extension traits
* TODO destructor bombs (ensure linear typing dynamically, e.g., https://github.com/Munksgaard/session-types/commit/0f25ccb7c3bc9f65fa8eaf538233e8fe344a189a)
* TODO convertible to Foo trait for more generic generics (e.g., http://static.rust-lang.org/doc/master/std/fs/struct.File.html#method.open)

24
patterns/unsafe-mods.md Normal file
View File

@ -0,0 +1,24 @@
# 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 [`optional`](https://crates.io/crates/optional) crate has one unsafe module for converting a `&T` to either a slice of one `[T]´ or an empty slice.
* `std`s `String` class is basically just a wrapper over `Vec<u8>` with the added invariant that the contents must be valid unicode. 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)