Documentation for concurrent and small improvements

git-svn-id: svn://db.shs.com.ru/pip@868 12ceb7fc-bf1f-11e4-8940-5bc7170c53b5

src_main/concurrent/executor.h

@@ -72,9 +72,7 @@ public:
      * accepted. Invocation has no additional effect if already shut down. This method does not wait for previously
      * submitted tasks to complete execution. Use awaitTermination to do that.
      */
-    void shutdown() {
-        isShutdown_ = true;
-    }
+    void shutdown();
 
     volatile bool isShutdown() const;
 

src_main/concurrent/piblockingdequeue.h

@@ -15,19 +15,38 @@
 template <typename T>
 class PIBlockingDequeue: private PIDeque<T> {
 public:
-    explicit inline PIBlockingDequeue(size_t capacity = SIZE_MAX, PIConditionVariable* cond_var = new PIConditionVariable()) : condition_var(cond_var), max_size(capacity) { }
-    explicit inline PIBlockingDequeue(const PIDeque<T>& other) : condition_var(new PIConditionVariable()) {
+    explicit inline PIBlockingDequeue(size_t capacity = SIZE_MAX,
+                                      PIConditionVariable* cond_var_add = new PIConditionVariable(),
+                                      PIConditionVariable* cond_var_rem = new PIConditionVariable())
+                                      : cond_var_add(cond_var_add), cond_var_rem(cond_var_rem), max_size(capacity) { }
+    explicit inline PIBlockingDequeue(const PIDeque<T>& other) : cond_var_add(new PIConditionVariable()), cond_var_rem(new PIConditionVariable()) {
         max_size = SIZE_MAX;
         PIDeque<T>::append(other);
     }
-    inline PIBlockingDequeue(PIBlockingDequeue<T> & other) : condition_var(new PIConditionVariable()) {
+    inline PIBlockingDequeue(PIBlockingDequeue<T> & other) : cond_var_add(new PIConditionVariable()), cond_var_rem(new PIConditionVariable()) {
         other.mutex.lock();
         max_size = other.max_size;
         PIDeque<T>::append(static_cast<PIDeque<T>&>(other));
         other.mutex.unlock();
     }
     virtual ~PIBlockingDequeue() {
-        delete condition_var;
+        delete cond_var_add;
+        delete cond_var_rem;
+    }
+
+    /**
+     * @brief Inserts the specified element into this queue, waiting if necessary for space to become available.
+     *
+     * @todo write tests
+     *
+     * @param v the element to add
+     */
+    virtual void put(const T & v) {
+        mutex.lock();
+        cond_var_rem->wait(mutex, [&]() { return PIDeque<T>::size() < max_size; });
+        PIDeque<T>::push_back(v);
+        mutex.unlock();
+        cond_var_add->notifyOne();
     }
 
     /**
@@ -45,7 +64,7 @@ public:
         }
         PIDeque<T>::push_back(v);
         mutex.unlock();
-        condition_var->notifyOne();
+        cond_var_add->notifyOne();
         return true;
     }
 
@@ -57,9 +76,10 @@ public:
     virtual T take() {
         T t;
         mutex.lock();
-        condition_var->wait(mutex, [&]() { return !PIDeque<T>::isEmpty(); });
+        cond_var_add->wait(mutex, [&]() { return !PIDeque<T>::isEmpty(); });
         t = T(PIDeque<T>::take_front());
         mutex.unlock();
+        cond_var_rem->notifyOne();
         return t;
     }
 
@@ -74,9 +94,10 @@ public:
     virtual T poll(int timeoutMs, const T & defaultVal) {
         T t;
         mutex.lock();
-        bool isOk = condition_var->waitFor(mutex, timeoutMs, [&]() { return !PIDeque<T>::isEmpty(); });
+        bool isOk = cond_var_add->waitFor(mutex, timeoutMs, [&]() { return !PIDeque<T>::isEmpty(); });
         t = isOk ? T(PIDeque<T>::take_front()) : defaultVal;
         mutex.unlock();
+        if (isOk) cond_var_rem->notifyOne();
         return t;
     }
 
@@ -134,13 +155,10 @@ public:
         return count;
     }
 
-    PIConditionVariable *getConditionVar() const {
-        return condition_var;
-    }
-
 private:
     PIConditionLock mutex;
-    PIConditionVariable* condition_var;
+    PIConditionVariable* cond_var_add;
+    PIConditionVariable* cond_var_rem;
     size_t max_size;
 };
 

src_main/concurrent/piconditionlock.h

@@ -8,10 +8,13 @@
 #include <pimutex.h>
 #include <piinit.h>
 
+/**
+ * @brief Continued
+ */
 class PIP_EXPORT PIConditionLock {
 public:
     explicit PIConditionLock();
-    ~PIConditionLock();
+    virtual ~PIConditionLock();
 
     void lock();
     void unlock();

src_main/concurrent/piconditionvar.h

@@ -9,15 +9,29 @@
 #include <functional>
 #include "piinit.h"
 
-#define PICONDITION_RELIABLE true
-
+/**
+ * @brief A condition variable is an object able to block the calling thread until notified to resume.
+ *
+ * It uses a PIConditionLock to lock the thread when one of its wait functions is called. The thread remains
+ * blocked until woken up by another thread that calls a notification function on the same PIConditionVariable object.
+ */
 class PIP_EXPORT PIConditionVariable {
 public:
     explicit PIConditionVariable();
     virtual ~PIConditionVariable();
 
+    /**
+     * @brief Unblocks one of the threads currently waiting for this condition. If no threads are waiting, the function
+     * does nothing. If more than one, it is unspecified which of the threads is selected.
+     */
     virtual void notifyOne();
+
+    /**
+     * @brief Unblocks all threads currently waiting for this condition. If no threads are waiting, the function does
+     * nothing.
+     */
     virtual void notifyAll();
+
     virtual void wait(PIConditionLock& lk);
     virtual void wait(PIConditionLock& lk, const std::function<bool()>& condition);
     virtual bool waitFor(PIConditionLock& lk, int timeoutMs);