bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Shorten ownership safety discussion in read_volatile

Browse source 
Non-`Copy` types should not be in volatile memory.
This commit is contained in:
Dylan MacKenzie 2018-05-09 15:52:16 -07:00
parent e350ba48ed
commit 827251e92b
1 changed files with 15 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

23
src/libcore/ptr.rs
View file

@ -622,6 +622,11 @@ pub unsafe fn write_unaligned<T>(dst: *mut T, src: T) {
/// to not be elided or reordered by the compiler across other volatile
/// operations.
///
/// Memory read with `read_volatile` should almost always be written to using
/// [`write_volatile`].
///
/// [`write_volatile`]: ./fn.write_volatile.html
///
/// # Notes
///
/// Rust does not currently have a rigorously and formally defined memory model,
@ -644,16 +649,13 @@ pub unsafe fn write_unaligned<T>(dst: *mut T, src: T) {
///
/// * `src` must be properly aligned.
///
/// Additionally, if `T` is not [`Copy`], only the returned value *or* the
/// pointed-to value can be used or dropped after calling `read_volatile`.
/// `read_volatile` creates a bitwise copy of `T`, regardless of whether `T:
/// Copy`, which can result in undefined behavior if both copies are used.
/// Note that `*src = foo` counts as a use because it will attempt to drop the
/// value previously at `*src`. [`write_volatile`] can be used to overwrite
/// data without causing it to be dropped.
/// Like [`read`], `read_volatile` creates a bitwise copy of the pointed-to
/// object, regardless of whether `T` is [`Copy`]. Using both values can cause
/// undefined behavior. However, storing non-[`Copy`] data in I/O memory is
/// almost certainly incorrect.
///
/// [`Copy`]: ../marker/trait.Copy.html
/// [`write_volatile`]: ./fn.write_volatile.html
/// [`read`]: ./fn.read.html
///
/// # Examples
///
@ -680,6 +682,9 @@ pub unsafe fn read_volatile<T>(src: *const T) -> T {
/// to not be elided or reordered by the compiler across other volatile
/// operations.
///
/// Memory written with `write_volatile` should almost always be read from using
/// [`read_volatile`].
///
/// `write_volatile` does not drop the contents of `dst`. This is safe, but it
/// could leak allocations or resources, so care must be taken not to overwrite
/// an object that should be dropped.
@ -687,6 +692,8 @@ pub unsafe fn read_volatile<T>(src: *const T) -> T {
/// Additionally, it does not drop `src`. Semantically, `src` is moved into the
/// location pointed to by `dst`.
///
/// [`read_volatile`]: ./fn.read_volatile.html
///
/// # Notes
///
/// Rust does not currently have a rigorously and formally defined memory model,