Skip to content

rephrase UnsafeCell doc #48201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Mar 13, 2018
Merged

rephrase UnsafeCell doc #48201

Changes from 3 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
f1c1fc2
rephrase UnsafeCell doc
NovemberZulu Feb 14, 2018
b9b8249
fix tidy checks
NovemberZulu Feb 14, 2018
273166e
remove italic
NovemberZulu Feb 27, 2018
d9b8724
style fix
NovemberZulu Feb 27, 2018
50f5ea9
Simplify
NovemberZulu Feb 27, 2018
ff6754c
fix tidy checks
NovemberZulu Feb 27, 2018
78789ad
and some more tidy checks
NovemberZulu Feb 27, 2018
fe557ee
another rewrite
NovemberZulu Mar 8, 2018
fbcd2f5
tidy. Again
NovemberZulu Mar 8, 2018
55be283
and again :(
NovemberZulu Mar 8, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 9 additions & 8 deletions src/libcore/cell.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1164,11 +1164,12 @@ impl<'a, T: ?Sized + fmt::Display> fmt::Display for RefMut<'a, T> {
/// 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.
/// to do this. When `UnsafeCell<T>` itself is immutably aliased, it is still safe to obtain
/// a mutable reference to its interior and/or to mutate the interior. However, it is up to
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you reformat this as a list? Several of the entries are long, and the sentence becomes hard to follow.

/// the abstraction designer to ensure that no two mutable references obtained this way are active
/// at the same time, there are no active immutable reference when a mutable reference is obtained
Copy link
Member

@cramertj cramertj Feb 27, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These rules are kind of confusingly stated. I think it should be something like the following:
(1) While a mutable reference exists, no second reference or of any kind may exist.
(2) While a reference of any kind exists, all mutations must go through that reference. This means that mutations cannot occur while an immutable reference exists.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll try to merge three rules into one, so it will be easier to follow.

/// from the cell, and that there are no active mutable references or mutations when an immutable
/// reference is obtained. 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
Expand Down Expand Up @@ -1240,9 +1241,9 @@ 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`
/// Ensure that the access is unique (no active references, mutable or not)
/// when casting to `&mut T`, and ensure that there are no mutations
/// or mutable aliases going on when casting to `&T`
///
/// # Examples
///
Expand Down