rt: Improve docs for main, kernel, scheduler, and task

1 files changed, 30 insertions, 7 deletions

diff --git a/src/rt/rust.cpp b/src/rt/rust.cpp
index 4019c8701ac..7efc3b8839c 100644
--- a/src/rt/rust.cpp
+++ b/src/rt/rust.cpp
@@ -1,9 +1,14 @@
+/**
+ * Main entry point into the Rust runtime. Here we initialize the kernel,
+ * create the initial scheduler and run the main task.
+ */
 
 #include "rust_globals.h"
 #include "rust_kernel.h"
 #include "rust_util.h"
 #include "rust_scheduler.h"
 
+// Creates a rust argument vector from the platform argument vector
 struct
 command_line_args : public kernel_owned<command_line_args>
 {
@@ -61,42 +66,60 @@ command_line_args : public kernel_owned<command_line_args>
     }
 };
 
-/**
- * Main entry point into the Rust runtime. Here we create a Rust service,
- * initialize the kernel, create the root domain and run it.
- */
-
+// A global that indicates whether Rust typestate claim statements should be
+// executed Generated code will read this variable directly (I think).
+// FIXME: This belongs somewhere else
 int check_claims = 0;
 
+/**
+   The runtime entrypoint. The (C ABI) main function generated by rustc calls
+   `rust_start`, providing the address of the Rust ABI main function, the
+   platform argument vector, and a `crate_map` the provides some logging
+   metadata.
+*/
 extern "C" CDECL int
 rust_start(uintptr_t main_fn, int argc, char **argv, void* crate_map) {
 
+    // Load runtime configuration options from the environment.
+    // FIXME #1497: Should provide a way to get these from the command
+    // line as well.
     rust_env *env = load_env();
 
     update_log_settings(crate_map, env->logspec);
+
+    // Maybe turn on typestate claim checking
     check_claims = env->check_claims;
 
     rust_kernel *kernel = new rust_kernel(env);
+
+    // Create the main scheduler and the main task
     rust_sched_id sched_id = kernel->create_scheduler(env->num_sched_threads);
     rust_scheduler *sched = kernel->get_scheduler_by_id(sched_id);
     rust_task *root_task = sched->create_task(NULL, "main");
+
+    // Build the command line arguments to pass to the root task
     command_line_args *args
         = new (kernel, "main command line args")
         command_line_args(root_task, argc, argv);
 
     LOG(root_task, dom, "startup: %d args in 0x%" PRIxPTR,
-             args->argc, (uintptr_t)args->args);
+        args->argc, (uintptr_t)args->args);
     for (int i = 0; i < args->argc; i++) {
         LOG(root_task, dom, "startup: arg[%d] = '%s'", i, args->argv[i]);
     }
 
+    // Schedule the main Rust task
     root_task->start((spawn_fn)main_fn, NULL, args->args);
+
+    // At this point the task lifecycle is responsible for it
+    // and our pointer may not be valid
     root_task = NULL;
 
+    // Run the kernel until all schedulers exit
     int ret = kernel->run();
+
     delete args;
     delete kernel;
-
     free_env(env);
 
     return ret;