ThreadRng: fix use-after-free in TL-dtor; doc for sized iterators

[dhardy]

Fixes #1022. Fixes #968 (except for 0.7 branch).

Revisiting #968, exterior access via the rng() function is safe for variant (5). Performance impact is negligible (on next_u32 and next_u64 benchmarks). I also checked variant (4) which has a small impact.

All results are the best of three runs; even so 1% differences are easily within the margin of error.
Best runs before change:

test thread_rng_u32          ... bench:       3,074 ns/iter (+/- 261) = 1301 MB/s
test thread_rng_u64          ... bench:       4,132 ns/iter (+/- 257) = 1936 MB/s

With Rc<UnsafeCell<..>> (0.4%):

test thread_rng_u32          ... bench:       3,085 ns/iter (+/- 566) = 1296 MB/s
test thread_rng_u64          ... bench:       4,144 ns/iter (+/- 196) = 1930 MB/s

With Rc<RefCell<..>> (2.3% - 10%):

test thread_rng_u32          ... bench:       3,146 ns/iter (+/- 117) = 1271 MB/s
test thread_rng_u64          ... bench:       4,566 ns/iter (+/- 185) = 1752 MB/s

We could easily add a safe feature to opt-out of this unsafe code, but likely that's not sensible.

[vks]

Looks good!

[RalfJung]

I think there's a subtle safety argument here: the caller is required to stop using the return mutable reference before anyone else calls this method. That is crucial to avoid aliasing mutable references.

That might be worth documenting? In particular it might be worth making the function unsafe as it is not in general safe to use by arbitrary callers.

[dhardy]

You're right of course. It's not a public function so I didn't put much thought into its signature.

[vks]

I submitted #1037 to fix this.

[vks]

@RalfJung Which function should be unsafe?

[RalfJung]

(I answered there.)