Thank you, Rust standard library maintainers, for making it very easy for me to contribute `BinaryHeap::peek_mut` to the stdlib, which landed in stable today!
This summer I was working on a userspace network I/O scheduler in Rust, and to avoid allocations, modifying the top element in the heap in-place was necessary. It dramatically improved performance of my scheduler.
I imagine if every item in the heap is a queue itself, you could use peek mut to get an item off the current max queue. After the modification, the former max element is sifted down to account for it's (probably) changed key.
The documentation really should mention the resifting, and why this is useful. It only mentions that the heap may be inconsistent if the `PeekMut` isn't properly dropped, without explaining why.
It's basically replacing the former (never stabilized) `push_pop` and `replace`, which Python folks can relate to similar methods in their `heapq`, for instance. With separate `push` and `pop` calls, the heap must be sifted twice, but with `peek_mut` you can update the head in-place and sift only once.
