doc: explicitly state the contracts of Stack and GuardedStack.

This commit is contained in:
whitequark 2016-09-02 16:00:11 +00:00 committed by edef
parent 3f6c895cb7
commit 0ca4bc86ff
2 changed files with 18 additions and 2 deletions

View File

@ -87,6 +87,8 @@ pub struct Generator<Input: Send, Output: Send, Stack: stack::Stack> {
impl<Input, Output, Stack> Generator<Input, Output, Stack> impl<Input, Output, Stack> Generator<Input, Output, Stack>
where Input: Send, Output: Send, Stack: stack::Stack { where Input: Send, Output: Send, Stack: stack::Stack {
/// Creates a new generator. /// 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> pub fn new<F>(stack: Stack, f: F) -> Generator<Input, Output, Stack>
where Stack: stack::GuardedStack, where Stack: stack::GuardedStack,
F: FnOnce(&mut Yielder<Input, Output, Stack>, Input) + Send { 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 /// This function is unsafe because the generator function can easily violate
/// memory safety by overflowing the stack. It is useful in environments where /// memory safety by overflowing the stack. It is useful in environments where
/// guarded stacks do not exist, e.g. in absence of an MMU. /// 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> pub unsafe fn unsafe_new<F>(stack: Stack, f: F) -> Generator<Input, Output, Stack>
where F: FnOnce(&mut Yielder<Input, Output, Stack>, Input) + Send { where F: FnOnce(&mut Yielder<Input, Output, Stack>, Input) + Send {
unsafe extern "C" fn generator_wrapper<Input, Output, Stack, F>(env: usize) -> ! unsafe extern "C" fn generator_wrapper<Input, Output, Stack, F>(env: usize) -> !

View File

@ -7,6 +7,15 @@
//! Traits for stacks. //! Traits for stacks.
/// A trait for objects that hold ownership of a stack. /// 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 { pub trait Stack {
/// Returns the base of the stack. /// Returns the base of the stack.
/// On all modern architectures, the stack grows downwards, /// 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 marker trait for `Stack` objects with a guard page.
/// ///
/// A guarded stack must guarantee that any access of data at addresses `limit()` to /// To preserve memory safety, an implementation of this trait must fulfill
/// `limit().offset(4096)` will abnormally terminate the program. /// 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 {} pub unsafe trait GuardedStack {}