From aa364056fdd4f259f1d9b29f573db9cd864b5867 Mon Sep 17 00:00:00 2001 From: whitequark Date: Sun, 17 Jul 2016 00:47:37 +0000 Subject: [PATCH] Add more documentation, and rephrase it elsewhere. --- src/context.rs | 14 +++++++------- src/os/mod.rs | 9 +++++++-- 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/src/context.rs b/src/context.rs index 98609d8..7572480 100644 --- a/src/context.rs +++ b/src/context.rs @@ -6,13 +6,13 @@ use stack; use debug; use arch; -/// Context is the heart of libfringe. -/// A context represents a saved thread of execution, along with a stack. +/// Context holds a suspended thread of execution along with a stack. +/// /// 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. /// -/// Every operation is unsafe, because libfringe can't make any guarantees -/// about the state of the context. +/// Every operation is unsafe, because no guarantees can be made about +/// the state of the context. #[derive(Debug)] pub struct Context { stack: Stack, @@ -24,7 +24,7 @@ unsafe impl Send for Context where Stack: stack::Stack + Send {} impl Context 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`. pub unsafe fn new(stack: Stack, f: unsafe extern "C" fn(usize) -> !) -> Context { let stack_id = debug::StackId::register(&stack); @@ -36,14 +36,14 @@ impl Context 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 { self.stack } } impl Context 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)] pub unsafe fn swap(old_ctx: *mut Context, new_ctx: *const Context, diff --git a/src/os/mod.rs b/src/os/mod.rs index 70ccec4..e977c18 100644 --- a/src/os/mod.rs +++ b/src/os/mod.rs @@ -7,8 +7,9 @@ use stack; mod sys; -/// This object represents a stack from the operating system's -/// anonymous memory mapping facility, usually `mmap`. +/// OsStack holds a stack allocated using the operating system's anonymous +/// memory mapping facility. +/// /// The stack it provides comes with a guard page, which is not included /// in the stack limit. #[derive(Debug)] @@ -20,6 +21,10 @@ pub struct Stack { unsafe impl Send for 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 { let page_size = sys::page_size();