From e745885906661736b370a06fcfbde49e13f9a9d5 Mon Sep 17 00:00:00 2001
From: Klaus Basan <klaus.basan@klausbasan.de>
Date: Mon, 29 Sep 2014 03:35:06 +0200
Subject: [PATCH] refs #325, added some comments to simplify review

---
 src/blackgui/models/listmodelbase.h |  3 ++-
 src/blackgui/updateworker.h         | 15 ++++++++++-----
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/src/blackgui/models/listmodelbase.h b/src/blackgui/models/listmodelbase.h
index eee3b6616..077b1edbb 100644
--- a/src/blackgui/models/listmodelbase.h
+++ b/src/blackgui/models/listmodelbase.h
@@ -171,7 +171,7 @@ namespace BlackGui
              * \param container used list
              * \param column    column inder
              * \param order     sort order (ascending / descending)
-             * \threadsafe
+             * \threadsafe under normal conditions thread safe as long as the column metadata are not changed
              */
             ContainerType sortContainerByColumn(const ContainerType &container, int column, Qt::SortOrder order) const;
 
@@ -247,6 +247,7 @@ namespace BlackGui
                             m_container = m_model->sortContainerByColumn(m_container, m_sortColumn, m_sortOrder);
                         }
                         // now update model itself thread safe, but time for sort was saved
+                        // the invoked method itself will run in the main thread's event loop again
                         QMetaObject::invokeMethod(m_model, "updateContainer", Qt::QueuedConnection,
                                                   Q_ARG(QVariant, m_container.toQVariant()), Q_ARG(bool, false));
                     }
diff --git a/src/blackgui/updateworker.h b/src/blackgui/updateworker.h
index 47320c270..76b6ed11a 100644
--- a/src/blackgui/updateworker.h
+++ b/src/blackgui/updateworker.h
@@ -18,7 +18,8 @@
 
 namespace BlackGui
 {
-    //! Base class for workers
+    //! Base class for workers. Runs itself in newly created thread when started.
+    //! Provides access to related thread and cleans up itself when done.
     class IUpdateWorker : public QObject
     {
         Q_OBJECT
@@ -45,15 +46,19 @@ namespace BlackGui
         }
 
         //! Start thread, return nullptr if cannot be started
-        //! \remarks If start fails, object needs to be terminated manually
+        //! \remarks If start fails (false), object needs to be terminated manually
         bool start()
         {
+            qDebug() << "before init thread" << QThread::currentThreadId();
             if (!m_thread) { initializeThread(); }
-            m_thread->start();
+            m_thread->start(); // starting, not yet doing anything
+
+            // m_thread will start with invocation by event loop
+            // invokeMethod "schedules" an update running in the newly created thread
             bool ok = QMetaObject::invokeMethod(this, "ps_runUpdate", Qt::QueuedConnection);
             if (ok) { return true; }
 
-            // startup failed
+            // invocation failed, so I can clean up thread straight away
             this->terminateThread();
             return false;
         }
@@ -71,7 +76,7 @@ namespace BlackGui
         //! Update, call virtual method so inheriting class needs no slots
         void ps_runUpdate()
         {
-            this->update();
+            this->update(); // call overridden method doing work
             emit this->updateFinished();
             this->terminate(); // clean up thread, delete worker (myself)
         }