(index<- ) ./libcore/ty.rs
git branch: * master 5200215 auto merge of #14035 : alexcrichton/rust/experimental, r=huonw
modified: Fri May 9 13:02:28 2014
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
4 //
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
10
11 //! Types dealing with unsafe actions.
12
13 use cast;
14 use kinds::marker;
15
16 /// Unsafe type that wraps a type T and indicates unsafe interior operations on the
17 /// wrapped type. Types with an `Unsafe<T>` field are considered to have an *unsafe
18 /// interior*. The Unsafe type is the only legal way to obtain aliasable data that is
19 /// considered mutable. In general, transmuting an &T type into an &mut T is considered
20 /// undefined behavior.
21 ///
22 /// Although it is possible to put an Unsafe<T> into static item, it is not permitted to
23 /// take the address of the static item if the item is not declared as mutable. This rule
24 /// exists because immutable static items are stored in read-only memory, and thus any
25 /// attempt to mutate their interior can cause segfaults. Immutable static items containing
26 /// Unsafe<T> instances are still useful as read-only initializers, however, so we do not
27 /// forbid them altogether.
28 ///
29 /// Types like `Cell` and `RefCell` use this type to wrap their internal data.
30 ///
31 /// Unsafe doesn't opt-out from any kind, instead, types with an `Unsafe` interior
32 /// are expected to opt-out from kinds themselves.
33 ///
34 /// # Example:
35 ///
36 /// ```rust
37 /// use std::ty::Unsafe;
38 /// use std::kinds::marker;
39 ///
40 /// struct NotThreadSafe<T> {
41 /// value: Unsafe<T>,
42 /// marker1: marker::NoShare
43 /// }
44 /// ```
45 ///
46 /// **NOTE:** Unsafe<T> fields are public to allow static initializers. It is not recommended
47 /// to access its fields directly, `get` should be used instead.
48 #[lang="unsafe"]
49 pub struct Unsafe<T> {
50 /// Wrapped value
51 pub value: T,
52
53 /// Invariance marker
54 pub marker1: marker::InvariantType<T>
55 }
56
57 impl<T> Unsafe<T> {
58
59 /// Static constructor
60 pub fn new(value: T) -> Unsafe<T> {
61 Unsafe{value: value, marker1: marker::InvariantType}
62 }
63
64 /// Gets a mutable pointer to the wrapped value
65 #[inline]
66 pub unsafe fn get(&self) -> *mut T { cast::transmute_mut_unsafe(&self.value) }
67
68 /// Unwraps the value
69 #[inline]
70 pub unsafe fn unwrap(self) -> T { self.value }
71 }