diff --git a/rustport/src/lib.rs b/rustport/src/lib.rs index 41b1c1e5..ee2e377a 100644 --- a/rustport/src/lib.rs +++ b/rustport/src/lib.rs @@ -4,11 +4,15 @@ use std::{ffi::c_void, sync::Mutex}; use stlab::{Priority, PriorityTaskSystem}; mod stlab; +/// A static instance of the task system which is invoked through the `execute` functions below. static TASK_SYSTEM: Lazy> = Lazy::new(|| Mutex::new(PriorityTaskSystem::new())); -// "Threadsafe" is not a guarantee, it is a requirement. These pointers are assumed to be able to -// be sent to another thread, and therefore must not rely on thread-local state. + +/// A function pointer paired with a context, akin to a C++ lambda and its captures. +/// +/// "Threadsafe" is not a guarantee, it is a requirement. These pointers are assumed to be able to +/// be sent to another thread, and therefore must not rely on thread-local state. struct ThreadsafeCFnWrapper { context: *mut c_void, fn_ptr: extern "C" fn(*mut c_void), @@ -19,14 +23,18 @@ impl ThreadsafeCFnWrapper { Self { context, fn_ptr } } + // Note: there is no way in stable rust to make a struct invocable with () syntax. pub(crate) fn call(&self) { (self.fn_ptr)(self.context) } } +/// `ThreadsafeCFnWrapper` may not rely on thread-local state. unsafe impl Send for ThreadsafeCFnWrapper {} /// Enqueues a the execution of `f(context)` on the PriorityTaskSystem. +/// +/// Precondition: Neither `context` nor `fn_ptr` may rely on thread-local state. #[no_mangle] pub extern "C" fn execute(context: *mut c_void, fn_ptr: extern "C" fn(*mut c_void)) -> i32 { execute_priority(context, fn_ptr, Priority::Default); @@ -34,6 +42,8 @@ pub extern "C" fn execute(context: *mut c_void, fn_ptr: extern "C" fn(*mut c_voi } /// Enqueues a the execution of `f(context)` on the PriorityTaskSystem at the given `priority`. +/// +/// Precondition: Neither `context` nor `fn_ptr` may rely on thread-local state. #[no_mangle] pub extern "C" fn execute_priority( context: *mut c_void, diff --git a/rustport/src/stlab/mod.rs b/rustport/src/stlab/mod.rs index 9865fa24..e50392e1 100644 --- a/rustport/src/stlab/mod.rs +++ b/rustport/src/stlab/mod.rs @@ -99,7 +99,6 @@ impl PriorityTaskSystem { /// Push `f` to the first queue in `queues` whose mutex is not under contention. /// If no such queue is found after a single pass, blockingly push `f` to one queue. - // REVIEW: I'm not sure `execute` is a good name. I think we want `push`, or `push_with_priority`. pub fn execute(&self, f: F, p: Priority) where F: FnOnce() -> () + Send + 'static, diff --git a/rustport/src/stlab/waiter.rs b/rustport/src/stlab/waiter.rs index 844e7683..9d6c6b06 100644 --- a/rustport/src/stlab/waiter.rs +++ b/rustport/src/stlab/waiter.rs @@ -36,8 +36,7 @@ impl Waiter { } /// Sets waiting to `false`. If waiting was `true`, wake one waiter and return `true`. Otherwise, return `false`. - /// If `try_lock` fails, return `false`. (REVIEW: why?) - /// (REVIEW: is it redundant to express that `waiting` and `done` are accesed under a mutex?) + /// If `try_lock` fails, return `false`. pub fn wake(&self) -> bool { if let Ok(ref mut this) = self.protected.try_lock() { if !this.waiting {