rustacuda_core/memory/
mod.rs

1mod pointer;
2pub use self::pointer::*;
3
4use core::marker::PhantomData;
5use core::num::*;
6
7/// Marker trait for types which can safely be copied to or from a CUDA device.
8///
9/// A type can be safely copied if its value can be duplicated simply by copying bits and if it does
10/// not contain a reference to memory which is not accessible to the device. Additionally, the
11/// DeviceCopy trait does not imply copy semantics as the Copy trait does.
12///
13/// ## How can I implement DeviceCopy?
14///
15/// There are two ways to implement DeviceCopy on your type. The simplest is to use `derive`:
16///
17/// ```
18/// #[macro_use]
19/// extern crate rustacuda;
20///
21/// #[derive(Clone, DeviceCopy)]
22/// struct MyStruct(u64);
23///
24/// # fn main () {}
25/// ```
26///
27/// This is safe because the `DeviceCopy` derive macro will check that all fields of the struct,
28/// enum or union implement `DeviceCopy`. For example, this fails to compile, because `Vec` cannot
29/// be copied to the device:
30///
31/// ```compile_fail
32/// # #[macro_use]
33/// # extern crate rustacuda;
34/// #[derive(Clone, DeviceCopy)]
35/// struct MyStruct(Vec<u64>);
36/// # fn main () {}
37/// ```
38///
39/// You can also implement `DeviceCopy` unsafely:
40///
41/// ```
42/// use rustacuda::memory::DeviceCopy;
43///
44/// #[derive(Clone)]
45/// struct MyStruct(u64);
46///
47/// unsafe impl DeviceCopy for MyStruct { }
48/// # fn main () {}
49/// ```
50///
51/// ## What is the difference between `DeviceCopy` and `Copy`?
52///
53/// `DeviceCopy` is stricter than `Copy`. `DeviceCopy` must only be implemented for types which
54/// do not contain references or raw pointers to non-device-accessible memory. `DeviceCopy` also
55/// does not imply copy semantics - that is, `DeviceCopy` values are not implicitly copied on
56/// assignment the way that `Copy` values are. This is helpful, as it may be desirable to implement
57/// `DeviceCopy` for large structures that would be inefficient to copy for every assignment.
58///
59/// ## When can't my type be `DeviceCopy`?
60///
61/// Some types cannot be safely copied to the device. For example, copying `&T` would create an
62/// invalid reference on the device which would segfault if dereferenced. Generalizing this, any
63/// type implementing `Drop` cannot be `DeviceCopy` since it is responsible for some resource that
64/// would not be available on the device.
65pub unsafe trait DeviceCopy {
66    // Empty
67}
68
69macro_rules! impl_device_copy {
70    ($($t:ty)*) => {
71        $(
72            unsafe impl DeviceCopy for $t {}
73        )*
74    }
75}
76
77impl_device_copy!(
78    usize u8 u16 u32 u64 u128
79    isize i8 i16 i32 i64 i128
80    f32 f64
81    bool char
82
83    NonZeroU8 NonZeroU16 NonZeroU32 NonZeroU64 NonZeroU128
84);
85unsafe impl<T: DeviceCopy> DeviceCopy for Option<T> {}
86unsafe impl<L: DeviceCopy, R: DeviceCopy> DeviceCopy for Result<L, R> {}
87unsafe impl<T: ?Sized + DeviceCopy> DeviceCopy for PhantomData<T> {}
88unsafe impl<T: DeviceCopy> DeviceCopy for Wrapping<T> {}
89
90macro_rules! impl_device_copy_array {
91    ($($n:expr)*) => {
92        $(
93            unsafe impl<T: DeviceCopy> DeviceCopy for [T;$ n] {}
94        )*
95    }
96}
97
98impl_device_copy_array! {
99    1 2 3 4 5 6 7 8 9 10
100    11 12 13 14 15 16 17 18 19 20
101    21 22 23 24 25 26 27 28 29 30
102    31 32
103}
104unsafe impl DeviceCopy for () {}
105unsafe impl<A: DeviceCopy, B: DeviceCopy> DeviceCopy for (A, B) {}
106unsafe impl<A: DeviceCopy, B: DeviceCopy, C: DeviceCopy> DeviceCopy for (A, B, C) {}
107unsafe impl<A: DeviceCopy, B: DeviceCopy, C: DeviceCopy, D: DeviceCopy> DeviceCopy
108    for (A, B, C, D)
109{
110}
111unsafe impl<A: DeviceCopy, B: DeviceCopy, C: DeviceCopy, D: DeviceCopy, E: DeviceCopy> DeviceCopy
112    for (A, B, C, D, E)
113{
114}
115unsafe impl<A: DeviceCopy, B: DeviceCopy, C: DeviceCopy, D: DeviceCopy, E: DeviceCopy, F: DeviceCopy>
116    DeviceCopy for (A, B, C, D, E, F)
117{
118}
119unsafe impl<
120        A: DeviceCopy,
121        B: DeviceCopy,
122        C: DeviceCopy,
123        D: DeviceCopy,
124        E: DeviceCopy,
125        F: DeviceCopy,
126        G: DeviceCopy,
127    > DeviceCopy for (A, B, C, D, E, F, G)
128{
129}
130unsafe impl<
131        A: DeviceCopy,
132        B: DeviceCopy,
133        C: DeviceCopy,
134        D: DeviceCopy,
135        E: DeviceCopy,
136        F: DeviceCopy,
137        G: DeviceCopy,
138        H: DeviceCopy,
139    > DeviceCopy for (A, B, C, D, E, F, G, H)
140{
141}