mirror of
https://github.com/google/comprehensive-rust.git
synced 2025-03-20 14:31:15 +02:00
0a1c30ef87
Attempt to address #1677. Expert review is needed. The new text is my best guess based on the original text and other explanations I could find online. A few things to note: * I'm trying to distinguish the future we return and the future we await. My assumption is that the stack contents goes to the future the code returns, not the future the code is awaiting. * Readers could be worried if they need to pin the code they write. I'm reassuring them that the borrow checks would normally catch bad references. * I'm intentionally avoiding the words that something is unsafe (or would be unsafe). The async Rust is safe. * I'm trying to be clear that `Pin` is a protective wrapper around a pointer, not a mechanism that changes the pointer or the pointed object. * Likewise, I don't want to give an impression that an unpinned pointer to a future is inherently unsafe or invalid. It just cannot be used to poll the future. * I dropped the vague mention of the "issues", as it probably refers to the issue with replacing a future (as opposed to resetting it in place). It's already mentioned in the notes further on this page. It affects pinning on stack only, `Box::pin()` can be replaced. Co-authored-by: Martin Geisler <martin@geisler.net>