marker.rs - source
Skip to main content core/ marker.rs 1 //! Primitive traits and types representing basic properties of types. 2 //! 3 //! Rust types can be classified in various useful ways according to 4 //! their intrinsic properties. These classifications are represented 5 //! as traits. 6 7 #![stable(feature = "rust1" , since = "1.0.0" )] 8 9 mod variance ; 10 11 #[unstable(feature = "phantom_variance_markers" , issue = "135806" )] 12 pub use self ::variance::{ 13 PhantomContravariant , PhantomContravariantLifetime , PhantomCovariant , PhantomCovariantLifetime , 14 PhantomInvariant , PhantomInvariantLifetime , Variance , variance , 15 }; 16 use crate ::cell::UnsafeCell ; 17 use crate ::clone::TrivialClone ; 18 use crate ::cmp ; 19 use crate ::fmt::Debug ; 20 use crate ::hash::{ Hash , Hasher }; 21 use crate ::pin::UnsafePinned ; 22 23 // NOTE: for consistent error messages between `core` and `minicore`, all `diagnostic` attributes 24 // should be replicated exactly in `minicore` (if `minicore` defines the item).
25 26 /// Implements a given marker trait for multiple types at the same time. 27 /// 28 /// The basic syntax looks like this: 29 /// ```ignore private macro 30 /// marker_impls! { MarkerTrait for u8, i8 } 31 /// ``` 32 /// You can also implement `unsafe` traits 33 /// ```ignore private macro 34 /// marker_impls! { unsafe MarkerTrait for u8, i8 } 35 /// ``` 36 /// Add attributes to all impls: 37 /// ```ignore private macro 38 /// marker_impls! { 39 /// #[allow(lint)] 40 /// #[unstable(feature = "marker_trait", issue = "none")] 41 /// MarkerTrait for u8, i8 42 /// } 43 /// ``` 44 /// And use generics: 45 /// ```ignore private macro 46 /// marker_impls! { 47 /// MarkerTrait for 48 /// u8, i8, 49 /// {T: PointeeSized} *const T, 50 /// {T: PointeeSized} *mut T, 51 /// {T: MarkerTrait} PhantomData<T>, 52 /// u32, 53 /// } 54 /// ``` 55 macro marker_impls { 56 ( $( #[$( $meta :tt) * ] )* $Trait :ident for $({$( $bounds :tt) * }) ? $T :ty $(, $( $rest :tt) * ) ? ) => { 57 $( #[$( $meta ) * ] )* impl < $($( $bounds ) * ) ? > $Trait for $T {} 58 marker_impls! { $( #[$( $meta ) * ] )* $Trait for $($( $rest ) * ) ? } 59 }, 60 ( $( #[$( $meta :tt) * ] )* $Trait :ident for ) => {}, 61 62 ( $( #[$( $meta :tt) * ] )* unsafe $Trait :ident for $({$( $bounds :tt) * }) ? $T :ty $(, $( $rest :tt) * ) ? ) => { 63 $( #[$( $meta ) * ] )* unsafe impl < $($( $bounds ) * ) ? > $Trait for $T {} 64 marker_impls! { $( #[$( $meta ) * ] )* unsafe $Trait for $($( $rest ) * ) ? } 65 }, 66 ( $( #[$( $meta :tt) * ] )* unsafe $Trait :ident for ) => {}, 67 } 68 69 /// Types that can be transferred across thread boundaries.
70 /// 71 /// This trait is automatically implemented when the compiler determines it's 72 /// appropriate. 73 /// 74 /// An example of a non-`Send` type is the reference-counting pointer 75 /// [`rc::Rc`][`Rc`]. If two threads attempt to clone [`Rc`]s that point to the same 76 /// reference-counted value, they might try to update the reference count at the 77 /// same time, which is [undefined behavior][ub] because [`Rc`] doesn't use atomic 78 /// operations.
Its cousin [`sync::Arc`][arc] does use atomic operations (incurring 79 /// some overhead) and thus is `Send`. 80 /// 81 /// See [the Nomicon](../../nomicon/send-and-sync.html) and the [`Sync`] trait for more details. 82 /// 83 /// [`Rc`]: ../../std/rc/struct.Rc.html 84 /// [arc]: ../../std/sync/struct.Arc.html 85 /// [ub]: ../../reference/behavior-considered-undefined.html 86 #[stable(feature = "rust1" , since = "1.0.0" )] 87 #[rustc_diagnostic_item = "Send" ] 88 #[diagnostic::on_unimplemented( 89 message = "`{Self}` cannot be sent between threads safely" , 90 label = "`{Self}` cannot be sent between threads safely" 91 )] 92 pub unsafe auto trait Send { 93 // empty.
94 } 95 96 #[stable(feature = "rust1" , since = "1.0.0" )] 97 impl <T: PointeeSized > ! Send for *const T {} 98 #[stable(feature = "rust1" , since = "1.0.0" )] 99 impl <T: PointeeSized > ! Send for *mut T {} 100 101 // Most instances arise automatically, but this instance is needed to link up `T: Sync` with 102 // `&T: Send` (and it also removes the unsound default instance `T Send` -> `&T: Send` that would 103 // otherwise exist).
104 #[stable(feature = "rust1" , since = "1.0.0" )] 105 unsafe impl <T: Sync + PointeeSized > Send for & T {} 106 107 /// Types with a constant size known at compile time. 108 /// 109 /// All type parameters have an implicit bound of `Sized`. The special syntax 110 /// `?Sized` can be used to remove this bound if it's not appropriate. 111 /// 112 /// ``` 113 /// # #![allow(dead_code)] 114 /// struct Foo<T>(T); 115 /// struct Bar<T: ?Sized>(T); 116 /// 117 /// // struct FooUse(Foo<[i32]>); // error: Sized is not implemented for [i32] 118 /// struct BarUse(Bar<[i32]>); // OK 119 /// ``` 120 /// 121 /// The one exception is the implicit `Self` type of a trait.
A trait does not 122 /// have an implicit `Sized` bound as this is incompatible with [trait object]s 123 /// where, by definition, the trait needs to work with all possible implementors, 124 /// and thus could be any size. 125 /// 126 /// Although Rust will let you bind `Sized` to a trait, you won't 127 /// be able to use it to form a trait object later: 128 /// 129 /// ``` 130 /// # #![allow(unused_variables)] 131 /// trait Foo { } 132 /// trait Bar: Sized { } 133 /// 134 /// struct Impl; 135 /// impl Foo for Impl { } 136 /// impl Bar for Impl { } 137 /// 138 /// let x: &dyn Foo = &Impl; // OK 139 /// // let y: &dyn Bar = &Impl; // error: the trait `Bar` cannot be made into an object 140 /// ``` 141 /// 142 /// [trait object]: ../../book/ch17-02-trait-objects.html 143 #[doc(alias = "?" , alias = "?Sized" )] 144 #[stable(feature = "rust1" , since = "1.0.0" )] 145 #[lang = "sized" ] 146 #[diagnostic::on_unimplemented( 147 message = "the size for values of type `{Self}` cannot be known at compilation time" , 148 label = "doesn't have a size known at compile-time" 149 )] 150 #[fundamental] // for Default, for example, which requires that `[T]: !Default` be evaluatable 151 #[rustc_specialization_trait] 152 #[rustc_deny_explicit_impl] 153 #[rustc_dyn_incompatible_trait] 154 // `Sized` being coinductive, despite having supertraits, is okay as there are no user-written impls, 155 // and we know that the supertraits are always implemented if the subtrait is just by looking at 156 // the builtin impls.
157 #[rustc_coinductive] 158 pub trait Sized : MetaSized { 159 // Empty. 160 } 161 162 /// Types with a size that can be determined from pointer metadata. 163 #[unstable(feature = "sized_hierarchy" , issue = "144404" )] 164 #[lang = "meta_sized" ] 165 #[diagnostic::on_unimplemented( 166 message = "the size for values of type `{Self}` cannot be known" , 167 label = "doesn't have a known size" 168 )] 169 #[fundamental] 170 #[rustc_specialization_trait] 171 #[rustc_deny_explicit_impl] 172 // `MetaSized` being coinductive, despite having supertraits, is okay for the same reasons as 173 // `Sized` above.
174 #[rustc_coinductive] 175 pub trait MetaSized : PointeeSized { 176 // Empty 177 } 178 179 /// Types that may or may not have a size. 180 #[unstable(feature = "sized_hierarchy" , issue = "144404" )] 181 #[lang = "pointee_sized" ] 182 #[diagnostic::on_unimplemented( 183 message = "values of type `{Self}` may or may not have a size" , 184 label = "may or may not have a known size" 185 )] 186 #[fundamental] 187 #[rustc_specialization_trait] 188 #[rustc_deny_explicit_impl] 189 #[rustc_coinductive] 190 pub trait PointeeSized { 191 // Empty 192 } 193 194 /// Types that can be "unsized" to a dynamically-sized type.
195 /// 196 /// For example, the sized array type `[i8; 2]` implements `Unsize<[i8]>` and 197 /// `Unsize<dyn fmt::Debug>`. 198 /// 199 /// All implementations of `Unsize` are provided automatically by the compiler. 200 /// Those implementations are: 201 /// 202 /// - Arrays `[T; N]` implement `Unsize<[T]>`. 203 /// - A type implements `Unsize<dyn Trait + 'a>` if all of these condi
The rest of this page is on the live site.