Merge pull request #92 from ratijas/futures

Futures: typos, code style, docs

Author: ratijas

qmetaobject/src/future.rs

@@ -3,15 +3,15 @@ use std::future::Future;
 use std::os::raw::c_void;
 use std::pin::Pin;
 
-static QTWAKERVTABLE: std::task::RawWakerVTable = unsafe {
+static QT_WAKER_VTABLE: std::task::RawWakerVTable = unsafe {
     std::task::RawWakerVTable::new(
         |s: *const ()| {
             std::task::RawWaker::new(
                 cpp!([s as "Waker*"] -> *const() as "Waker*" {
-                    s->ref++;
+                    s->refs++;
                     return s;
                 }),
-                &QTWAKERVTABLE,
+                &QT_WAKER_VTABLE,
             )
         },
         |s: *const ()| {
@@ -34,35 +34,59 @@ static QTWAKERVTABLE: std::task::RawWakerVTable = unsafe {
 };
 
 cpp! {{
+    /// Special QObject subclass to glue together internals of Rust's futures and Qt's events.
+    /// It's lifetime is determined through reference counting, and its lifecycle is based on
+    /// Qt's QObject rather than C++ RAII.
     struct Waker : QObject {
-    public:
+        /// Wrapped Rust's Future as a dynamic trait object.
         TraitObject future;
+        /// Guard against redundant processing of multiple consecutive wake-up calls.
         bool woken = false;
+        /// Guard against polling a future after it has been completed.
         bool completed = false;
-        QAtomicInt ref = 0;
+        /// Reference counter.
+        QAtomicInt refs = 0;
+
+        // start with refs count of 1, because caller gets the ownership.
+        Waker(TraitObject f): future(f), refs(1) {}
+
         void customEvent(QEvent *e) override {
             Q_UNUSED(e);
             woken = false;
             // future must not be polled after it returned `Poll::Ready`
-            if (completed) return;
-            completed = rust!(ProcessQtEvent [this: *const() as "Waker*",
-                future : *mut dyn Future<Output=()> as "TraitObject"] -> bool as "bool" {
+            if (completed) {
+                return;
+            }
+            completed = rust!(ProcessQtEvent [
+                this: *const () as "Waker*",
+                future: *mut dyn Future<Output=()> as "TraitObject"
+            ] -> bool as "bool" {
                 poll_with_qt_waker(this, Pin::new_unchecked(&mut *future))
             });
-            if (completed) deref();
+            if (completed) {
+                deref();
+            }
         }
+
         void deref() {
-            if (!--ref) {
+            if (!--refs) {
                 deleteLater();
             }
         }
+
         void wake() {
-            if (woken) return;
+            if (woken) {
+                return;
+            }
             woken = true;
+            // This line results in invocation of customEvent(QEvent*) method above.
+            // Note that object may be waken multiple times before the wake up call
+            // actually gets proceeded by the Qt's event loop.
             QApplication::postEvent(this, new QEvent(QEvent::User));
         }
+
         ~Waker() {
-            rust!(QtDestroyFuture [future : *mut dyn Future<Output=()> as "TraitObject"] {
+            rust!(QtDestroyFuture [future: *mut dyn Future<Output=()> as "TraitObject"] {
                 std::mem::drop(Box::from_raw(future))
             });
         }
@@ -81,18 +105,16 @@ pub fn execute_async(f: impl Future<Output = ()> + 'static) {
     let f = Box::into_raw(Box::new(f)) as *mut dyn Future<Output = ()>;
     unsafe {
         let waker = cpp!([f as "TraitObject"] -> *const() as "Waker*" {
-            auto w = new Waker;
-            w->ref++;
-            w->future = f;
-            return w;
+            return new Waker(f);
         });
         poll_with_qt_waker(waker, Pin::new_unchecked(&mut *f));
     }
 }
 
+// SAFETY: caller must ensure that given future hasn't returned Poll::Ready earlier.
 unsafe fn poll_with_qt_waker(waker: *const (), future: Pin<&mut dyn Future<Output = ()>>) -> bool {
-    cpp!([waker as "Waker*"] { waker->ref++; });
-    let waker = std::task::RawWaker::new(waker, &QTWAKERVTABLE);
+    cpp!([waker as "Waker*"] { waker->refs++; });
+    let waker = std::task::RawWaker::new(waker, &QT_WAKER_VTABLE);
     let waker = std::task::Waker::from_raw(waker);
     let mut context = std::task::Context::from_waker(&waker);
     future.poll(&mut context).is_ready()
@@ -103,9 +125,11 @@ unsafe fn poll_with_qt_waker(waker: *const (), future: Pin<&mut dyn Future<Outpu
 /// The arguments of the signal need to implement `Clone`, and the Output of the future is a tuple
 /// containing the arguments of the signal (or the empty tuple if there are none.)
 ///
-/// The future will be ready as soon as the signal is emited.
+/// The future will be ready as soon as the signal is emitted.
+///
+/// This is unsafe for the same reason that [`connections::connect`][] is unsafe.
 ///
-/// This is unsafe for the same reason that connections::connect is unsafe.
+/// [`connections::connect`]: ../connections/fn.connect.html
 pub unsafe fn wait_on_signal<Args: SignalArgArrayToTuple>(
     sender: *const c_void,
     signal: crate::connections::CppSignal<Args>,