diff --git a/_drafts/allocation-safety.md b/_posts/2018-12-15-allocation-safety.md
similarity index 71%
rename from _drafts/allocation-safety.md
rename to _posts/2018-12-15-allocation-safety.md
index 3d0378d..27591ce 100644
--- a/_drafts/allocation-safety.md
+++ b/_posts/2018-12-15-allocation-safety.md
@@ -1,6 +1,6 @@
---
layout: post
-title: "QADAPT - Allocation Safety in Rust"
+title: "QADAPT - debug_assert! for your memory usage"
description: "...and why you want an allocator that goes 💥."
category:
tags: []
@@ -21,27 +21,30 @@ There's another part of the human condition that derives joy from seeing things
-And *that's* the part of the human condition I'm going to focus on.
+And *that's* the part I'm going to focus on.
-# Why an Allocator
+# Why an Allocator?
-So why, after complaining about allocators, would I want to go back and write one myself?
-There are two reasons for that:
+So why, after complaining about allocators, would I still want to write one?
+There are three reasons for that:
-1. **Allocation/dropping is slow**
-2. **It's difficult to know when exactly Rust will allocate/drop, especially when using
-code that you did not write**
+1. Allocation/dropping is slow
+2. It's difficult to know exactly when Rust will allocate or drop, especially when using
+code that you did not write
+3. I want automated tools to verify behavior, instead of inspecting by hand
When I say "slow," it's important to define the terms. If you're writing web applications,
you'll spend orders of magnitude more time waiting for the database than you will the allocator.
-However, there's still plenty of code where micro- or nano-seconds matter; think finance,
+However, there's still plenty of code where micro- or nano-seconds matter; think
+[finance](https://www.youtube.com/watch?v=NH1Tta7purM),
[real-time audio](https://www.reddit.com/r/rust/comments/9hg7yj/synthesizer_progress_update/e6c291f),
-[self-driving cars](https://polysync.io/blog/session-types-for-hearty-codecs/), and networking.
+[self-driving cars](https://polysync.io/blog/session-types-for-hearty-codecs/), and
+[networking](https://carllerche.github.io/bytes/bytes/index.html).
In these situations it's simply unacceptable for you to spend time doing things
-that are not your program, and waiting on the allocator takes a great deal of time.
+that are not your program, and waiting on the allocator is not cool.
-Secondly, it can be difficult to predict where exactly allocations will happen in Rust code. We're going
-to play a quick trivia game: **Does this code trigger an allocation?**
+As I continue to learn Rust, it's difficult for me to predict where exactly allocations will happen.
+So, I propose we play a quick trivia game: **Does this code invoke the allocator?**
## Example 1
@@ -53,8 +56,8 @@ fn my_function() {
**No**: Rust [knows how big](https://doc.rust-lang.org/std/mem/fn.size_of.html)
the `Vec` type is, and reserves a fixed amount of memory on the stack for the `v` vector.
-If we were to reserve extra space (using `Vec::with_capacity`), this would trigger
-an allocation.
+However, if we wanted to reserve extra space (using `Vec::with_capacity`) the allocator
+would get invoked.
## Example 2
@@ -65,8 +68,9 @@ fn my_function() {
```
**Yes**: Because Boxes allow us to work with things that are of unknown size, it has to allocate
-on the heap even though the vector has a known size at compile time. Some release builds may
-optimize out the Box in this specific example, but it's not guaranteed to happen.
+on the heap. While the `Box` is unnecessary in this snippet (release builds will optimize out
+the allocation), reserving heap space more generally is needed to pass a dynamically sized type
+to another function.
## Example 3
@@ -77,25 +81,25 @@ fn my_function(v: Vec) {
```
**Maybe**: Depending on whether the Vector we were given has space available, we may or may not allocate.
-Especially when dealing with code that you did not author, it's helpful to have a system double-check
-that you didn't accidentally introduce an allocation or drop somewhere unintended.
+Especially when dealing with code that you did not author, it's difficult to verify that things behave
+as you expect them to.
# Blowing Things Up
-So, how exactly does QADAPT solve these problems? **Whenever an allocation/drop occurs in code marked
+So, how exactly does QADAPT solve these problems? **Whenever an allocation or drop occurs in code marked
allocation-safe, QADAPT triggers a thread panic.** We don't want to let the program continue as if
nothing strange happened, *we want things to explode*.
However, you don't want code to panic in production because of circumstances you didn't predict.
Just like [`debug_assert!`](https://doc.rust-lang.org/std/macro.debug_assert.html),
-QADAPT will strip out its own code when building in release mode to guarantee no panics and
-no performance impact.
+**QADAPT will strip out its own code when building in release mode to guarantee no panics and
+no performance impact.**
-Finally, there are three ways to have QADAPT check that your code is allocation-free:
+Finally, there are three ways to have QADAPT check that your code will not invoke the allocator:
## Using a procedural macro
-Easiest method, marks an entire function as not allocating/drop safe:
+The easiest method, watch an entire function for allocator invocation:
```rust
use qadapt::no_alloc;
@@ -139,17 +143,17 @@ fn main() {
assert_no_alloc!(v.push(5));
// Even though we remove an item, it doesn't trigger a drop
- // because it's a scalar
+ // because it's a scalar. If it were a `Box<_>` type,
+ // a drop would trigger.
assert_no_alloc!({
- let mut x = v.pop().unwrap();
- x += 1;
+ v.pop().unwrap();
});
}
```
## Using function calls
-Both the most precise and most tedious method:
+Both the most precise and most tedious:
```rust
use qadapt::enter_protected;
@@ -206,9 +210,10 @@ fn main() {
While there's a lot more to writing high-performance code than managing your usage
of the allocator, it's critical that you do use the allocator correctly.
-QADAPT is here to verify that your code is doing what you expect.
+QADAPT will verify that your code is doing what you expect. It's usable even on
+stable Rust from version 1.31 onward, which isn't the case for most allocators.
-I'll be writing more about high-performance code in Rust in the future, and I expect
+I'm hoping to write more about high-performance Rust in the future, and I expect
that QADAPT will help guide that. If there are topics you're interested in,
let me know in the comments below!