src/docs/mut_from_ref.txt

   1 ### What it does
   2 This lint checks for functions that take immutable references and return
   3 mutable ones. This will not trigger if no unsafe code exists as there
   4 are multiple safe functions which will do this transformation
   5
   6 To be on the conservative side, if there's at least one mutable
   7 reference with the output lifetime, this lint will not trigger.
   8
   9 ### Why is this bad?
  10 Creating a mutable reference which can be repeatably derived from an
  11 immutable reference is unsound as it allows creating multiple live
  12 mutable references to the same object.
  13
  14 This [error](https://github.com/rust-lang/rust/issues/39465) actually
  15 lead to an interim Rust release 1.15.1.
  16
  17 ### Known problems
  18 This pattern is used by memory allocators to allow allocating multiple
  19 objects while returning mutable references to each one. So long as
  20 different mutable references are returned each time such a function may
  21 be safe.
  22
  23 ### Example
  24 ```
  25 fn foo(&Foo) -> &mut Bar { .. }
  26 ```