---

yaml
---
r: 157471
b: refs/heads/snap-stage3
c: 8adfd02
h: refs/heads/master
i:
  157469: fcc758f
  157467: 90d7062
  157463: 9362587
  157455: 6e1e885
  157439: f3eba8f
v: v3

Author: Julian Orth

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: 065caf34f5ff29e04605f95d9c5d511af219439a
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
-refs/heads/snap-stage3: f037452447f5f46deb26e1c483fe88fb51a19198
+refs/heads/snap-stage3: 8adfd02368343636fe83b68e35c3b8e2db0f0e02
 refs/heads/try: 0ee4d8b0b112c608646fa75463ab4dc59132efd9
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b

branches/snap-stage3/src/doc/guide.md

@@ -3466,14 +3466,13 @@ for destroying that resource as well. Given that we're discussing pointers
 right now, let's discuss this in the context of memory allocation, though
 it applies to other resources as well.
 
-When you allocate heap memory, you need a mechanism to free that memory. Many
-languages use a garbage collector to handle deallocation. This is a valid,
-time-tested strategy, but it's not without its drawbacks: it adds overhead, and
-can lead to unpredictable pauses in execution. Because the programmer does not
-have to think as much about deallocation, allocation becomes something
-commonplace, leading to more memory usage. And if you need precise control
-over when something is deallocated, leaving it up to your runtime can make this
-difficult.
+When you allocate heap memory, you need a mechanism to free that memory.  Many
+languages let the programmer control the allocation, and then use a garbage
+collector to handle the deallocation. This is a valid, time-tested strategy,
+but it's not without its drawbacks. Because the programmer does not have to
+think as much about deallocation, allocation becomes something commonplace,
+because it's easy. And if you need precise control over when something is
+deallocated, leaving it up to your runtime can make this difficult.
 
 Rust chooses a different path, and that path is called **ownership**. Any
 binding that creates a resource is the **owner** of that resource.
@@ -3499,19 +3498,17 @@ memory. The length of time that the borrower is borrowing the pointer
 from you is called a **lifetime**.
 
 If two distinct bindings share a pointer, and the memory that pointer points to
-is immutable, then there are no problems. But if it's mutable, the result of
-changing it can vary unpredictably depending on who happens to access it first,
-which is called a **race condition**. To avoid this, if someone wants to mutate
-something that they've borrowed from you, you must not have lent out that
-pointer to anyone else.
+is immutable, then there are no problems. But if it's mutable, both pointers
+can attempt to write to the memory at the same time, causing a **race
+condition**. Therefore, if someone wants to mutate something that they've
+borrowed from you, you must not have lent out that pointer to anyone else.
 
 Rust has a sophisticated system called the **borrow checker** to make sure that
 everyone plays by these rules. At compile time, it verifies that none of these
-rules are broken. If our program compiles successfully, Rust can guarantee it
-is free of data races and other memory errors, and there is no runtime overhead
-for any of this. The borrow checker works only at compile time. If the borrow
-checker did find a problem, it will report a **lifetime error**, and your
-program will refuse to compile.
+rules are broken. If there's no problem, our program compiles successfully, and
+there is no runtime overhead for any of this. The borrow checker works only at
+compile time. If the borrow checker did find a problem, it will report a
+**lifetime error**, and your program will refuse to compile.
 
 That's a lot to take in. It's also one of the _most_ important concepts in
 all of Rust. Let's see this syntax in action:

branches/snap-stage3/src/liballoc/heap.rs

@@ -28,8 +28,8 @@ pub unsafe fn allocate(size: uint, align: uint) -> *mut u8 {
 /// size on the platform.
 ///
 /// The `old_size` and `align` parameters are the parameters that were used to
-/// create the allocation referenced by `ptr`. The `old_size` parameter may be
-/// any value in range_inclusive(requested_size, usable_size).
+/// create the allocation referenced by `ptr`. The `old_size` parameter may also
+/// be the value returned by `usable_size` for the requested size.
 #[inline]
 pub unsafe fn reallocate(ptr: *mut u8, old_size: uint, size: uint, align: uint) -> *mut u8 {
     imp::reallocate(ptr, old_size, size, align)
@@ -38,8 +38,8 @@ pub unsafe fn reallocate(ptr: *mut u8, old_size: uint, size: uint, align: uint)
 /// Extends or shrinks the allocation referenced by `ptr` to `size` bytes of
 /// memory in-place.
 ///
-/// If the operation succeeds, it returns `usable_size(size, align)` and if it
-/// fails (or is a no-op) it returns `usable_size(old_size, align)`.
+/// Returns true if successful, otherwise false if the allocation was not
+/// altered.
 ///
 /// Behavior is undefined if the requested size is 0 or the alignment is not a
 /// power of 2. The alignment must be no larger than the largest supported page
@@ -49,20 +49,20 @@ pub unsafe fn reallocate(ptr: *mut u8, old_size: uint, size: uint, align: uint)
 /// create the allocation referenced by `ptr`. The `old_size` parameter may be
 /// any value in range_inclusive(requested_size, usable_size).
 #[inline]
-pub unsafe fn reallocate_inplace(ptr: *mut u8, old_size: uint, size: uint, align: uint) -> uint {
+pub unsafe fn reallocate_inplace(ptr: *mut u8, old_size: uint, size: uint, align: uint) -> bool {
     imp::reallocate_inplace(ptr, old_size, size, align)
 }
 
 /// Deallocates the memory referenced by `ptr`.
 ///
 /// The `ptr` parameter must not be null.
 ///
-/// The `old_size` and `align` parameters are the parameters that were used to
-/// create the allocation referenced by `ptr`. The `old_size` parameter may be
-/// any value in range_inclusive(requested_size, usable_size).
+/// The `size` and `align` parameters are the parameters that were used to
+/// create the allocation referenced by `ptr`. The `size` parameter may also be
+/// the value returned by `usable_size` for the requested size.
 #[inline]
-pub unsafe fn deallocate(ptr: *mut u8, old_size: uint, align: uint) {
-    imp::deallocate(ptr, old_size, align)
+pub unsafe fn deallocate(ptr: *mut u8, size: uint, align: uint) {
+    imp::deallocate(ptr, size, align)
 }
 
 /// Returns the usable size of an allocation created with the specified the
@@ -102,8 +102,8 @@ unsafe fn exchange_malloc(size: uint, align: uint) -> *mut u8 {
 #[cfg(not(test))]
 #[lang="exchange_free"]
 #[inline]
-unsafe fn exchange_free(ptr: *mut u8, old_size: uint, align: uint) {
-    deallocate(ptr, old_size, align);
+unsafe fn exchange_free(ptr: *mut u8, size: uint, align: uint) {
+    deallocate(ptr, size, align);
 }
 
 // The minimum alignment guaranteed by the architecture. This value is used to
@@ -112,10 +112,10 @@ unsafe fn exchange_free(ptr: *mut u8, old_size: uint, align: uint) {
 #[cfg(any(target_arch = "arm",
           target_arch = "mips",
           target_arch = "mipsel"))]
-const MIN_ALIGN: uint = 8;
+static MIN_ALIGN: uint = 8;
 #[cfg(any(target_arch = "x86",
           target_arch = "x86_64"))]
-const MIN_ALIGN: uint = 16;
+static MIN_ALIGN: uint = 16;
 
 #[cfg(jemalloc)]
 mod imp {
@@ -178,16 +178,22 @@ mod imp {
     }
 
     #[inline]
-    pub unsafe fn reallocate_inplace(ptr: *mut u8, _old_size: uint, size: uint,
-                                     align: uint) -> uint {
+    pub unsafe fn reallocate_inplace(ptr: *mut u8, old_size: uint, size: uint,
+                                     align: uint) -> bool {
         let flags = align_to_flags(align);
-        je_xallocx(ptr as *mut c_void, size as size_t, 0, flags) as uint
+        let new_size = je_xallocx(ptr as *mut c_void, size as size_t, 0, flags) as uint;
+        // checking for failure to shrink is tricky
+        if size < old_size {
+            usable_size(size, align) == new_size as uint
+        } else {
+            new_size >= size
+        }
     }
 
     #[inline]
-    pub unsafe fn deallocate(ptr: *mut u8, old_size: uint, align: uint) {
+    pub unsafe fn deallocate(ptr: *mut u8, size: uint, align: uint) {
         let flags = align_to_flags(align);
-        je_sdallocx(ptr as *mut c_void, old_size as size_t, flags)
+        je_sdallocx(ptr as *mut c_void, size as size_t, flags)
     }
 
     #[inline]
@@ -207,8 +213,8 @@ mod imp {
 mod imp {
     use core::cmp;
     use core::ptr;
-    use core::ptr::RawPtr;
     use libc;
+    use libc_heap;
     use super::MIN_ALIGN;
 
     extern {
@@ -220,11 +226,7 @@ mod imp {
     #[inline]
     pub unsafe fn allocate(size: uint, align: uint) -> *mut u8 {
         if align <= MIN_ALIGN {
-            let ptr = libc::malloc(size as libc::size_t);
-            if ptr.is_null() {
-                ::oom();
-            }
-            ptr as *mut u8
+            libc_heap::malloc_raw(size)
         } else {
             let mut out = 0 as *mut libc::c_void;
             let ret = posix_memalign(&mut out,
@@ -240,11 +242,7 @@ mod imp {
     #[inline]
     pub unsafe fn reallocate(ptr: *mut u8, old_size: uint, size: uint, align: uint) -> *mut u8 {
         if align <= MIN_ALIGN {
-            let ptr = libc::realloc(ptr as *mut libc::c_void, size as libc::size_t);
-            if ptr.is_null() {
-                ::oom();
-            }
-            ptr as *mut u8
+            libc_heap::realloc_raw(ptr, size)
         } else {
             let new_ptr = allocate(size, align);
             ptr::copy_memory(new_ptr, ptr as *const u8, cmp::min(size, old_size));
@@ -254,13 +252,13 @@ mod imp {
     }
 
     #[inline]
-    pub unsafe fn reallocate_inplace(_ptr: *mut u8, old_size: uint, _size: uint,
-                                     _align: uint) -> uint {
-        old_size
+    pub unsafe fn reallocate_inplace(_ptr: *mut u8, old_size: uint, size: uint,
+                                     _align: uint) -> bool {
+        size == old_size
     }
 
     #[inline]
-    pub unsafe fn deallocate(ptr: *mut u8, _old_size: uint, _align: uint) {
+    pub unsafe fn deallocate(ptr: *mut u8, _size: uint, _align: uint) {
         libc::free(ptr as *mut libc::c_void)
     }
 
@@ -276,6 +274,7 @@ mod imp {
 mod imp {
     use libc::{c_void, size_t};
     use libc;
+    use libc_heap;
     use core::ptr::RawPtr;
     use super::MIN_ALIGN;
 
@@ -289,11 +288,7 @@ mod imp {
     #[inline]
     pub unsafe fn allocate(size: uint, align: uint) -> *mut u8 {
         if align <= MIN_ALIGN {
-            let ptr = libc::malloc(size as size_t);
-            if ptr.is_null() {
-                ::oom();
-            }
-            ptr as *mut u8
+            libc_heap::malloc_raw(size)
         } else {
             let ptr = _aligned_malloc(size as size_t, align as size_t);
             if ptr.is_null() {
@@ -306,11 +301,7 @@ mod imp {
     #[inline]
     pub unsafe fn reallocate(ptr: *mut u8, _old_size: uint, size: uint, align: uint) -> *mut u8 {
         if align <= MIN_ALIGN {
-            let ptr = libc::realloc(ptr as *mut c_void, size as size_t);
-            if ptr.is_null() {
-                ::oom();
-            }
-            ptr as *mut u8
+            libc_heap::realloc_raw(ptr, size)
         } else {
             let ptr = _aligned_realloc(ptr as *mut c_void, size as size_t,
                                        align as size_t);
@@ -322,13 +313,13 @@ mod imp {
     }
 
     #[inline]
-    pub unsafe fn reallocate_inplace(_ptr: *mut u8, old_size: uint, _size: uint,
-                                     _align: uint) -> uint {
-        old_size
+    pub unsafe fn reallocate_inplace(_ptr: *mut u8, old_size: uint, size: uint,
+                                     _align: uint) -> bool {
+        size == old_size
     }
 
     #[inline]
-    pub unsafe fn deallocate(ptr: *mut u8, _old_size: uint, align: uint) {
+    pub unsafe fn deallocate(ptr: *mut u8, _size: uint, align: uint) {
         if align <= MIN_ALIGN {
             libc::free(ptr as *mut libc::c_void)
         } else {
@@ -357,7 +348,7 @@ mod test {
             let ptr = heap::allocate(size, 8);
             let ret = heap::reallocate_inplace(ptr, size, size, 8);
             heap::deallocate(ptr, size, 8);
-            assert_eq!(ret, heap::usable_size(size, 8));
+            assert!(ret);
         }
     }
 

branches/snap-stage3/src/liballoc/lib.rs

@@ -54,8 +54,11 @@
 //!
 //! ## Heap interfaces
 //!
-//! The [`heap`](heap/index.html) module defines the low-level interface to the
-//! default global allocator. It is not compatible with the libc allocator API.
+//! The [`heap`](heap/index.html) and [`libc_heap`](libc_heap/index.html)
+//! modules are the unsafe interfaces to the underlying allocation systems. The
+//! `heap` module is considered the default heap, and is not necessarily backed
+//! by libc malloc/free.  The `libc_heap` module is defined to be wired up to
+//! the system malloc/free.
 
 #![crate_name = "alloc"]
 #![experimental]
@@ -87,6 +90,7 @@ pub use boxed as owned;
 // Heaps provided for low-level allocation strategies
 
 pub mod heap;
+pub mod libc_heap;
 
 // Primitive types using the heaps above
 

branches/snap-stage3/src/liballoc/libc_heap.rs

@@ -0,0 +1,48 @@
+// Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+
+//! The global (exchange) heap.
+
+use libc::{c_void, size_t, free, malloc, realloc};
+use core::ptr::{RawPtr, null_mut};
+
+/// A wrapper around libc::malloc, aborting on out-of-memory.
+#[inline]
+pub unsafe fn malloc_raw(size: uint) -> *mut u8 {
+    // `malloc(0)` may allocate, but it may also return a null pointer
+    // http://pubs.opengroup.org/onlinepubs/9699919799/functions/malloc.html
+    if size == 0 {
+        null_mut()
+    } else {
+        let p = malloc(size as size_t);
+        if p.is_null() {
+            ::oom();
+        }
+        p as *mut u8
+    }
+}
+
+/// A wrapper around libc::realloc, aborting on out-of-memory.
+#[inline]
+pub unsafe fn realloc_raw(ptr: *mut u8, size: uint) -> *mut u8 {
+    // `realloc(ptr, 0)` may allocate, but it may also return a null pointer
+    // http://pubs.opengroup.org/onlinepubs/9699919799/functions/realloc.html
+    if size == 0 {
+        free(ptr as *mut c_void);
+        null_mut()
+    } else {
+        let p = realloc(ptr as *mut c_void, size as size_t);
+        if p.is_null() {
+            ::oom();
+        }
+        p as *mut u8
+    }
+}

branches/snap-stage3/src/libcore/cell.rs

@@ -191,17 +191,6 @@ impl<T:Copy> Cell<T> {
             *self.value.get() = value;
         }
     }
-
-    /// Get a reference to the underlying `UnsafeCell`.
-    ///
-    /// This can be used to circumvent `Cell`'s safety checks.
-    ///
-    /// This function is `unsafe` because `UnsafeCell`'s field is public.
-    #[inline]
-    #[experimental]
-    pub unsafe fn as_unsafe_cell<'a>(&'a self) -> &'a UnsafeCell<T> {
-        &self.value
-    }
 }
 
 #[unstable = "waiting for `Clone` trait to become stable"]
@@ -317,17 +306,6 @@ impl<T> RefCell<T> {
             None => fail!("RefCell<T> already borrowed")
         }
     }
-
-    /// Get a reference to the underlying `UnsafeCell`.
-    ///
-    /// This can be used to circumvent `RefCell`'s safety checks.
-    ///
-    /// This function is `unsafe` because `UnsafeCell`'s field is public.
-    #[inline]
-    #[experimental]
-    pub unsafe fn as_unsafe_cell<'a>(&'a self) -> &'a UnsafeCell<T> {
-        &self.value
-    }
 }
 
 #[unstable = "waiting for `Clone` to become stable"]