Changeset 57612 in vbox

Timestamp:

Sep 3, 2015 5:13:56 PM (9 years ago)

Author:

vboxsync

Message:

FE/Qt: Thread-pool: Doxy.

Location:

trunk/src/VBox/Frontends/VirtualBox/src/globals

Files:

• UIThreadPool.cpp (modified) (1 diff)
• UIThreadPool.h (modified) (4 diffs)

trunk/src/VBox/Frontends/VirtualBox/src/globals/UIThreadPool.cpp

@@ -1 +1 @@
 /* $Id$ */
 /** @file
- * VBox Qt GUI - UIThreadPool and UITask class implementation.
+ * VBox Qt GUI - UIThreadPool and UITask classes implementation.
  */
 
 /*
- * Copyright (C) 2013 Oracle Corporation
+ * Copyright (C) 2013-2015 Oracle Corporation
  *
  * This file is part of VirtualBox Open Source Edition (OSE), as

trunk/src/VBox/Frontends/VirtualBox/src/globals/UIThreadPool.h

@@ -1 +1 @@
 /* $Id$ */
 /** @file
- * VBox Qt GUI - UIThreadPool and UITask class declaration.
+ * VBox Qt GUI - UIThreadPool and UITask classes declaration.
  */
 
 /*
- * Copyright (C) 2013 Oracle Corporation
+ * Copyright (C) 2013-2015 Oracle Corporation
  *
  * This file is part of VirtualBox Open Source Edition (OSE), as
@@ -31 +31 @@
 class UITask;
 
-/* Worker-thread pool prototype.
- * Schedules COM-related GUI tasks to multiple worker-threads. */
+/** QObject extension used as worker-thread pool.
+  * Schedules COM-related GUI tasks to multiple worker-threads. */
 class UIThreadPool : public QObject
 {
@@ -39 +39 @@
 signals:
 
-    /* Notifier: Task-queue stuff: */
+    /** Notifies listeners about @a pTask complete. */
     void sigTaskComplete(UITask *pTask);
 
 public:
 
-    /* Constructor/destructor: */
+    /** Constructs worker-thread pool.
+      * @param cMaxWorkers          defines the maximum amount of worker-threads.
+      * @param cMsWorkerIdleTimeout defines the maximum amount of time (in ms) which
+      *                             pool will wait for the worker-thread on cleanup. */
     UIThreadPool(ulong cMaxWorkers = 3, ulong cMsWorkerIdleTimeout = 5000);
+    /** Destructs worker-thread pool. */
     ~UIThreadPool();
 
-    /* API: Task-queue stuff: */
+    /** Enqueues @a pTask into task-queue. */
     void enqueueTask(UITask *pTask);
 
-    /* API: Termination stuff: */
+    /** Returns whether the 'termination sequence' is started. */
     bool isTerminating() const;
+    /** Defines that the 'termination sequence' is started. */
     void setTerminating();
 
 protected:
 
-    /* Protected API: Worker-thread stuff: */
+    /** Returns dequeued top-most task from the task-queue using @a pWorker as a hint.
+      * @remarks Called by the worker-thread. */
     UITask* dequeueTask(UIThreadWorker *pWorker);
 
 private slots:
 
-    /* Handler: Task-queue stuff: */
+    /** Handles @a pTask complete signal. */
     void sltHandleTaskComplete(UITask *pTask);
 
-    /* Handler: Worker stuff: */
+    /** Handles @a pWorker finished signal. */
     void sltHandleWorkerFinished(UIThreadWorker *pWorker);
 
 private:
 
-    /** @name Worker thread related variables.
+    /** @name Worker-thread stuff.
      * @{ */
-    QVector<UIThreadWorker*> m_workers;
-    /** Milliseconds  */
-    const ulong m_cMsIdleTimeout;
-    /** The number of worker threads.
-     * @remarks We cannot use the vector size since it may contain NULL pointers. */
-    int m_cWorkers;
-    /** The number of idle worker threads. */
-    int m_cIdleWorkers;
-    /** Set by the destructor to indicate that all worker threads should
-     *  terminate ASAP. */
-    bool m_fTerminating;
+        /** Holds the maximum amount of time (in ms) which
+          * pool will wait for the worker-thread on cleanup. */
+        const ulong m_cMsIdleTimeout;
+        /** Holds the vector of worker-threads. */
+        QVector<UIThreadWorker*> m_workers;
+        /** Holds the number of worker-threads.
+          * @remarks We cannot use the vector size since it may contain NULL pointers. */
+        int m_cWorkers;
+        /** Holds the number of idle worker-threads. */
+        int m_cIdleWorkers;
+        /** Holds whether the 'termination sequence' is started
+          * and all worker-threads should terminate ASAP. */
+        bool m_fTerminating;
     /** @} */
 
-    /** @name Task related variables
+    /** @name Task stuff
      * @{ */
-    /** Queue (FIFO) of pending tasks. */
-    QQueue<UITask*> m_tasks;
-    /** Condition variable that gets signalled when queuing a new task and there are
-     * idle worker threads around.
-     *
-     * Idle threads sits in dequeueTask waiting for this. Thus on thermination
-     * setTerminating() will do a broadcast signal to wake up all workers (after
-     * setting m_fTerminating of course). */
-    QWaitCondition m_taskCondition;
+        /** Holds the queue (FIFO) of pending tasks. */
+        QQueue<UITask*> m_tasks;
+        /** Holds the condition variable that gets signalled when
+          * queuing a new task and there are idle worker threads around.
+          * @remarks Idle threads sits in dequeueTask waiting for this.
+          *          Thus on thermination, setTerminating() will send a
+          *          broadcast signal to wake up all workers (after
+          *          setting m_fTerminating of course). */
+        QWaitCondition m_taskCondition;
     /** @} */
 
-
-    /** This mutex is used with the m_taskCondition condition and protects m_tasks,
-     *  m_fTerminating and m_workers. */
+    /** Holds the guard mutex object protecting
+      * all the inter-thread variables. */
     mutable QMutex m_everythingLocker;
 
-    /* Friends: */
+    /** Allows UIThreadWorker to dequeue tasks. */
     friend class UIThreadWorker;
 };
 
-/* GUI task interface.
- * Describes executable task to be used with UIThreadPool object. */
+/** QObject extension used as worker-thread task.
+  * Describes task to be executed by the UIThreadPool object. */
 class UITask : public QObject
 {
@@ -115 +122 @@
 signals:
 
-    /* Notifier: Task stuff: */
+    /** Notifies listeners about @a pTask complete. */
     void sigComplete(UITask *pTask);
 
 public:
 
-    /* Constructor: */
+    /** Constructs worker-thread task.
+      * @param data defines inter-thread task data to be processed by worker-thread. */
     UITask(const QVariant &data);
 
-    /* API: Data stuff: */
+    /** Returns the inter-thread task data. */
     const QVariant& data() const;
-
-    /* API: Run stuff: */
-    void start();
 
 protected:
 
-    /* Helper: Run stuff: */
+    /** Starts the task.
+      * @remarks Called by the worker-thread. */
+    void start();
+
+    /** Contains the abstract task body, to be reimplemented in sub-class. */
     virtual void run() = 0;
 
-    /* Variable: Data stuff: */
+//private:
+
+    /** Holds the inter-thread task data to be processed by worker-thread. */
     QVariant m_data;
+
+    /** Allows UIThreadWorker to start task. */
+    friend class UIThreadWorker;
 };