1 // Copyright 2013 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
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.
11 #![allow(missing_docs)]
12 #![unstable(feature = "raw", issue = "27751")]
14 //! Contains struct definitions for the layout of compiler built-in types.
16 //! They can be used as targets of transmutes in unsafe code for manipulating
17 //! the raw representations directly.
19 //! Their definition should always match the ABI defined in `rustc::back::abi`.
25 /// The representation of a slice like `&[T]`.
27 /// This struct is guaranteed to have the layout of types like `&[T]`,
28 /// `&str`, and `Box<[T]>`, but is not the type of such slices
29 /// (e.g. the fields are not directly accessible on a `&[T]`) nor does
30 /// it control that layout (changing the definition will not change
31 /// the layout of a `&[T]`). It is only designed to be used by unsafe
32 /// code that needs to manipulate the low-level details.
34 /// However, it is not recommended to use this type for such code,
35 /// since there are alternatives which may be safer:
37 /// - Creating a slice from a data pointer and length can be done with
38 /// `std::slice::from_raw_parts` or `std::slice::from_raw_parts_mut`
39 /// instead of `std::mem::transmute`ing a value of type `Slice`.
40 /// - Extracting the data pointer and length from a slice can be
41 /// performed with the `as_ptr` (or `as_mut_ptr`) and `len`
44 /// If one does decide to convert a slice value to a `Slice`, the
45 /// `Repr` trait in this module provides a method for a safe
46 /// conversion from `&[T]` (and `&str`) to a `Slice`, more type-safe
47 /// than a call to `transmute`.
54 /// use std::raw::{self, Repr};
56 /// let slice: &[u16] = &[1, 2, 3, 4];
58 /// let repr: raw::Slice<u16> = slice.repr();
59 /// println!("data pointer = {:?}, length = {}", repr.data, repr.len);
67 impl<T> Copy for Slice<T> {}
68 impl<T> Clone for Slice<T> {
69 fn clone(&self) -> Slice<T> { *self }
72 /// The representation of a trait object like `&SomeTrait`.
74 /// This struct has the same layout as types like `&SomeTrait` and
75 /// `Box<AnotherTrait>`. The [Trait Objects chapter of the
76 /// Book][moreinfo] contains more details about the precise nature of
79 /// [moreinfo]: ../../book/trait-objects.html#representation
81 /// `TraitObject` is guaranteed to match layouts, but it is not the
82 /// type of trait objects (e.g. the fields are not directly accessible
83 /// on a `&SomeTrait`) nor does it control that layout (changing the
84 /// definition will not change the layout of a `&SomeTrait`). It is
85 /// only designed to be used by unsafe code that needs to manipulate
86 /// the low-level details.
88 /// There is no `Repr` implementation for `TraitObject` because there
89 /// is no way to refer to all trait objects generically, so the only
90 /// way to create values of this type is with functions like
91 /// `std::mem::transmute`. Similarly, the only way to create a true
92 /// trait object from a `TraitObject` value is with `transmute`.
94 /// Synthesizing a trait object with mismatched types—one where the
95 /// vtable does not correspond to the type of the value to which the
96 /// data pointer points—is highly likely to lead to undefined
107 /// // an example trait
109 /// fn bar(&self) -> i32;
111 /// impl Foo for i32 {
112 /// fn bar(&self) -> i32 {
117 /// let value: i32 = 123;
119 /// // let the compiler make a trait object
120 /// let object: &Foo = &value;
122 /// // look at the raw representation
123 /// let raw_object: raw::TraitObject = unsafe { mem::transmute(object) };
125 /// // the data pointer is the address of `value`
126 /// assert_eq!(raw_object.data as *const i32, &value as *const _);
129 /// let other_value: i32 = 456;
131 /// // construct a new object, pointing to a different `i32`, being
132 /// // careful to use the `i32` vtable from `object`
133 /// let synthesized: &Foo = unsafe {
134 /// mem::transmute(raw::TraitObject {
135 /// data: &other_value as *const _ as *mut (),
136 /// vtable: raw_object.vtable
140 /// // it should work just like we constructed a trait object out of
141 /// // `other_value` directly
142 /// assert_eq!(synthesized.bar(), 457);
145 #[derive(Copy, Clone)]
146 pub struct TraitObject {
151 /// This trait is meant to map equivalences between raw structs and their
152 /// corresponding rust values.
153 pub unsafe trait Repr<T> {
154 /// This function "unwraps" a rust value (without consuming it) into its raw
155 /// struct representation. This can be used to read/write different values
156 /// for the struct. This is a safe method because by default it does not
157 /// enable write-access to the fields of the return value in safe code.
159 fn repr(&self) -> T { unsafe { mem::transmute_copy(&self) } }
162 unsafe impl<T> Repr<Slice<T>> for [T] {}
163 unsafe impl Repr<Slice<u8>> for str {}