add CACM article to website
[web.git] / ralf / _posts / 2018-08-07-stacked-borrows.md
1 ---
2 title: "Stacked Borrows: An Aliasing Model For Rust"
3 categories: internship rust
4 forum: https://internals.rust-lang.org/t/stacked-borrows-an-aliasing-model-for-rust/8153
5 ---
6
7 In this post, I am proposing "Stacked Borrows": A set of rules defining which kinds of aliasing are allowed in Rust.
8 This is intended to answer the question which pointer may be used when to perform which kinds of memory accesses.
9
10 This is a long-standing open question of many unsafe code authors, and also by compiler authors who want to add more optimizations.
11 The model I am proposing here is by far not the first attempt at giving a definition: The model is heavily based on ideas by [@arielb1](https://github.com/nikomatsakis/rust-memory-model/issues/26) and [@ubsan](https://github.com/nikomatsakis/rust-memory-model/issues/28), and of course taking into account the lessons I [learned last year]({% post_url 2017-08-11-types-as-contracts-evaluation %}) when I took my first stab at defining such a model, dubbed ["Types as Contracts"]({% post_url 2017-07-17-types-as-contracts %}).
12
13 <!-- MORE -->
14
15 But before I delve into my latest proposal, I want to briefly discuss a key difference between my previous model and this one:
16 "Types as Contracts" was a fully "validity"-based model, while "Stacked Borrows" is (to some extent) "access"-based.
17
18 **Update:**
19 Since publishing this post, I have written [another]({% post_url 2018-11-16-stacked-borrows-implementation %}) blog post about a slightly adjusted version of Stacked Borrows (the first version that actually got implemented).
20 That other post is self-contained, so if you are just interested in the current state of Stacked Borrows, I suggest you go there.
21 Only go on reading here if you want some additional historic context.
22 **/Update**
23
24 ## 1 Validity-based vs. Access-based
25
26 An "access"-based model is one where certain properties -- in this case, mutable references being unique and shared references pointing to read-only memory -- are only enforced when the reference is actually used to *access* memory.
27 In contrast, a "validity"-based model requires these properties to always hold for all references that *could* be used.
28 In both cases, violating a property that the model requires to hold is undefined behavior..
29
30 Essentially, with a validity-based model like "Types as Contracts", the basic idea is that all data is always valid according to the type it is given.
31 Enforcing the restrictions of such a model (e.g., when checking whether a program has undefined behavior) amounts to eagerly checking all reachable data for validity.
32 An access-based model, on the other hand, only requires data to be valid when used.
33 Enforcing it amounts to lazily checking the bare minimum at each operation.
34
35 Validity-based models have several advantages: Eager checking means we can typically identify which code is actually responsible for producing the "bad" value.
36 "All data must always be valid" is also easier to explain than a long list of operations and the kind of restrictions they place upon the data.
37
38 However, in Rust, we cannot talk about references and whether the are valid at their given type without talking about lifetimes.
39 With "Types as Contracts", the exact place where a lifetime ended turned out to be really important.
40 Not only did this make the specification complex and hard to understand; the implementation in Miri also had to actively work against the compiler's general intention to forget about lifetimes as early as possible.
41 With non-lexical lifetimes, the "end" of a lifetime is not even so clearly defined any more.
42
43 ## 2 Stacking Borrows
44
45 For these reasons, my second proposal makes lifetimes in general and the result of lifetime inference in particular completely irrelevant for whether a program has undefined behavior (UB).
46 This is one of the core design goals.
47
48 If you need some more context on undefined behavior and how it relates to compiler optimizations, I suggest you read [my blog post on this topic]({% post_url 2017-07-14-undefined-behavior %}) first.
49 It's not a long post, and I cannot repeat everything again here. :)
50
51 The central idea of this model (and its precursors by @arielb1 and @ubsan) is that, for every location, we keep track of the references that are allowed to access this location.
52 (I will discuss later just how we keep track of this; for now, let's just assume it can be done.)
53 This forms a stack: When we have an `&mut i32`, we can *reborrow* it to obtain a new reference.
54 That new reference is now the one that must be used for this location, but the old reference it was created from cannot be forgotten: At some point, the reborrow will expire and the old reference will be "active" again.
55 We will have other items on that stack as well, so we will write `Uniq(x)` to indicate that `x` is the unique reference permitted to access this location.
56
57 Let us look at an example:
58 {% highlight rust %}
59 fn demo0(x: &mut i32) -> i32 {
60   // At the beginning of the function, `x` must be the "active" reference
61   // for the 4 locations it points to, meaning `Uniq(x)` is at the top of the stack.
62   // (It's 4 locations because `i32` has size 4.)
63   let y = &mut *x; // Now `Uniq(y)` is pushed onto the stack, as new active reference.
64   // The stack now contains: Uniq(y), Uniq(x), ...
65   *y = 5; // Okay because `y` is active.
66   *x = 3; // This "reactivates" `x` by popping the stack.
67   // The stack now contains: Uniq(x), ...
68   *y // This is UB! `Uniq(y)` is not on the stack of borrows, so `y` must not be used.
69 }
70 {% endhighlight %}
71 Of course, this example would not compile because the borrow checker would complain.
72 However, in my interpretation, the *reason* it complains is that if it accepted the program, we would have UB in safe code!
73
74 This is worth pondering a bit: The model defines program semantics without taking lifetimes into account, so we can run programs and ask whether they have UB without
75 ever doing lifetime inference or borrow checking (very much unlike "Types as Contracts").
76 One important property, then, is that *if* the program has UB and does not use any unsafe code, the borrow checker must detect this.
77 In some sense, my model defines a dynamic version of the borrow checker *that works without lifetimes*.
78 It turns out that even with non-lexical lifetimes, the borrow structure for a given location is still well-nested, which is why we can arrange borrows in a stack.
79
80 ### 2.1 Raw Pointers
81
82 Let us bypass the borrow checker by adding some unsafe code to our program:
83 {% highlight rust %}
84 fn demo1(x: &mut i32) -> i32 {
85   // At the beginning of the function, `x` must be the "active" reference.
86   let raw = x as *mut _; // Create raw pointer
87   // The stack now contains: Raw, Uniq(x), ...
88   let y = unsafe { &mut *raw }; // Now `y` is pushed onto the stack, as new active reference.
89   // The stack now contains: Uniq(y), Raw, Uniq(x), ...
90   *y = 5; // Okay because `y` is active.
91   *x = 3; // This "reactivates" `x` by popping the stack twice.
92   *y // This is UB! `Uniq(y)` is not on the stack of borrows, so `y` must not be used.
93 }
94 {% endhighlight %}
95
96 What happens here is that we are casting `x` to a raw pointer.
97 For raw pointers, we cannot really keep track of where and how they have been created -- raw pointers can be safely cast to and from integers, and data could flow arbitrarily.
98 So, when a `&mut` is cast to `*mut` like above, we instead push `Raw` onto the stack, indicating that *any* raw pointer may be used to access this location.
99 (The usual restrictions about address arithmetic across allocations still apply, I am just talking about the borrow checking here.)
100
101 In the next line, we use a raw pointer to create `y`.
102 That is okay because `Raw` is active.
103 As usual when a reference is created, we push it onto the stack.
104 This makes `y` the active reference, so we can use it in the next line.
105 And again, using `x` pops the stack until `x` is active -- in this case, this removes both the `Uniq(y)` and the `Raw`, making `y` unusable and causing UB in the last line.
106
107 Let us look at another example involving raw pointers:
108 {% highlight rust %}
109 fn demo2(x: &mut i32) -> i32 {
110   // At the beginning of the function, `x` must be the "active" reference.
111   let raw = x as *mut _; // Create raw pointer
112   // The stack now contains: Raw, Uniq(x), ...
113   let y = unsafe { &mut *raw }; // Now `y` is pushed onto the stack, as new active reference.
114   // The stack now contains: Uniq(y), Raw, Uniq(x), ...
115   *y = 5; // Okay because `y` is active.
116   unsafe { *raw = 5 }; // Using a raw pointer, so `Raw` gets reactivated by popping the stack!
117   // The stack now contains: Raw, Uniq(x), ...
118   *y // This is UB! `Uniq(y)` is not on the stack of borrows, so `y` must not be used.
119 }
120 {% endhighlight %}
121 Because raw pointers are tracked on the stack, they have to follow the well-nested structure.
122 `y` was "created from" `raw`, so using `raw` again invalidates `y`!
123 This is exactly in symmetry with the first example where `y` was "created from" `x`, so using `x` again invalidated `y`.
124
125 ### 2.2 Shared References
126
127 For shared references, of course, we do not have a single reference which is the only one with permission to access.
128 The key property we have to model is that shared references point to memory that does not change (assuming no interior mutability is involved).
129 The memory is, so to speak, *frozen*.
130
131 For this purpose, we tag shared references with some kind of "timestamp" indicating *when* it was created.
132 We also have an extra flag for each location storing *since when* the location is frozen.
133 Using a shared reference to access memory is okay if memory has been frozen continuously since the reference was created.
134
135 We can see this in action in the following example:
136 {% highlight rust %}
137 fn demo3(x: &mut i32) -> i32 {
138   // At the beginning of the function, `x` must be the "active" reference.
139   let raw = x as *mut _; // Create raw pointer
140   // The stack now contains: Raw, Uniq(x), ...
141   let y = unsafe { & *raw }; // Now memory gets frozen (recording the timestamp)
142   let _val = *y; // Okay because memory was frozen since `y` was created
143   *x = 3; // This "reactivates" `x` by unfreezing and popping the stack.
144   let z = &*x; // Now memory gets frozen *again*
145   *y // This is UB! Memory has been frozen strictly after `y` got created.
146 }
147 {% endhighlight %}
148
149 Shared references with interior mutability do not really have any restrictions in terms of what can happen to memory, so we treat them basically like raw pointers.
150
151 ### 2.3 Recap
152
153 For every location in memory, we keep track of a stack of borrows (`Uniq(_)` or `Raw`), and potentially "top off" this stack by freezing the location.
154 A frozen location is never written to, and no `Uniq` is pushed.
155
156 Whenever a mutable reference is created, a matching `Uniq` is pushed onto the stack for every location "covered by" the reference -- i.e., the locations that would be accessed when the reference is used (starting at where it points to, and going on for `size_of_val` many bytes).
157 Whenever a shared reference is created, if there is no interior mutability, we freeze the locations if they are not already frozen.
158 If there is interior mutability, we just push a `Raw`.
159 Whenever a raw pointer is created from a mutable reference, we push a `Raw`.
160 (Nothing happens when a raw pointer is created from a shared reference.)
161
162 A mutable reference `x` is "active" for a location if that location is not frozen and `Uniq(x)` is on top of the stack.
163 A shared reference without interior mutability is active if the location is frozen at least since the location was created.
164 A shared reference with interior mutability is active is `Raw` is on top of the stack.
165
166 Whenever a reference is used to do something (anything), we make sure that it is active again for all locations that it covers; this can involve unfreezing and popping the stack.
167 If it is not possible to reactivate the reference this way, we have UB.
168
169 **Update:** I previously talked about "activating" the reference instead of "reactivating it"; I decided to change terminology to make it clearer that this is an old reference being used again, so it must be on the stack already (but might not be at the top). **/Update**
170
171 ## 3 Tracking Borrows
172
173 So far, I have just been assuming that we can somehow keep a connection between a reference like `x` in the code above, and an item `Uniq(x)` on the stack.
174 I also said we are keeping track of when a shared reference was created.
175 To realize this, we need to somehow have information "tagged" to the reference.
176 In particular, notice that `x` and `y` in the first example have the same address.
177 If we compared them as raw pointers, they would turn out equal.
178 And yet, it makes a huge difference if we use `x` or `y`!
179
180 If you read my previous post on [why pointers are complicated]({% post_url 2018-07-24-pointers-and-bytes %}), this should not come as too much of a surprise.
181 There is more to a pointer, or a reference (I am using these terms mostly interchangeably), than the address in memory that it points to.
182
183 For the purpose of this model, we assume that a value of reference type consists of two parts: An address in memory, and a tag used to store the time when the reference was created.
184 "Time" here is a rather abstract notion, we really just need some counter that we bump up every time a new reference is created.
185 This gives us a unique ID for each mutable reference -- and, as we have seen, for shared references we actually exploit the fact that IDs are handed out in increasing order
186 (so that we can test if a reference was created before or after a location was frozen).
187 So, we can actually treat mutable and shard references uniformly in that both just record, in their tag, the time at which they were created.
188
189 Whenever I said above that we have `Uniq(x)` on the stack, what I really meant is that we have `Uniq(t_x)` on the stack, where `t_x` is some clock value, and that the "tag" of `x` is `t_x`.
190 For the sake of readability, I will continue to use the `Uniq(x)` notation below.
191
192 Since raw pointers are not tracked, we can erase the tag when casting a reference to a raw pointer.
193 This means our tag does not interfere with pointer-integer casts, which means there are a whole bunch of complicated questions we do not have to worry about. :)
194
195 Of course, these tags do not exist on real hardware.
196 But that is besides the point.
197 When *specifying* program behavior, we can work with an ["instrumented machine"]({% post_url 2017-06-06-MIR-semantics %}) that has extra state which is not present on the real machine, as long as we only use that extra state to define whether a program is UB or not:
198 On real hardware, we can ignore programs that are UB (they may just do whatever), so the extra state does not matter.
199
200 Tags are something I wanted to avoid in "Types as Contracts" -- that was one of the initial design constraints I had put upon myself, in the hope of avoiding the trouble coming with "complicated pointers".
201 However, I now came to the conclusion that tagging pointers is a price worth paying if it means we can make lifetimes irrelevant.
202
203 ## 4 Retagging and Barriers
204
205 I hope you now have a clear idea of the basic structure of the model I am proposing: The stack of borrows, the freeze flag, and references tagged with the time at which they got created.
206 The full model is not quite as simple, but it is not much more complicated either.
207 We need to add just two more concepts: Retagging and barriers.
208
209 ### 4.1 Retagging
210
211 Remember that every time we create a mutable borrow, we assign it the current
212 clock values as its tag.  Since the tag can never be changed, this means two
213 different variables can never have the same tag -- right?  Well, unfortunately,
214 things are not so simple: Using
215 e.g. [`transmute_copy`](https://doc.rust-lang.org/stable/std/mem/fn.transmute_copy.html)
216 or a `union`, one can make a copy of a reference in a way that Rust does not
217 even notice.
218
219 Still, we would like to make statements about code like this:
220 {% highlight rust %}
221 fn demo4(x: &mut i32, y: &mut i32) -> i32 {
222   *x = 42;
223   *y = 7;
224   *x // Will load 42! We can optimize away the load.
225 }
226 {% endhighlight %}
227 The trouble is, we cannot prevent the outside world from passing bogus `&mut` that have the same tag.
228 Does this mean we are back to square one in terms of making aliased mutable references UB?
229 Lucky enough, we are not! We have a lot of machinery at our disposal, we just have to tweak it a little.
230
231 What we will do is, every time a reference comes "into" our function (this can be a function argument, but also loading it from memory or getting it as the return value of some other function), we perform "retagging":
232 We change the tags of the mutable references to the current clock value, bumping up the clock after every tag we assign, and then we push those new tags on top of the borrow stack.
233 This way, we can know -- without making any assumptions about foreign code -- that all references have distinct IDs.
234 In particular, two different references can never be both "active" for the same location at the same time.
235
236 With this additional step, it is now easy to argue that `demo4` above is UB when `x` and `y` alias, no matter their initial tag:
237 After using `x`, we know it is active.
238 Next we use and reactivate `y`, which has to pop `Uniq(x)` as they have distinct tags.
239 Finally, we use `x` again even though it is no longer in the stack, triggering UB.
240 (A `Uniq` is only ever pushed when it is created, so it is never in the stack more than once.)
241
242 ### 4.2 Barriers
243
244 There is one more concept I would like to add: Barriers.
245 The model would make a lot of sense even without barriers -- but adding barriers rules out some more behavior that I do not think we want to allow.
246 It is also needed to explain why we can put the [`noalias` parameter attribute](https://llvm.org/docs/LangRef.html#parameter-attributes) on our functions when generating LLVM IR.
247
248 Consider the following code:
249 {% highlight rust %}
250 fn demo5(x: &mut i32, y: usize) {
251   *x = 42;
252   foo(y);
253 }
254
255 fn foo(y: usize) {
256   let y = unsafe { &mut *(y as *mut i32) };
257   *y = 7;
258 }
259 {% endhighlight %}
260 The question is: Can we reorder the `*x = 42;` down to the end of `demo5`?
261 Notice that we are *not* using `x` again, so we cannot assume that `x` is active at the end of `demo5`!
262 This is the usual trouble with access-based models.
263
264 However, someone might conceivably call `demo5` with `y` being `x as *mut _ as usize`, which means reordering could change program behavior.
265 To fix this, we have to make sure that if someone actually calls `demo5` this way, we have UB *even though* `x` is not used again.
266
267 To this end, I propose to turn the dial a little more towards a validity-based model by imposing some extra constraints.
268 We want to ensure that turning the integer `y` into a reference does not pop `x` from the stack and continue executing the program (we want UB instead).
269 This could happen if the stack contained, somewhere, a `Raw`.
270 Remember that we do not tag raw pointers, so when a raw pointer was involved in creating `x`, that `Raw` item will still be on the stack, enabling any raw pointer to be used to access this location.
271 This is sometimes crucial, but in this case, `demo5` should be able to prevent those old historic borrows involved in creating `x` from being reactivated.
272
273 The idea is to put a "barrier" into the stack of all function arguments when `demo5` gets called, and to make it UB to pop that barrier from the stack before `demo5` returns.
274 This way, all the borrows further down in the stack (below `Uniq(x)`) are temporarily disabled and cannot be reactivated while `demo5` runs.
275 This means that even if `y` happens to be the memory address `x` points to, it is UB to cast `y` to a reference because the `Raw` item cannot be reactivated.
276
277 Another way to think about barriers is as follows:
278 The model generally ignores lifetimes and does not know how long they last.
279 All we know is that when a reference is used, its lifetime must be ongoing, so we say that is when we reactivate the borrow.
280 On top of this, barriers encode the fact that, when a reference is passed as an argument to a function, then its lifetime (whatever it is) extends beyond the current function call.
281 In our example, this means that no borrow further up the stack (these are the borrows with even longer lifetimes) can be used while `demo5` is running.
282
283 A nice side-effect of barriers in combination with renumbering is that even if `demo4` from the previous subsection would not use its arguments at all, it would *still* be UB to call it with two aliasing references:
284 When renumbering `x`, we are pushing a barrier. Renumbering `y` would attempt to reactivate `Uniq(y)`, but that can only be behind the barrier, so it cannot be reactivated.
285
286 ## 5 The Model in Code
287
288 Now we have everything together.
289 Instead of giving another recap, I will try to give an alternative, more precise description of the model in the form of pseudo Rust code.
290 This is essentially a draft of the code that will hopefully be in Miri soon, to actually dynamically track the borrow stack and enforce the rules.
291 This is also how I go about developing such models -- I use some form of pseudo-Rust, which I find it easier to be precise in than pure English.
292 Some details have been omitted in the high-level description so far, they should all be in this code.
293
294 If you are only interested in the high-level picture, feel free to skip to the end.
295 The rest of this is more like a specification than an explanatory blog post.
296 The nice thing is that even with the spec, this post is still shorter than the one introducing "Types as Contracts". :)
297
298 ### 5.1 Per-Location Operations
299
300 Imagine we have a type `MemoryByte` storing the per-location information in memory.
301 This is where we put the borrow stack and the information about freezing:
302
303 {% highlight rust %}
304 /// Information about a potentially mutable borrow
305 enum Mut {
306   /// A unique, mutable reference
307   Uniq(Timestamp),
308   /// Any raw pointer, or a shared borrow with interior mutability
309   Raw,
310 }
311 /// Information about any kind of borrow
312 enum Borrow {
313   /// A mutable borrow, a raw pointer, or a shared borrow with interior mutability
314   Mut(Mut),
315   /// A shared borrow without interior mutability
316   Frz(Timestamp)
317 }
318 /// An item in the borrow stack
319 enum BorStackItem {
320   /// Defines which references are permitted to mutate *if* the location is not frozen
321   Mut(Mut),
322   /// A barrier, tracking the function it belongs to by its index on the call stack
323   FnBarrier(usize)
324 }
325
326 struct MemoryByte {
327   borrows: Vec<BorStackItem>, // used as a stack
328   frz_since: Option<Timestamp>,
329   /* More fields, to store the actual value and what else might be needed */
330 }
331 {% endhighlight %}
332
333 Next, we define some per-location operations that we will use later to define what happens when working with references.
334 Below, `assert!` is used for things that should always be true because of interpreter invariants (i.e., Miri will ICE if they fail to hold), and `bail!` is used to indicate that the program has UB.
335
336 {% highlight rust %}
337 impl MemoryByte {
338
339   /// Check if the given borrow may be used on this location.
340   fn check(&self, bor: Borrow) → bool {
341     match bor {
342       Frz(acc_t) =>
343         // Must be frozen at least as long as the `acc_t` says.
344         self.frz_since.map_or(false, |loc_t| loc_t <= acc_t),
345       Mut(acc_m) =>
346         // Raw pointers are fine with frozen locations. This is important because &Cell is raw!
347         if self.frozen_since.is_some() {
348           acc_m.is_raw()
349         } else {
350           self.borrows.last().map_or(false, |loc_itm| loc_itm == Mut(acc_m))
351         }
352     }
353   }
354
355   /// Reactivate the given existing borrow for this location, fail if that is not possible.
356   fn reactivate(&mut self, bor: Borrow) {
357     // Do NOT change anything if `bor` is already active -- in particular, if
358     // it is a `Mut(Raw)` and we are frozen.
359     if self.check(bor) { return; }
360     let acc_m = match bor {
361       Frz(acc_t) => bail!("Location should be frozen but it is not"),
362       Mut(acc_m) => acc_m,
363     };
364     // We definitely have to unfreeze this, even if we use the topmost item.
365     self.frozen_since = None;
366     // Pop until we see the one we are looking for.
367     while let Some(itm) = self.borrows.last() {
368       match itm {
369         FnBarrier(_) => {
370           bail!("Trying to reactivate a borrow that lives behind a barrier");
371         }
372         Mut(loc_m) => {
373           if loc_m == acc_m { return; }
374           self.borrows.pop();
375         }
376       }
377     }
378     bail!("Borrow-to-reactivate does not exist on the stack");
379   }
380
381   /// Initiate the given (new) borrow for the location.
382   /// This is "pushing to the stack", except that it also handles initiating a `Frz`.
383   fn initiate(&mut self, bor: Borrow) {
384     match bor {
385       Frz(t) => {
386         if self.frozen_since.is_none() {
387           self.frozen_since = Some(t);
388         }
389       }
390       Mut(m) => {
391         if m.is_uniq() && self.frozen_since.is_some() {
392           bail!("Must not initiate Uniq when frozen!");
393         }
394         self.borrows.push(Mut(m));
395       }
396     }
397   }
398
399   /// Reset the borrow tracking for this location.
400   fn reset(&mut self) {
401     if self.borrows.iter().any(|itm| if let FnBarrier(_) = item { true } else { false }) {
402       assert!("Cannot reset while there are barriers");
403     }
404     self.frozen_since = None;
405     self.borrows.clear();
406   }
407   
408 }
409 {% endhighlight %}
410
411 ### 5.2 MIR operations
412
413 Finally, we enhance some MIR operations with bookkeeping, following the model I described above.
414 This is where the code gets more "pseudo" and less Rust. ;)
415
416 For each of these operation, we iterate over all affected locations; let us call the loop variable `loc` of type `MemoryByte`.
417 We also have a variable `tag` with the tag of the pointer we are operating on (loading, or storing, or casting to a raw pointer, ...).
418
419 Moreover, we have a boolean variable `in_unsafe_cell` indicating whether, according to the type of the pointer, the location we are currently working on is covered by an [`UnsafeCell`](https://doc.rust-lang.org/stable/std/cell/struct.UnsafeCell.html).
420 (This realizes the conditions checking whether we have interior mutability or not.)
421 For example, in `&Cell<i32>`, all 4 locations are inside an `UnsafeCell`.
422 However, in `&(i32, Cell<i32>)`, only the last 4 of the 8 covered locations are inside an `UnsafeCell`.
423
424 Finally, given a reference type, a tag, and whether we are inside an `UnsafeCell`, we can compute the matching `Borrow`:
425 Mutable references use `Mut(Uniq(tag))`, shared references in an `UnsafeCell` use `Mut(Raw)` and other shared references use `Frz(tag)`.
426 We use `bor` to refer to the `Borrow` of the pointer we are working on.
427
428 Now we can look at what happens for each operation.
429
430 * Using a raw pointer directly is desugared to creating a shared reference (when reading) or a mutable reference (when writing), and using that. The appropriate steps below apply.
431 * Any time we use a (mutable or shared) reference to access memory, and any time we pass a reference to "the outside world" (passing it to a function, storing it in memory, returning it to our caller; also below structs or enums but not below unions or pointer indirectons), we reactivate.
432   - `loc.reactivate(borrow)`.
433 * Any time a *new* reference is created (any time we run an expression `&mut foo` or `&foo`), we (re)borrow.
434   - Bump up the clock, and remember the old time as `new_tag`.
435   - Compute `new_bor` from `new_tag` and the type of the reference being created.
436   - `if loc.check(new_bor) {`
437     * The new borrow is already active! This can happen because a mutable reference can be shared multiple times. We do not do anything else.
438       As a special exception, we do *not* reactivate `bor` even though it is "used", because that would unfreeze the location!
439
440     `} else {`
441     * We might be creating a reference to a local variable. In that case, `loc.reset()`. Otherwise, `reactivate(bor)`.
442     * `initiate(new_bor)`
443
444     `}`
445   - Use `new_tag` for the new reference.
446 * Any time a reference is passed to us from "the outside world" (as function argument, loaded from memory, or returned from a callee; also below structs or enums but not below unions or pointer indirectons), we retag.
447   - Bump up the clock, and remember the old time as `new_tag`.
448   - Compute `new_bor` from `new_tag` and the type of the reference being created.
449   - `reactivate(bor)`.
450   - If this is a function argument coming in: `loc.borrows.push(FnBarrier(stack_height))`.
451   - `initiate(new_bor)`. Note that this is a NOP if `new_bor` is already active -- in particular, if the location is frozen and this is a shared reference with interior mutability, we do *not* push anything on top of the barrier. This is important, because any reactivation that unfreezes this location must lead to UB while the barrier is still present.
452   - Change reference tag to `new_tag`.
453 * Any time a raw pointer is created from a reference, we might have to do a raw reborrow.
454   - `reactivate(bor)`.
455   - `initiate(Mut(Raw))`. This is a NOP when coming from a shared reference.
456 * Any time a function returns, we have to clean up the barriers.
457   - Iterate over all of memory and remove the matching `FnBarrier`. This is where the "stack" becomes a bit of a lie, because we also remove barriers from the middle of a stack.<br>
458     This could be optimized by adding an indirection, so we just have to record somewhere that this function call has ended.
459 * Any time memory is deallocated, this counts as mutation, so the usual rules for that apply. After that, the stacks of the deallocated bytes must not contain any barriers.
460
461
462 If you want to test your own understanding of "Stacked Borrows", I invite you to go back to [Section 2.2 of "Types as Contracts"]({% post_url 2017-07-17-types-as-contracts %}#22-examples) and look at the three examples here.
463 Ignore the `Validate` calls, that part is no longer relevant.
464 These are examples of optimizations we would like to be valid, and in fact all three of them are still valid with "Stacked Borrows".
465 Can you argue why that is the case?
466
467 ## Summary
468
469 I have described (yet) another Rust memory model that defines when a reference may be used to perform which memory operations.
470 The main design constraint of this model is that lifetimes should not matter for program execution.
471 To my own surprise, the model actually ended up being fairly simple, all things considered.
472
473 I think I covered most of the relevant features, though I will have to take a closer look at two-phase borrows and see if they need some further changes to the model.
474
475 Of course, now the big question is whether this model actually "works" -- does it permit all the code we want to permit (does it even permit all safe code), and does it rule out enough code such that we can get useful optimizations?
476 I hope to explore this question further in the following weeks by implementing a dynamic checker to test the model on real code.
477 It is just easier to answer these questions when you do not have to *manually* reevaluate all examples after every tiny change.
478 However, I can always use more examples, so if you think you found some interesting or surprising corner case, please let me know!
479
480 As always, if you have any questions or comments, feel free to [ask in the forums](https://internals.rust-lang.org/t/stacked-borrows-an-aliasing-model-for-rust/8153).