From 0ca4bc86ff53e5ca980fcaa614d2712c8683f687 Mon Sep 17 00:00:00 2001 From: whitequark 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 { impl Generator 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(stack: Stack, f: F) -> Generator where Stack: stack::GuardedStack, F: FnOnce(&mut Yielder, Input) + Send { @@ -98,6 +100,8 @@ impl Generator /// 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(stack: Stack, f: F) -> Generator where F: FnOnce(&mut Yielder, Input) + Send { unsafe extern "C" fn generator_wrapper(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 {}