morgan
/
libfringe
forked from M-Labs/libfringe
1
0
Fork 0
Code Pull Requests Activity

Add more documentation, and rephrase it elsewhere.

This commit is contained in:
whitequark 2016-07-17 00:47:37 +00:00 committed by edef
parent ebd9ca8dec
commit aa364056fd
2 changed files with 14 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
src/context.rs
View File

@ -6,13 +6,13 @@ use stack;
use debug; use debug;
use arch; use arch;
/// Context is the heart of libfringe. /// Context holds a suspended thread of execution along with a stack.
/// A context represents a saved thread of execution, along with a stack. ///
/// It can be swapped into and out of with the swap method, /// It can be swapped into and out of with the swap method,
/// and once you're done with it, you can get the stack back through unwrap. /// and once you're done with it, you can get the stack back through unwrap.
/// ///
/// Every operation is unsafe, because libfringe can't make any guarantees /// Every operation is unsafe, because no guarantees can be made about
/// about the state of the context. /// the state of the context.
#[derive(Debug)] #[derive(Debug)]
pub struct Context<Stack: stack::Stack> { pub struct Context<Stack: stack::Stack> {
stack: Stack, stack: Stack,
@ -24,7 +24,7 @@ unsafe impl<Stack> Send for Context<Stack>
where Stack: stack::Stack + Send {} where Stack: stack::Stack + Send {}
impl<Stack> Context<Stack> where Stack: stack::Stack { impl<Stack> Context<Stack> where Stack: stack::Stack {
/// Create a new Context. When it is swapped into, it will call /// Creates a new Context. When it is swapped into, it will call
/// `f(arg)`, where `arg` is the argument passed to `swap`. /// `f(arg)`, where `arg` is the argument passed to `swap`.
pub unsafe fn new(stack: Stack, f: unsafe extern "C" fn(usize) -> !) -> Context<Stack> { pub unsafe fn new(stack: Stack, f: unsafe extern "C" fn(usize) -> !) -> Context<Stack> {
let stack_id = debug::StackId::register(&stack); let stack_id = debug::StackId::register(&stack);
@ -36,14 +36,14 @@ impl<Stack> Context<Stack> where Stack: stack::Stack {
} }
} }
/// Unwrap the context, returning the stack it contained. /// Unwraps the context, returning the stack it contained.
pub unsafe fn unwrap(self) -> Stack { pub unsafe fn unwrap(self) -> Stack {
self.stack self.stack
} }
} }
impl<OldStack> Context<OldStack> where OldStack: stack::Stack { impl<OldStack> Context<OldStack> where OldStack: stack::Stack {
/// Switch to in_ctx, saving the current thread of execution to out_ctx. /// Switches to in_ctx, saving the current thread of execution to out_ctx.
#[inline(always)] #[inline(always)]
pub unsafe fn swap<NewStack>(old_ctx: *mut Context<OldStack>, pub unsafe fn swap<NewStack>(old_ctx: *mut Context<OldStack>,
new_ctx: *const Context<NewStack>, new_ctx: *const Context<NewStack>,

9
src/os/mod.rs
View File

@ -7,8 +7,9 @@ use stack;
mod sys; mod sys;
/// This object represents a stack from the operating system's /// OsStack holds a stack allocated using the operating system's anonymous
/// anonymous memory mapping facility, usually `mmap`. /// memory mapping facility.
///
/// The stack it provides comes with a guard page, which is not included /// The stack it provides comes with a guard page, which is not included
/// in the stack limit. /// in the stack limit.
#[derive(Debug)] #[derive(Debug)]
@ -20,6 +21,10 @@ pub struct Stack {
unsafe impl Send for Stack {} unsafe impl Send for Stack {}
impl Stack { impl Stack {
/// Allocates a new stack with at least `size` accessible bytes.
/// `size` is rounded up to an integral number of pages; `Stack::new(0)`
/// is legal and allocates the smallest possible stack, consisting
/// of one data page and one guard page.
pub fn new(size: usize) -> Result<Stack, IoError> { pub fn new(size: usize) -> Result<Stack, IoError> {
let page_size = sys::page_size(); let page_size = sys::page_size();