src/doc/nomicon/dropck.md

   1 % Drop Check
   2
   3 We have seen how lifetimes provide us some fairly simple rules for ensuring
   4 that never read dangling references. However up to this point we have only ever
   5 interacted with the *outlives* relationship in an inclusive manner. That is,
   6 when we talked about `'a: 'b`, it was ok for `'a` to live *exactly* as long as
   7 `'b`. At first glance, this seems to be a meaningless distinction. Nothing ever
   8 gets dropped at the same time as another, right? This is why we used the
   9 following desugarring of `let` statements:
  10
  11 ```rust,ignore
  12 let x;
  13 let y;
  14 ```
  15
  16 ```rust,ignore
  17 {
  18     let x;
  19     {
  20         let y;
  21     }
  22 }
  23 ```
  24
  25 Each creates its own scope, clearly establishing that one drops before the
  26 other. However, what if we do the following?
  27
  28 ```rust,ignore
  29 let (x, y) = (vec![], vec![]);
  30 ```
  31
  32 Does either value strictly outlive the other? The answer is in fact *no*,
  33 neither value strictly outlives the other. Of course, one of x or y will be
  34 dropped before the other, but the actual order is not specified. Tuples aren't
  35 special in this regard; composite structures just don't guarantee their
  36 destruction order as of Rust 1.0.
  37
  38 We *could* specify this for the fields of built-in composites like tuples and
  39 structs. However, what about something like Vec? Vec has to manually drop its
  40 elements via pure-library code. In general, anything that implements Drop has
  41 a chance to fiddle with its innards during its final death knell. Therefore
  42 the compiler can't sufficiently reason about the actual destruction order
  43 of the contents of any type that implements Drop.
  44
  45 So why do we care? We care because if the type system isn't careful, it could
  46 accidentally make dangling pointers. Consider the following simple program:
  47
  48 ```rust
  49 struct Inspector<'a>(&'a u8);
  50
  51 fn main() {
  52     let (inspector, days);
  53     days = Box::new(1);
  54     inspector = Inspector(&days);
  55 }
  56 ```
  57
  58 This program is totally sound and compiles today. The fact that `days` does
  59 not *strictly* outlive `inspector` doesn't matter. As long as the `inspector`
  60 is alive, so is days.
  61
  62 However if we add a destructor, the program will no longer compile!
  63
  64 ```rust,ignore
  65 struct Inspector<'a>(&'a u8);
  66
  67 impl<'a> Drop for Inspector<'a> {
  68     fn drop(&mut self) {
  69         println!("I was only {} days from retirement!", self.0);
  70     }
  71 }
  72
  73 fn main() {
  74     let (inspector, days);
  75     days = Box::new(1);
  76     inspector = Inspector(&days);
  77     // Let's say `days` happens to get dropped first.
  78     // Then when Inspector is dropped, it will try to read free'd memory!
  79 }
  80 ```
  81
  82 ```text
  83 <anon>:12:28: 12:32 error: `days` does not live long enough
  84 <anon>:12     inspector = Inspector(&days);
  85                                      ^~~~
  86 <anon>:9:11: 15:2 note: reference must be valid for the block at 9:10...
  87 <anon>:9 fn main() {
  88 <anon>:10     let (inspector, days);
  89 <anon>:11     days = Box::new(1);
  90 <anon>:12     inspector = Inspector(&days);
  91 <anon>:13     // Let's say `days` happens to get dropped first.
  92 <anon>:14     // Then when Inspector is dropped, it will try to read free'd memory!
  93           ...
  94 <anon>:10:27: 15:2 note: ...but borrowed value is only valid for the block suffix following statement 0 at 10:26
  95 <anon>:10     let (inspector, days);
  96 <anon>:11     days = Box::new(1);
  97 <anon>:12     inspector = Inspector(&days);
  98 <anon>:13     // Let's say `days` happens to get dropped first.
  99 <anon>:14     // Then when Inspector is dropped, it will try to read free'd memory!
 100 <anon>:15 }
 101 ```
 102
 103 Implementing Drop lets the Inspector execute some arbitrary code during its
 104 death. This means it can potentially observe that types that are supposed to
 105 live as long as it does actually were destroyed first.
 106
 107 Interestingly, only generic types need to worry about this. If they aren't
 108 generic, then the only lifetimes they can harbor are `'static`, which will truly
 109 live *forever*. This is why this problem is referred to as *sound generic drop*.
 110 Sound generic drop is enforced by the *drop checker*. As of this writing, some
 111 of the finer details of how the drop checker validates types is totally up in
 112 the air. However The Big Rule is the subtlety that we have focused on this whole
 113 section:
 114
 115 **For a generic type to soundly implement drop, its generics arguments must
 116 strictly outlive it.**
 117
 118 This rule is sufficient but not necessary to satisfy the drop checker. That is,
 119 if your type obeys this rule then it's definitely sound to drop. However
 120 there are special cases where you can fail to satisfy this, but still
 121 successfully pass the borrow checker. These are the precise rules that are
 122 currently up in the air.
 123
 124 It turns out that when writing unsafe code, we generally don't need to
 125 worry at all about doing the right thing for the drop checker. However there
 126 is one special case that you need to worry about, which we will look at in
 127 the next section.