From 174687c4bcfbd3e66287d15e9fba1089c8dd3813 Mon Sep 17 00:00:00 2001
From: Strahinja Val Markovic <val@markovic.io>
Date: Fri, 6 Jul 2012 12:14:25 -0700
Subject: [PATCH] Renaming ConcurrentStack to ConcurrentLatestValue

---
 cpp/ycm/Completer.cpp                         |  8 +++---
 cpp/ycm/Completer.h                           |  8 +++---
 ...currentStack.h => ConcurrentLatestValue.h} | 28 +++++++++++++------
 python/ycm.py                                 |  1 +
 4 files changed, 29 insertions(+), 16 deletions(-)
 rename cpp/ycm/{ConcurrentStack.h => ConcurrentLatestValue.h} (55%)

diff --git a/cpp/ycm/Completer.cpp b/cpp/ycm/Completer.cpp
index d3f7fcbc..b81296e0 100644
--- a/cpp/ycm/Completer.cpp
+++ b/cpp/ycm/Completer.cpp
@@ -42,11 +42,11 @@ namespace
 const unsigned int MAX_ASYNC_THREADS = 4;
 const unsigned int MIN_ASYNC_THREADS = 2;
 
-void ThreadMain( TaskStack &task_stack )
+void ThreadMain( LatestTask &latest_task )
 {
   while ( true )
   {
-    ( *task_stack.Get() )();
+    ( *latest_task.Get() )();
   }
 }
 
@@ -171,7 +171,7 @@ Future Completer::CandidatesForQueryAndTypeAsync(
 
   unique_future< AsyncResults > future = task->get_future();
 
-  task_stack_.Set( task );
+  latest_task_.Set( task );
   return Future( move( future ) );
 }
 
@@ -242,7 +242,7 @@ void Completer::InitThreads()
 
   for ( int i = 0; i < threads_to_create; ++i )
   {
-    threads_.create_thread( bind( ThreadMain, boost::ref( task_stack_ ) ) );
+    threads_.create_thread( bind( ThreadMain, boost::ref( latest_task_ ) ) );
   }
 }
 
diff --git a/cpp/ycm/Completer.h b/cpp/ycm/Completer.h
index cc630d69..349af31f 100644
--- a/cpp/ycm/Completer.h
+++ b/cpp/ycm/Completer.h
@@ -19,7 +19,7 @@
 #define COMPLETER_H_7AR4UGXE
 
 #include "Candidate.h"
-#include "ConcurrentStack.h"
+#include "ConcurrentLatestValue.h"
 #include "Future.h"
 
 #include <boost/utility.hpp>
@@ -49,9 +49,9 @@ typedef boost::unordered_map< std::string,
 typedef boost::unordered_map< std::string,
           boost::shared_ptr< FilepathToCandidates > > FiletypeMap;
 
-typedef ConcurrentStack<
+typedef ConcurrentLatestValue<
           boost::shared_ptr<
-            boost::packaged_task< AsyncResults > > > TaskStack;
+            boost::packaged_task< AsyncResults > > > LatestTask;
 
 
 class Completer : boost::noncopyable
@@ -113,7 +113,7 @@ private:
 
   FiletypeMap filetype_map_;
 
-  mutable TaskStack task_stack_;
+  mutable LatestTask latest_task_;
 
   bool threading_enabled_;
 
diff --git a/cpp/ycm/ConcurrentStack.h b/cpp/ycm/ConcurrentLatestValue.h
similarity index 55%
rename from cpp/ycm/ConcurrentStack.h
rename to cpp/ycm/ConcurrentLatestValue.h
index a4f133d7..2259644f 100644
--- a/cpp/ycm/ConcurrentStack.h
+++ b/cpp/ycm/ConcurrentLatestValue.h
@@ -15,23 +15,36 @@
 // You should have received a copy of the GNU General Public License
 // along with YouCompleteMe.  If not, see <http://www.gnu.org/licenses/>.
 
-#ifndef CONCURRENTSTACK_H_SYF1JPPG
-#define CONCURRENTSTACK_H_SYF1JPPG
+#ifndef CONCURRENTLATESTVALUE_H_SYF1JPPG
+#define CONCURRENTLATESTVALUE_H_SYF1JPPG
 
-#include <stack>
 #include <boost/thread.hpp>
 #include <boost/utility.hpp>
 
 namespace YouCompleteMe
 {
 
+// This is is basically a multi-consumer single-producer queue, only with the
+// twist that we only care about the latest value set. So the GUI thread is the
+// setter, and the worker threads are the workers. The workers wait in line on
+// the condition variable and when the setter sets a value, a worker is chosen
+// to consume it.
+//
+// The point is that we always want to have one "fresh" worker thread ready to
+// work on our latest value. If a newer value is set, then we don't care what
+// happens to the old values.
+//
+// This implementation is mutex-based and is not lock-free. Normally using a
+// lock-free data structure makes more sense, but since the GUI thread goes
+// through VimL and Python on every keystroke, there's really no point. Those 5
+// nanoseconds it takes to lock a mutex are laughably negligible compared to the
+// VimL/Python overhead.
 template <typename T>
-class ConcurrentStack : boost::noncopyable
+class ConcurrentLatestValue : boost::noncopyable
 {
 public:
 
-  // TODO: rename this class, it's not a stack anymore
-  ConcurrentStack() : empty_( true ) {}
+  ConcurrentLatestValue() : empty_( true ) {}
 
   void Set( const T& data )
   {
@@ -59,7 +72,6 @@ public:
 
 
 private:
-  // std::stack< T > stack_;
   T latest_;
   bool empty_;
   boost::mutex mutex_;
@@ -69,4 +81,4 @@ private:
 
 } // namespace YouCompleteMe
 
-#endif /* end of include guard: CONCURRENTSTACK_H_SYF1JPPG */
+#endif /* end of include guard: CONCURRENTLATESTVALUE_H_SYF1JPPG */
diff --git a/python/ycm.py b/python/ycm.py
index dc075dd2..1ac4902d 100644
--- a/python/ycm.py
+++ b/python/ycm.py
@@ -116,6 +116,7 @@ def CompletionStartColumn():
 
   if current_column - start_column < min_num_chars:
     # for vim, -2 means not found but don't trigger an error message
+    # see :h complete-functions
     return -2
 
   return start_column