Add descriptions.

Author: sisshiki1969

src/coroutine/stack.rs

@@ -12,6 +12,16 @@ const STACK_LAYOUT: Result<Layout, LayoutError> =
 
 static STACK_STORE: Lazy<Mutex<Vec<Stack>>> = Lazy::new(|| Mutex::new(Vec::new()));
 
+///
+/// Machine stack handle for Fiber.
+///
+/// `Stack` is a wrapper of a raw pointer which points to the top of machine stack area
+/// of a Fiber object.
+/// The stack area is newly allocated when a Fiber object is 'resume'd at the first time
+/// after created.
+///  
+/// Default size of the stack area is DEFAULT_SIZE bytes(currently, 512KiB).
+///
 #[derive(Clone, Copy, Debug, PartialEq)]
 #[repr(transparent)]
 pub struct Stack(*mut u8);
@@ -24,6 +34,10 @@ impl Stack {
         Self(std::ptr::null_mut())
     }
 
+    /// Allocate new stack area.
+    ///
+    /// If some `Stack` were saved in `STACK_STORE`, the newest one is returned.
+    /// Otherwise, allocate new `Stack` and return it.
     pub(crate) fn allocate() -> Self {
         match STACK_STORE.lock().unwrap().pop() {
             None => unsafe {
@@ -36,6 +50,10 @@ impl Stack {
         }
     }
 
+    /// Deallocate `Stack`.
+    ///
+    /// Currently, when a Fiber object was disposed by GC, associated `Stack` is returned
+    /// to `STACK_STORE`.
     pub(crate) fn deallocate(&mut self) {
         if self.0.is_null() {
             return;
@@ -44,6 +62,13 @@ impl Stack {
         self.0 = std::ptr::null_mut();
     }
 
+    /// Initialize `Stack`.
+    ///
+    /// Addresses of some functions are stored at the bottom of the stack area.
+    ///
+    /// - `new_context` is to be called when the Fiber coroutine is 'resume'd at the first time.
+    /// - `guard` is to be called when 'resume'd **after** the Fiber coroutine execution was finished.
+    /// - a pointer which points FiberContext is placed at the very bottom of the stack.
     pub(crate) fn init(&mut self, fiber: *const FiberContext) -> u64 {
         unsafe {
             let s_ptr = self.0.offset(DEFAULT_STACK_SIZE as isize);

src/vm/executor/frame.rs

@@ -62,6 +62,13 @@ impl Frame {
     }
 }
 
+///
+/// Control frame
+///
+/// This is a wrapped raw pointer which points to a certain point within `RubyStack`.
+/// You can obtain or alter various information like cfp, lfp, and the number of local variables
+/// in the frame through `ControlFrame`.
+///
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct ControlFrame(*mut Value);
 
@@ -683,17 +690,18 @@ impl VM {
     ///
     ///  ### After
     ///~~~~text
-    ///   lfp                            cfp           sp
-    ///    v                              v             v
-    /// +------+------+--+------+------+------+------+-----
-    /// |  a0  |  a1  |..|  an  | self | flg  | cfp* |
-    /// +------+------+--+------+------+------+------+-----
+    ///   lfp                            cfp                 sp
+    ///    v                              v                   v
+    /// +------+------+--+------+------+------+------+-----+---
+    /// |  a0  |  a1  |..|  an  | self | cfp* | lfp  | flg |
+    /// +------+------+--+------+------+------+------+-----+---
     ///  <-------- local frame --------> <---------->
     ///                               native control frame
     ///~~~~
     ///
-    /// - flg: flags
     /// - cfp*: prev cfp
+    /// - lfp: lfp
+    /// - flg: flags
     ///
     pub(crate) fn prepare_native_frame(&mut self, args_len: usize) {
         self.save_next_pc();

src/vm/executor/ruby_stack.rs

@@ -5,10 +5,18 @@ use std::pin::Pin;
 
 pub(super) const VM_STACK_SIZE: usize = 8192;
 
+///
+/// Ruruby exection stack.
+///
+/// Ruruby stack is implemented as a fixed and pinned heap array of `Value`s.
+/// You can do operations like push, pop, or extend, as if it was a Vec.
+///
+/// Stack size is VM_STACK_SIZE(currently, 8192 `Value`s).
 #[derive(Clone)]
 pub(super) struct RubyStack {
-    //len: usize,
+    /// Stack pointer.
     pub sp: StackPtr,
+    /// Pinned Buffer.
     buf: Pin<Box<[Value]>>,
 }
 
@@ -49,6 +57,7 @@ impl IndexMut<Range<usize>> for RubyStack {
 }
 
 impl RubyStack {
+    /// Allocate new `RubyStack`.
     pub(super) fn new() -> Self {
         let mut inner = unsafe { Box::new_uninit_slice(VM_STACK_SIZE).assume_init() };
         let sp = StackPtr::from(inner.as_mut_ptr());
@@ -58,33 +67,43 @@ impl RubyStack {
         }
     }
 
+    /// Set SP to `new_len`.
     unsafe fn set_len(&mut self, new_len: usize) {
         self.sp = StackPtr::from(self.buf.as_mut_ptr()) + new_len;
     }
 
+    /// Increment SP.
     unsafe fn inc_len(&mut self, offset: usize) {
         self.sp = self.sp + offset;
     }
 
+    /// Decrement SP.
     unsafe fn dec_len(&mut self, offset: usize) {
         self.sp = self.sp - offset;
     }
 
+    /// Get length of stack.
+    /// This is as same as the index of SP in the stack.
     pub(super) fn len(&self) -> usize {
         let len = unsafe { self.sp.as_ptr().offset_from(self.buf.as_ptr()) };
         assert!(len >= 0);
         len as usize
     }
 
+    /// Shortens the stack.
+    /// If len is greater than the current length, this has no effect.
     pub(super) fn truncate(&mut self, len: usize) {
         if len >= self.len() {
             return;
         }
         unsafe { self.set_len(len) };
     }
 
+    /// Resize the stack so that len is equal to new_len.
+    /// If new_len is greater than len, the stack is extended by the difference, with each additional slot filled with Nil.
+    /// If new_len is less than len, the stack is simply truncated.
     pub(super) fn resize(&mut self, new_len: usize) {
-        debug_assert!(new_len <= VM_STACK_SIZE);
+        assert!(new_len <= VM_STACK_SIZE);
         let len = self.len();
         if new_len > len {
             self.buf[len..new_len].fill(Value::nil());