BlockingDequeue put and offer logic && documentation for concurrent

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

src_main/concurrent/piconditionvar.h

@@ -32,9 +32,67 @@ public:
      */
     virtual void notifyAll();
 
+    /**
+     * @brief see wait(PIConditionLock&, const std::function<bool()>&)
+     */
     virtual void wait(PIConditionLock& lk);
+
+    /**
+     * @brief Wait until notified
+     *
+     * The execution of the current thread (which shall have locked with lk method PIConditionLock::lock()) is blocked
+     * until notified.
+     *
+     * At the moment of blocking the thread, the function automatically calls lk.unlock() (PIConditionLock::unlock()),
+     * allowing other locked threads to continue.
+     *
+     * Once notified (explicitly, by some other thread), the function unblocks and calls lk.lock() (PIConditionLock::lock()),
+     * leaving lk in the same state as when the function was called. Then the function returns (notice that this last mutex
+     * locking may block again the thread before returning).
+     *
+     * Generally, the function is notified to wake up by a call in another thread either to member notifyOne() or to
+     * member notifyAll(). But certain implementations may produce spurious wake-up calls without any of these functions
+     * being called. Therefore, users of this function shall ensure their condition for resumption is met.
+     *
+     * If condition is specified, the function only blocks if condition returns false, and notifications can only unblock
+     * the thread when it becomes true (which is specially useful to check against spurious wake-up calls).
+     *
+     * @param lk lock object used by method wait for data protection
+     * @param condition A callable object or function that takes no arguments and returns a value that can be evaluated
+     * as a bool. This is called repeatedly until it evaluates to true.
+     */
     virtual void wait(PIConditionLock& lk, const std::function<bool()>& condition);
+
+    /**
+     * @brief see waitFor(PIConditionLock&, int, const std::function<bool()>&)
+     */
     virtual bool waitFor(PIConditionLock& lk, int timeoutMs);
+
+    /**
+     * @brief Wait for timeout or until notified
+     *
+     * The execution of the current thread (which shall have locked with lk method PIConditionLock::lock()) is blocked
+     * during timeoutMs, or until notified (if the latter happens first).
+     *
+     * At the moment of blocking the thread, the function automatically calls lk.lock() (PIConditionLock::lock()), allowing
+     * other locked threads to continue.
+     *
+     * Once notified or once timeoutMs has passed, the function unblocks and calls lk.unlock() (PIConditionLock::unlock()),
+     * leaving lk in the same state as when the function was called. Then the function returns (notice that this last
+     * mutex locking may block again the thread before returning).
+     *
+     * Generally, the function is notified to wake up by a call in another thread either to member notifyOne() or to
+     * member notifyAll(). But certain implementations may produce spurious wake-up calls without any of these functions
+     * being called. Therefore, users of this function shall ensure their condition for resumption is met.
+     *
+     * If condition is specified, the function only blocks if condition returns false, and notifications can only unblock
+     * the thread when it becomes true (which is especially useful to check against spurious wake-up calls).
+     *
+     * @param lk lock object used by method wait for data protection
+     * @param condition A callable object or function that takes no arguments and returns a value that can be evaluated
+     * as a bool. This is called repeatedly until it evaluates to true.
+     * @return false if timeout reached or true if wakeup condition is true
+     */
     virtual bool waitFor(PIConditionLock& lk, int timeoutMs, const std::function<bool()>& condition);
 private:
     NO_COPY_CLASS(PIConditionVariable)