Merge pull request #75 from llogiq/unsafe-mods

new pattern: Contain Unsafety in Small Modules

README.md

@@ -37,6 +37,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)

patterns/unsafe-mods.md

@@ -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 [`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)