---

yaml
---
r: 77021
b: refs/heads/snap-stage3
c: 6b23d20
h: refs/heads/master
i:
  77019: a8ad3e5
v: v3

Author: nikomatsakis

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: f1132496dddbdd88f321a7919eec3d65136b3f75
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
-refs/heads/snap-stage3: 0f6dd539488039cacef9646786039eb5213e6444
+refs/heads/snap-stage3: 6b23d20452ef7c2d2eb79baf074bcda04fad9a66
 refs/heads/try: ebfe63cd1c0b5d23f7ea60c69b4fde2e30cfd42a
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b

branches/snap-stage3/doc/rust.md

@@ -582,7 +582,7 @@ a referencing source file, or by the name of the crate itself.
 
 Each source file contains a sequence of zero or more `item` definitions,
 and may optionally begin with any number of `attributes` that apply to the containing module.
-Atributes on the anonymous crate module define important metadata that influences
+Attributes on the anonymous crate module define important metadata that influences
 the behavior of the compiler.
 
 ~~~~~~~~
@@ -1273,7 +1273,7 @@ since the typechecker checks that any type with an implementation of `Circle` al
 
 In type-parameterized functions,
 methods of the supertrait may be called on values of subtrait-bound type parameters.
-Refering to the previous example of `trait Circle : Shape`:
+Referring to the previous example of `trait Circle : Shape`:
 
 ~~~
 # trait Shape { fn area(&self) -> float; }
@@ -1914,7 +1914,7 @@ A field access on a record is an [lvalue](#lvalues-rvalues-and-temporaries) refe
 When the field is mutable, it can be [assigned](#assignment-expressions) to.
 
 When the type of the expression to the left of the dot is a pointer to a record or structure,
-it is automatically derferenced to make the field access possible.
+it is automatically dereferenced to make the field access possible.
 
 
 ### Vector expressions

branches/snap-stage3/doc/tutorial-ffi.md

@@ -19,6 +19,7 @@ extern {
     fn snappy_max_compressed_length(source_length: size_t) -> size_t;
 }
 
+#[fixed_stack_segment]
 fn main() {
     let x = unsafe { snappy_max_compressed_length(100) };
     println(fmt!("max compressed length of a 100 byte buffer: %?", x));
@@ -35,6 +36,11 @@ interfaces that aren't thread-safe, and almost any function that takes a pointer
 valid for all possible inputs since the pointer could be dangling, and raw pointers fall outside of
 Rust's safe memory model.
 
+Finally, the `#[fixed_stack_segment]` annotation that appears on
+`main()` instructs the Rust compiler that when `main()` executes, it
+should request a "very large" stack segment.  More details on
+stack management can be found in the following sections.
+
 When declaring the argument types to a foreign function, the Rust compiler will not check if the
 declaration is correct, so specifying it correctly is part of keeping the binding correct at
 runtime.
@@ -75,6 +81,8 @@ length is number of elements currently contained, and the capacity is the total
 the allocated memory. The length is less than or equal to the capacity.
 
 ~~~~ {.xfail-test}
+#[fixed_stack_segment]
+#[inline(never)]
 pub fn validate_compressed_buffer(src: &[u8]) -> bool {
     unsafe {
         snappy_validate_compressed_buffer(vec::raw::to_ptr(src), src.len() as size_t) == 0
@@ -86,6 +94,36 @@ The `validate_compressed_buffer` wrapper above makes use of an `unsafe` block, b
 guarantee that calling it is safe for all inputs by leaving off `unsafe` from the function
 signature.
 
+The `validate_compressed_buffer` wrapper is also annotated with two
+attributes `#[fixed_stack_segment]` and `#[inline(never)]`. The
+purpose of these attributes is to guarantee that there will be
+sufficient stack for the C function to execute. This is necessary
+because Rust, unlike C, does not assume that the stack is allocated in
+one continuous chunk. Instead, we rely on a *segmented stack* scheme,
+in which the stack grows and shrinks as necessary.  C code, however,
+expects one large stack, and so callers of C functions must request a
+large stack segment to ensure that the C routine will not run off the
+end of the stack.
+
+The compiler includes a lint mode that will report an error if you
+call a C function without a `#[fixed_stack_segment]` attribute. More
+details on the lint mode are given in a later section.
+
+You may be wondering why we include a `#[inline(never)]` directive.
+This directive informs the compiler never to inline this function.
+While not strictly necessary, it is usually a good idea to use an
+`#[inline(never)]` directive in concert with `#[fixed_stack_segment]`.
+The reason is that if a fn annotated with `fixed_stack_segment` is
+inlined, then its caller also inherits the `fixed_stack_segment`
+annotation. This means that rather than requesting a large stack
+segment only for the duration of the call into C, the large stack
+segment would be used for the entire duration of the caller. This is
+not necessarily *bad* -- it can for example be more efficient,
+particularly if `validate_compressed_buffer()` is called multiple
+times in a row -- but it does work against the purpose of the
+segmented stack scheme, which is to keep stacks small and thus
+conserve address space.
+
 The `snappy_compress` and `snappy_uncompress` functions are more complex, since a buffer has to be
 allocated to hold the output too.
 
@@ -96,6 +134,8 @@ the true length after compression for setting the length.
 
 ~~~~ {.xfail-test}
 pub fn compress(src: &[u8]) -> ~[u8] {
+    #[fixed_stack_segment]; #[inline(never)];
+    
     unsafe {
         let srclen = src.len() as size_t;
         let psrc = vec::raw::to_ptr(src);
@@ -116,6 +156,8 @@ format and `snappy_uncompressed_length` will retrieve the exact buffer size requ
 
 ~~~~ {.xfail-test}
 pub fn uncompress(src: &[u8]) -> Option<~[u8]> {
+    #[fixed_stack_segment]; #[inline(never)];
+    
     unsafe {
         let srclen = src.len() as size_t;
         let psrc = vec::raw::to_ptr(src);
@@ -139,6 +181,99 @@ pub fn uncompress(src: &[u8]) -> Option<~[u8]> {
 For reference, the examples used here are also available as an [library on
 GitHub](https://github.com/thestinger/rust-snappy).
 
+# Automatic wrappers
+
+Sometimes writing Rust wrappers can be quite tedious.  For example, if
+function does not take any pointer arguments, often there is no need
+for translating types. In such cases, it is usually still a good idea
+to have a Rust wrapper so as to manage the segmented stacks, but you
+can take advantage of the (standard) `externfn!` macro to remove some
+of the tedium.
+
+In the initial section, we showed an extern block that added a call
+to a specific snappy API:
+
+~~~~ {.xfail-test}
+use std::libc::size_t;
+
+#[link_args = "-lsnappy"]
+extern {
+    fn snappy_max_compressed_length(source_length: size_t) -> size_t;
+}
+
+#[fixed_stack_segment]
+fn main() {
+    let x = unsafe { snappy_max_compressed_length(100) };
+    println(fmt!("max compressed length of a 100 byte buffer: %?", x));
+}
+~~~~
+
+To avoid the need to create a wrapper fn for `snappy_max_compressed_length()`,
+and also to avoid the need to think about `#[fixed_stack_segment]`, we
+could simply use the `externfn!` macro instead, as shown here:
+
+~~~~ {.xfail-test}
+use std::libc::size_t;
+
+externfn!(#[link_args = "-lsnappy"]
+          fn snappy_max_compressed_length(source_length: size_t) -> size_t)
+
+fn main() {
+    let x = unsafe { snappy_max_compressed_length(100) };
+    println(fmt!("max compressed length of a 100 byte buffer: %?", x));
+}
+~~~~
+
+As you can see from the example, `externfn!` replaces the extern block
+entirely. After macro expansion, it will create something like this:
+
+~~~~ {.xfail-test}
+use std::libc::size_t;
+
+// Automatically generated by
+//   externfn!(#[link_args = "-lsnappy"]
+//             fn snappy_max_compressed_length(source_length: size_t) -> size_t)
+unsafe fn snappy_max_compressed_length(source_length: size_t) -> size_t {
+    #[fixed_stack_segment]; #[inline(never)];
+    return snappy_max_compressed_length(source_length);
+    
+    #[link_args = "-lsnappy"]
+    extern {
+        fn snappy_max_compressed_length(source_length: size_t) -> size_t;
+    }
+}
+
+fn main() {
+    let x = unsafe { snappy_max_compressed_length(100) };
+    println(fmt!("max compressed length of a 100 byte buffer: %?", x));
+}
+~~~~
+
+# Segmented stacks and the linter
+
+By default, whenever you invoke a non-Rust fn, the `cstack` lint will
+check that one of the following conditions holds:
+
+1. The call occurs inside of a fn that has been annotated with
+   `#[fixed_stack_segment]`;
+2. The call occurs inside of an `extern fn`;
+3. The call occurs within a stack closure created by some other
+   safe fn.
+   
+All of these conditions ensure that you are running on a large stack
+segmented. However, they are sometimes too strict. If your application
+will be making many calls into C, it is often beneficial to promote
+the `#[fixed_stack_segment]` attribute higher up the call chain.  For
+example, the Rust compiler actually labels main itself as requiring a
+`#[fixed_stack_segment]`. In such cases, the linter is just an
+annoyance, because all C calls that occur from within the Rust
+compiler are made on a large stack. Another situation where this
+frequently occurs is on a 64-bit architecture, where large stacks are
+the default. In cases, you can disable the linter by including a
+`#[allow(cstack)]` directive somewhere, which permits violations of
+the "cstack" rules given above (you can also use `#[warn(cstack)]` to
+convert the errors into warnings, if you prefer).
+
 # Destructors
 
 Foreign libraries often hand off ownership of resources to the calling code,
@@ -161,6 +296,9 @@ pub struct Unique<T> {
 
 impl<T: Send> Unique<T> {
     pub fn new(value: T) -> Unique<T> {
+        #[fixed_stack_segment];
+        #[inline(never)];
+        
         unsafe {
             let ptr = malloc(std::sys::size_of::<T>() as size_t) as *mut T;
             assert!(!ptr::is_null(ptr));
@@ -184,6 +322,9 @@ impl<T: Send> Unique<T> {
 #[unsafe_destructor]
 impl<T: Send> Drop for Unique<T> {
     fn drop(&self) {
+        #[fixed_stack_segment];
+        #[inline(never)];
+        
         unsafe {
             let x = intrinsics::init(); // dummy value to swap in
             // moving the object out is needed to call the destructor

branches/snap-stage3/mk/rt.mk

@@ -68,9 +68,7 @@ RUNTIME_CXXS_$(1)_$(2) := \
               rt/sync/rust_thread.cpp \
               rt/rust_builtin.cpp \
               rt/rust_run_program.cpp \
-              rt/rust_env.cpp \
               rt/rust_rng.cpp \
-              rt/rust_stack.cpp \
               rt/rust_upcall.cpp \
               rt/rust_uv.cpp \
               rt/rust_crate_map.cpp \

branches/snap-stage3/src/etc/cmathconsts.c

@@ -13,7 +13,7 @@
 #include <math.h>
 #include <stdio.h>
 
-// must match core::ctypes
+// must match std::ctypes
 
 #define C_FLT(x) (float)x
 #define C_DBL(x) (double)x

branches/snap-stage3/src/etc/ziggurat_tables.py

@@ -2,7 +2,7 @@
 # xfail-license
 
 # This creates the tables used for distributions implemented using the
-# ziggurat algorithm in `core::rand::distributions;`. They are
+# ziggurat algorithm in `std::rand::distributions;`. They are
 # (basically) the tables as used in the ZIGNOR variant (Doornik 2005).
 # They are changed rarely, so the generated file should be checked in
 # to git.

branches/snap-stage3/src/etc/zsh/_rust

@@ -36,7 +36,7 @@ _rustc_opts_lint=(
     'path-statement[path statements with no effect]'
     'missing-trait-doc[detects missing documentation for traits]'
     'missing-struct-doc[detects missing documentation for structs]'
-    'ctypes[proper use of core::libc types in foreign modules]'
+    'ctypes[proper use of std::libc types in foreign modules]'
     "unused-mut[detect mut variables which don't need to be mutable]"
     'unused-imports[imports that are never used]'
     'heap-memory[use of any (~ type or @ type) heap memory]'

branches/snap-stage3/src/libextra/arc.rs

@@ -762,7 +762,7 @@ mod tests {
                 do 10.times {
                     let tmp = *num;
                     *num = -1;
-                    task::yield();
+                    task::deschedule();
                     *num = tmp + 1;
                 }
                 c.send(());
@@ -913,17 +913,17 @@ mod tests {
             do read_mode.read |state| {
                 // if writer mistakenly got in, make sure it mutates state
                 // before we assert on it
-                do 5.times { task::yield(); }
+                do 5.times { task::deschedule(); }
                 // make sure writer didn't get in.
                 assert!(*state);
             }
         }
     }
     #[test]
     fn test_rw_write_cond_downgrade_read_race() {
-        // Ideally the above test case would have yield statements in it that
+        // Ideally the above test case would have deschedule statements in it that
         // helped to expose the race nearly 100% of the time... but adding
-        // yields in the intuitively-right locations made it even less likely,
+        // deschedules in the intuitively-right locations made it even less likely,
         // and I wasn't sure why :( . This is a mediocre "next best" option.
         do 8.times { test_rw_write_cond_downgrade_read_race_helper() }
     }

branches/snap-stage3/src/libextra/c_vec.rs

@@ -155,12 +155,20 @@ mod tests {
     use std::libc;
 
     fn malloc(n: size_t) -> CVec<u8> {
+        #[fixed_stack_segment];
+        #[inline(never)];
+
         unsafe {
             let mem = libc::malloc(n);
 
             assert!(mem as int != 0);
 
-            c_vec_with_dtor(mem as *mut u8, n as uint, || free(mem))
+            return c_vec_with_dtor(mem as *mut u8, n as uint, || f(mem));
+        }
+
+        fn f(mem: *c_void) {
+            #[fixed_stack_segment]; #[inline(never)];
+            unsafe { libc::free(mem) }
         }
     }
 

branches/snap-stage3/src/libextra/crypto/cryptoutil.rs

@@ -176,7 +176,7 @@ pub fn add_bytes_to_bits_tuple
 /// method that modifies the buffer directory or provides the caller with bytes that can be modifies
 /// results in those bytes being marked as used by the buffer.
 pub trait FixedBuffer {
-    /// Input a vector of bytes. If the buffer becomes full, proccess it with the provided
+    /// Input a vector of bytes. If the buffer becomes full, process it with the provided
     /// function and then clear the buffer.
     fn input(&mut self, input: &[u8], func: &fn(&[u8]));
 

branches/snap-stage3/src/libextra/crypto/digest.rs

@@ -47,18 +47,18 @@ pub trait Digest {
     fn output_bits(&self) -> uint;
 
     /**
-     * Convenience functon that feeds a string into a digest
+     * Convenience function that feeds a string into a digest.
      *
      * # Arguments
      *
-     * * in The string to feed into the digest
+     * * `input` The string to feed into the digest
      */
     fn input_str(&mut self, input: &str) {
         self.input(input.as_bytes());
     }
 
     /**
-     * Convenience functon that retrieves the result of a digest as a
+     * Convenience function that retrieves the result of a digest as a
      * ~str in hexadecimal format.
      */
     fn result_str(&mut self) -> ~str {

branches/snap-stage3/src/libextra/enum_set.rs

@@ -18,7 +18,7 @@ pub struct EnumSet<E> {
     priv bits: uint
 }
 
-/// An iterface for casting C-like enum to uint and back.
+/// An interface for casting C-like enum to uint and back.
 pub trait CLike {
     /// Converts C-like enum to uint.
     fn to_uint(&self) -> uint;

branches/snap-stage3/src/libextra/fileinput.rs

@@ -156,7 +156,7 @@ impl FileInput {
     /**
     Create a `FileInput` object from a vec of files. An empty
     vec means lines are read from `stdin` (use `from_vec_raw` to stop
-    this behaviour). Any occurence of `None` represents `stdin`.
+    this behaviour). Any occurrence of `None` represents `stdin`.
     */
     pub fn from_vec(files: ~[Option<Path>]) -> FileInput {
         FileInput::from_vec_raw(

branches/snap-stage3/src/libextra/flate.rs

@@ -47,6 +47,8 @@ static TINFL_FLAG_PARSE_ZLIB_HEADER : c_int = 0x1; // parse zlib header and adle
 static TDEFL_WRITE_ZLIB_HEADER : c_int = 0x01000; // write zlib header and adler32 checksum
 
 fn deflate_bytes_internal(bytes: &[u8], flags: c_int) -> ~[u8] {
+    #[fixed_stack_segment]; #[inline(never)];
+
     do bytes.as_imm_buf |b, len| {
         unsafe {
             let mut outsz : size_t = 0;
@@ -73,6 +75,8 @@ pub fn deflate_bytes_zlib(bytes: &[u8]) -> ~[u8] {
 }
 
 fn inflate_bytes_internal(bytes: &[u8], flags: c_int) -> ~[u8] {
+    #[fixed_stack_segment]; #[inline(never)];
+
     do bytes.as_imm_buf |b, len| {
         unsafe {
             let mut outsz : size_t = 0;