Skip to content

Commit

Permalink
Auto merge of #34520 - Manishearth:fix-unsafecell-docs, r=steveklabnik
Browse files Browse the repository at this point in the history
Clarify UnsafeCell docs; fix #34496

None
  • Loading branch information
bors authored Aug 4, 2016
2 parents 0a3180b + 3873402 commit 40f3ee2
Showing 1 changed file with 19 additions and 0 deletions.
19 changes: 19 additions & 0 deletions src/libcore/cell.rs
Original file line number Diff line number Diff line change
Expand Up @@ -847,6 +847,20 @@ impl<'b, T: ?Sized + Unsize<U>, U: ?Sized> CoerceUnsized<RefMut<'b, U>> for RefM
/// The `UnsafeCell<T>` type is the only legal way to obtain aliasable data that is considered
/// mutable. In general, transmuting an `&T` type into an `&mut T` is considered undefined behavior.
///
/// The compiler makes optimizations based on the knowledge that `&T` is not mutably aliased or
/// mutated, and that `&mut T` is unique. When building abstractions like `Cell`, `RefCell`,
/// `Mutex`, etc, you need to turn these optimizations off. `UnsafeCell` is the only legal way
/// to do this. When `UnsafeCell<T>` is immutably aliased, it is still safe to obtain a mutable
/// reference to its interior and/or to mutate it. However, it is up to the abstraction designer
/// to ensure that no two mutable references obtained this way are active at the same time, and
/// that there are no active mutable references or mutations when an immutable reference is obtained
/// from the cell. This is often done via runtime checks.
///
/// Note that while mutating or mutably aliasing the contents of an `& UnsafeCell<T>` is
/// okay (provided you enforce the invariants some other way); it is still undefined behavior
/// to have multiple `&mut UnsafeCell<T>` aliases.
///
///
/// Types like `Cell<T>` and `RefCell<T>` use this type to wrap their internal data.
///
/// # Examples
Expand Down Expand Up @@ -916,6 +930,11 @@ impl<T> UnsafeCell<T> {
impl<T: ?Sized> UnsafeCell<T> {
/// Gets a mutable pointer to the wrapped value.
///
/// This can be cast to a pointer of any kind.
/// Ensure that the access is unique when casting to
/// `&mut T`, and ensure that there are no mutations or mutable
/// aliases going on when casting to `&T`
///
/// # Examples
///
/// ```
Expand Down

0 comments on commit 40f3ee2

Please sign in to comment.