From 0ca4bc86ff53e5ca980fcaa614d2712c8683f687 Mon Sep 17 00:00:00 2001
From: whitequark <whitequark@whitequark.org>
Date: Fri, 2 Sep 2016 16:00:11 +0000
Subject: [PATCH] doc: explicitly state the contracts of Stack and
 GuardedStack.

---
 src/generator.rs |  4 ++++
 src/stack.rs     | 16 ++++++++++++++--
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/src/generator.rs b/src/generator.rs
index 913ae78..225ffa5 100644
--- a/src/generator.rs
+++ b/src/generator.rs
@@ -87,6 +87,8 @@ pub struct Generator<Input: Send, Output: Send, Stack: stack::Stack> {
 impl<Input, Output, Stack> Generator<Input, Output, Stack>
     where Input: Send, Output: Send, Stack: stack::Stack {
   /// Creates a new generator.
+  ///
+  /// See also the [contract](../trait.GuardedStack.html) that needs to be fulfilled by `stack`.
   pub fn new<F>(stack: Stack, f: F) -> Generator<Input, Output, Stack>
       where Stack: stack::GuardedStack,
             F: FnOnce(&mut Yielder<Input, Output, Stack>, Input) + Send {
@@ -98,6 +100,8 @@ impl<Input, Output, Stack> Generator<Input, Output, Stack>
   /// This function is unsafe because the generator function can easily violate
   /// memory safety by overflowing the stack. It is useful in environments where
   /// guarded stacks do not exist, e.g. in absence of an MMU.
+  ///
+  /// See also the [contract](../trait.Stack.html) that needs to be fulfilled by `stack`.
   pub unsafe fn unsafe_new<F>(stack: Stack, f: F) -> Generator<Input, Output, Stack>
       where F: FnOnce(&mut Yielder<Input, Output, Stack>, Input) + Send {
     unsafe extern "C" fn generator_wrapper<Input, Output, Stack, F>(env: usize) -> !
diff --git a/src/stack.rs b/src/stack.rs
index 0e769d8..dfd05bc 100644
--- a/src/stack.rs
+++ b/src/stack.rs
@@ -7,6 +7,15 @@
 //! Traits for stacks.
 
 /// A trait for objects that hold ownership of a stack.
+///
+/// To preserve memory safety, an implementation of this trait must fulfill
+/// the following contract:
+///
+///   * The base of the stack must be aligned to a platform-specific boundary.
+///   * Every address between the base and the limit must be readable and writable.
+///
+/// On any platform supported by libfringe, it is safe to align the stack to a 16-byte boundary.
+/// The platform ABI document lists the specific alignment requirement.
 pub trait Stack {
   /// Returns the base of the stack.
   /// On all modern architectures, the stack grows downwards,
@@ -20,6 +29,9 @@ pub trait Stack {
 
 /// A marker trait for `Stack` objects with a guard page.
 ///
-/// A guarded stack must guarantee that any access of data at addresses `limit()` to
-/// `limit().offset(4096)` will abnormally terminate the program.
+/// To preserve memory safety, an implementation of this trait must fulfill
+/// the following contract, in addition to the [contract](trait.Stack.html) of `Stack`:
+///
+///   * Any access of data at addresses `limit()` to `limit().offset(4096)` must
+///     abnormally terminate, at least, the thread that performs the access.
 pub unsafe trait GuardedStack {}