Skip to content
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

Remove weird Cell example from InvariantType docs (attempt #2) #21995

Merged
merged 2 commits into from
Feb 7, 2015
Merged

Remove weird Cell example from InvariantType docs (attempt #2) #21995

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b6544fd
removed weird example
Feb 1, 2015
310ada0
added example back in, with a modified, (hopefully) improved description
Feb 6, 2015
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
11 changes: 6 additions & 5 deletions src/libcore/marker.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -311,16 +311,17 @@ impl<T: ?Sized> Clone for ContravariantType<T> {
///
/// # Example
///
/// The Cell type is an example which uses unsafe code to achieve
/// "interior" mutability:
/// The Cell type is an example of an `InvariantType` which uses unsafe
/// code to achieve "interior" mutability:
///
/// ```
/// struct Cell<T> { value: T }
/// ```
///
/// The type system would infer that `value` is only read here and
/// never written, but in fact `Cell` uses unsafe code to achieve
/// interior mutability.
/// The type system would infer that `value` is only read here
/// and never written, but in fact `Cell` uses unsafe code to achieve
/// interior mutability. In order to get correct behavior, the
/// `InvariantType` marker must be applied.
Copy link
Contributor

Choose a reason for hiding this comment

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

This is not strictly true. That is, all types must use unsafe code to achieve interior mutability. And if they do so, types should use an InvariantType marker (though this is likely to be replaced; see RFC rust-lang/rfcs#738). The only exception to that last rule is Cell, which has no marker because it is builtin to the compiler.

Copy link
Contributor

Choose a reason for hiding this comment

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

Let me put this another, hopefully clearer, way:

  1. UnsafeCell and its wrapper Cell are the best ways to have interior mutability. If you use those, you do not need any markers.
  2. Cell types are required if you are making some data that is truly interior to your struct (i.e., no pointer direction required to reach it) mutable. This is because the compiler has to know whether the interior of a struct is mutable for various safety checks relating to static data.
  3. You may need a marker if you have a pointer like *mut T that gets transmuted or cast in your code to *mut U and that U is mutated when only reachable through a shared reference. In that case, you want a marker InvariantType<U>, because the fact that U will be mutated cannot be observed from the type definition alone -- the compiler sees *mut T, but doesn't know that it will eventually be transmuted to *mut U.

I guess it depends on how one defined "interior" mutability. The only legal way to have some data that is contained within your struct be mutable via a shared reference is to use UnsafeCell, in which case

#[unstable(feature = "core",
reason = "likely to change with new variance strategy")]
#[lang="invariant_type"]
Expand Down