Merge rayon-rs#702

702: Adds info about (lack of) object safety to `iter` module documentation. r=cuviper a=Qqwy

Because I spent quite a while yesterday and today tracking this problem down, I thought it might be an improvement to the documentation to mention that Rayon's ParallelIterator and friends are not object-safe (and why).

(c.f. rayon-rs#628)

Co-authored-by: Qqwy/Wiebe-Marten Wijnja <w-m@wmcode.nl>
Co-authored-by: Qqwy / Wiebe-Marten <w-m@wmcode.nl>

Author: bors[bot]

src/iter/mod.rs

@@ -72,6 +72,12 @@
 //! to mirror the unstable `std::ops::Try` with implementations for `Option` and
 //! `Result`, where `Some`/`Ok` values will let those iterators continue, but
 //! `None`/`Err` values will exit early.
+//!
+//! A note about object safety: It is currently _not_ possible to wrap
+//! a `ParallelIterator` (or any trait that depends on it) using a
+//! `Box<dyn ParallelIterator>` or other kind of dynamic allocation,
+//! because `ParallelIterator` is **not object-safe**.
+//! (This keeps the implementation simpler and allows extra optimizations.)
 
 use self::plumbing::*;
 use self::private::Try;