Documentation and tracing improvements after rename

README.md

@@ -76,16 +76,16 @@ lua.globals().set(
 ### 3. Set up scheduler, run threads
 
 ```rs
-let rt = Scheduler::new(&lua)?;
+let sched = Scheduler::new(&lua)?;
 
 // We can create multiple lua threads ...
 let sleepThread = lua.load("sleep(0.1)");
 let fileThread = lua.load("readFile(\"Cargo.toml\")");
 
 // ... spawn them both onto the scheduler ...
-rt.push_thread_front(sleepThread, ());
+sched.push_thread_front(sleepThread, ());
-rt.push_thread_front(fileThread, ());
+sched.push_thread_front(fileThread, ());
 
 // ... and run until they finish
-block_on(rt.run());
+block_on(sched.run());
 ```

examples/basic_sleep.rs

@@ -28,12 +28,12 @@ pub fn main() -> LuaResult<()> {
     )?;
 
     // Load the main script into a scheduler
-    let rt = Scheduler::new(&lua);
+    let sched = Scheduler::new(&lua);
     let main = lua.load(MAIN_SCRIPT);
-    rt.push_thread_front(main, ())?;
+    sched.push_thread_front(main, ())?;
 
     // Run until completion
-    block_on(rt.run());
+    block_on(sched.run());
 
     Ok(())
 }

examples/basic_spawn.rs

@@ -47,12 +47,12 @@ pub fn main() -> LuaResult<()> {
     )?;
 
     // Load the main script into a scheduler
-    let rt = Scheduler::new(&lua);
+    let sched = Scheduler::new(&lua);
     let main = lua.load(MAIN_SCRIPT);
-    rt.push_thread_front(main, ())?;
+    sched.push_thread_front(main, ())?;
 
     // Run until completion
-    block_on(rt.run());
+    block_on(sched.run());
 
     Ok(())
 }

examples/callbacks.rs

@@ -19,8 +19,8 @@ pub fn main() -> LuaResult<()> {
     let lua = Lua::new();
 
     // Create a new scheduler with custom callbacks
-    let rt = Scheduler::new(&lua);
+    let sched = Scheduler::new(&lua);
-    rt.set_error_callback(|e| {
+    sched.set_error_callback(|e| {
         println!(
             "Captured error from Lua!\n{}\n{e}\n{}",
             "-".repeat(15),
@@ -30,13 +30,13 @@ pub fn main() -> LuaResult<()> {
 
     // Load the main script into the scheduler, and keep track of the thread we spawn
     let main = lua.load(MAIN_SCRIPT);
-    let id = rt.push_thread_front(main, ())?;
+    let id = sched.push_thread_front(main, ())?;
 
     // Run until completion
-    block_on(rt.run());
+    block_on(sched.run());
 
     // We should have gotten the error back from our script
-    assert!(rt.get_thread_result(id).unwrap().is_err());
+    assert!(sched.get_thread_result(id).unwrap().is_err());
 
     Ok(())
 }

examples/exit_code.rs

@@ -17,20 +17,20 @@ pub fn main() -> LuaResult<()> {
 
     // Set up persistent Lua environment
     let lua = Lua::new();
-    let rt = Scheduler::new(&lua);
+    let sched = Scheduler::new(&lua);
     let fns = Functions::new(&lua)?;
 
     lua.globals().set("exit", fns.exit)?;
 
     // Load the main script into the scheduler
     let main = lua.load(MAIN_SCRIPT);
-    rt.push_thread_front(main, ())?;
+    sched.push_thread_front(main, ())?;
 
     // Run until completion
-    block_on(rt.run());
+    block_on(sched.run());
 
     // Verify that we got a correct exit code
-    let code = rt.get_exit_code().unwrap_or_default();
+    let code = sched.get_exit_code().unwrap_or_default();
     assert!(format!("{code:?}").contains("(1)"));
 
     Ok(())

examples/lots_of_threads.rs

@@ -20,7 +20,7 @@ pub fn main() -> LuaResult<()> {
 
     // Set up persistent Lua environment
     let lua = Lua::new();
-    let rt = Scheduler::new(&lua);
+    let sched = Scheduler::new(&lua);
     let fns = Functions::new(&lua)?;
 
     lua.globals().set("spawn", fns.spawn)?;
@@ -36,10 +36,10 @@ pub fn main() -> LuaResult<()> {
 
     // Load the main script into the scheduler
     let main = lua.load(MAIN_SCRIPT);
-    rt.push_thread_front(main, ())?;
+    sched.push_thread_front(main, ())?;
 
     // Run until completion
-    block_on(rt.run());
+    block_on(sched.run());
 
     Ok(())
 }

examples/scheduler_ordering.rs

@@ -19,7 +19,7 @@ pub fn main() -> LuaResult<()> {
 
     // Set up persistent Lua environment
     let lua = Lua::new();
-    let rt = Scheduler::new(&lua);
+    let sched = Scheduler::new(&lua);
     let fns = Functions::new(&lua)?;
 
     lua.globals().set("spawn", fns.spawn)?;
@@ -36,13 +36,13 @@ pub fn main() -> LuaResult<()> {
 
     // Load the main script into the scheduler, and keep track of the thread we spawn
     let main = lua.load(MAIN_SCRIPT);
-    let id = rt.push_thread_front(main, ())?;
+    let id = sched.push_thread_front(main, ())?;
 
     // Run until completion
-    block_on(rt.run());
+    block_on(sched.run());
 
     // We should have gotten proper values back from our script
-    let res = rt.get_thread_result(id).unwrap().unwrap();
+    let res = sched.get_thread_result(id).unwrap().unwrap();
     let nums = Vec::<usize>::from_lua_multi(res, &lua)?;
     assert_eq!(nums, vec![1, 2, 3, 4, 5, 6]);
 

examples/tracy.rs

@@ -35,7 +35,7 @@ pub fn main() -> LuaResult<()> {
 
     // Set up persistent Lua environment
     let lua = Lua::new();
-    let rt = Scheduler::new(&lua);
+    let sched = Scheduler::new(&lua);
     let fns = Functions::new(&lua)?;
 
     lua.globals().set("spawn", fns.spawn)?;
@@ -51,10 +51,10 @@ pub fn main() -> LuaResult<()> {
 
     // Load the main script into the scheduler
     let main = lua.load(MAIN_SCRIPT);
-    rt.push_thread_front(main, ())?;
+    sched.push_thread_front(main, ())?;
 
     // Run until completion
-    block_on(rt.run());
+    block_on(sched.run());
 
     Ok(())
 }

lib/functions.rs

@@ -40,6 +40,9 @@ end
 
 /**
     A collection of lua functions that may be called to interact with a [`Scheduler`].
+
+    Note that these may all be implemented using [`LuaSchedulerExt`], however, this struct
+    is implemented using internal (non-public) APIs, and generally has better performance.
 */
 pub struct Functions<'lua> {
     /**
@@ -112,7 +115,7 @@ impl<'lua> Functions<'lua> {
         let resume_map = result_map.clone();
         let resume =
             lua.create_function(move |lua, (thread, args): (LuaThread, LuaMultiValue)| {
-                let _span = tracing::trace_span!("lua::resume").entered();
+                let _span = tracing::trace_span!("Scheduler::fn_resume").entered();
                 match thread.resume::<_, LuaMultiValue>(args.clone()) {
                     Ok(v) => {
                         if v.get(0).map(is_poll_pending).unwrap_or_default() {
@@ -164,7 +167,7 @@ impl<'lua> Functions<'lua> {
         let spawn_map = result_map.clone();
         let spawn = lua.create_function(
             move |lua, (tof, args): (LuaThreadOrFunction, LuaMultiValue)| {
-                let _span = tracing::trace_span!("lua::spawn").entered();
+                let _span = tracing::trace_span!("Scheduler::fn_spawn").entered();
                 let thread = tof.into_thread(lua)?;
                 if thread.status() == LuaThreadStatus::Resumable {
                     // NOTE: We need to resume the thread once instantly for correct behavior,
@@ -201,7 +204,7 @@ impl<'lua> Functions<'lua> {
 
         let defer = lua.create_function(
             move |lua, (tof, args): (LuaThreadOrFunction, LuaMultiValue)| {
-                let _span = tracing::trace_span!("lua::defer").entered();
+                let _span = tracing::trace_span!("Scheduler::fn_defer").entered();
                 let thread = tof.into_thread(lua)?;
                 if thread.status() == LuaThreadStatus::Resumable {
                     defer_queue.push_item(lua, &thread, args)?;
@@ -216,7 +219,7 @@ impl<'lua> Functions<'lua> {
             .get::<_, LuaFunction>("close")?;
         let close_key = lua.create_registry_value(close)?;
         let cancel = lua.create_function(move |lua, thread: LuaThread| {
-            let _span = tracing::trace_span!("lua::cancel").entered();
+            let _span = tracing::trace_span!("Scheduler::fn_cancel").entered();
             let close: LuaFunction = lua.registry_value(&close_key)?;
             match close.call(thread) {
                 Err(LuaError::CoroutineInactive) | Ok(()) => Ok(()),
@@ -228,7 +231,7 @@ impl<'lua> Functions<'lua> {
             (
                 "exit",
                 lua.create_function(|lua, code: Option<u8>| {
-                    let _span = tracing::trace_span!("lua::exit").entered();
+                    let _span = tracing::trace_span!("Scheduler::fn_exit").entered();
                     let code = code.map(ExitCode::from).unwrap_or_default();
                     lua.set_exit_code(code);
                     Ok(())

lib/scheduler.rs

@@ -369,7 +369,7 @@ impl<'lua> Scheduler<'lua> {
 
                 // 5
                 let mut num_processed = 0;
-                let span_tick = trace_span!("scheduler::tick");
+                let span_tick = trace_span!("Scheduler::tick");
                 let fut_tick = async {
                     local_exec.tick().await;
                     // NOTE: Try to do as much work as possible instead of just a single tick()
@@ -398,21 +398,21 @@ impl<'lua> Scheduler<'lua> {
                 let mut num_deferred = 0;
                 let mut num_futures = 0;
                 {
-                    let _span = trace_span!("scheduler::drain_spawned").entered();
+                    let _span = trace_span!("Scheduler::drain_spawned").entered();
                     for (thread, args) in self.queue_spawn.drain_items(self.lua) {
                         process_thread(thread, args);
                         num_spawned += 1;
                     }
                 }
                 {
-                    let _span = trace_span!("scheduler::drain_deferred").entered();
+                    let _span = trace_span!("Scheduler::drain_deferred").entered();
                     for (thread, args) in self.queue_defer.drain_items(self.lua) {
                         process_thread(thread, args);
                         num_deferred += 1;
                     }
                 }
                 {
-                    let _span = trace_span!("scheduler::drain_futures").entered();
+                    let _span = trace_span!("Scheduler::drain_futures").entered();
                     for fut in fut_queue.drain_items() {
                         local_exec.spawn(fut).detach();
                         num_futures += 1;

lib/traits.rs

@@ -182,9 +182,9 @@ pub trait LuaSpawnExt<'lua> {
                 })?
             )?;
 
-            let rt = Scheduler::new(&lua);
+            let sched = Scheduler::new(&lua);
-            rt.push_thread_front(lua.load("spawnBackgroundTask()"), ());
+            sched.push_thread_front(lua.load("spawnBackgroundTask()"), ());
-            block_on(rt.run());
+            block_on(sched.run());
 
             Ok(())
         }
@@ -226,9 +226,9 @@ pub trait LuaSpawnExt<'lua> {
                 })?
             )?;
 
-            let rt = Scheduler::new(&lua);
+            let sched = Scheduler::new(&lua);
-            rt.push_thread_front(lua.load("spawnLocalTask()"), ());
+            sched.push_thread_front(lua.load("spawnLocalTask()"), ());
-            block_on(rt.run());
+            block_on(sched.run());
 
             Ok(())
         }
@@ -268,9 +268,9 @@ pub trait LuaSpawnExt<'lua> {
                 })?
             )?;
 
-            let rt = Scheduler::new(&lua);
+            let sched = Scheduler::new(&lua);
-            rt.push_thread_front(lua.load("spawnBlockingTask()"), ());
+            sched.push_thread_front(lua.load("spawnBlockingTask()"), ());
-            block_on(rt.run());
+            block_on(sched.run());
 
             Ok(())
         }

lib/util.rs

@@ -9,7 +9,7 @@ use tracing::instrument;
 
     Otherwise returns the values yielded by the thread, or the error that caused it to stop.
 */
-#[instrument(level = "trace", name = "scheduler::run_until_yield", skip_all)]
+#[instrument(level = "trace", name = "Scheduler::run_until_yield", skip_all)]
 pub(crate) async fn run_until_yield<'lua>(
     thread: LuaThread<'lua>,
     args: LuaMultiValue<'lua>,