Add docs to WorkQueue and GlyphStore

3 files changed, 21 insertions, 3 deletions

diff --git a/src/mbgl/text/glyph_store.cpp b/src/mbgl/text/glyph_store.cpp
index 17c1524a88..f34f8ecd04 100644
--- a/src/mbgl/text/glyph_store.cpp
+++ b/src/mbgl/text/glyph_store.cpp
@@ -59,8 +59,10 @@ bool GlyphStore::hasGlyphRanges(const std::string& fontStackName, const std::set
     for (const auto& range : glyphRanges) {
         const auto& rangeSetsIt = rangeSets.find(range);
         if (rangeSetsIt == rangeSets.end()) {
-            // Post the request to the Map thread.
+            // Push the request to the MapThread, so we can easly cancel
+            // if it is still pending when we destroy this object.
             workQueue.push(std::bind(&GlyphStore::requestGlyphRange, this, fontStackName, range));
+
             hasRanges = false;
             continue;
         }
@@ -81,6 +83,8 @@ util::exclusive<FontStack> GlyphStore::createFontStack(const std::string& fontSt
         it = stacks.emplace(fontStack, std::make_unique<FontStack>()).first;
     }
 
+    // FIXME: We lock all FontStacks, but what we should
+    // really do is lock only the one we are returning.
     return { it->second.get(), std::move(lock) };
 }
 
diff --git a/src/mbgl/text/glyph_store.hpp b/src/mbgl/text/glyph_store.hpp
index 5d0f498c71..1e31e77bf5 100644
--- a/src/mbgl/text/glyph_store.hpp
+++ b/src/mbgl/text/glyph_store.hpp
@@ -16,7 +16,9 @@ namespace mbgl {
 class FontStack;
 class GlyphPBF;
 
-// Manages GlyphRange PBF loading.
+// The GlyphStore manages the loading and storage of Glyphs
+// and creation of FontStack objects. The GlyphStore lives
+// on the MapThread but can be queried from any thread.
 class GlyphStore {
 public:
     class Observer {
@@ -32,6 +34,11 @@ public:
 
     util::exclusive<FontStack> getFontStack(const std::string& fontStack);
 
+    // Returns true if the set of GlyphRanges are available and parsed or false
+    // if they are not. For the missing ranges, a request on the FileSource is
+    // made and when the glyph if finally parsed, it gets added to the respective
+    // FontStack and a signal is emitted to notify the observers. This method
+    // can be called from any thread.
     bool hasGlyphRanges(const std::string& fontStackName, const std::set<GlyphRange>& glyphRanges);
 
     void setURL(const std::string &url) {
diff --git a/src/mbgl/util/work_queue.hpp b/src/mbgl/util/work_queue.hpp
index dcec5668b9..55b687a468 100644
--- a/src/mbgl/util/work_queue.hpp
+++ b/src/mbgl/util/work_queue.hpp
@@ -14,11 +14,18 @@ namespace util {
 
 class RunLoop;
 
+// The WorkQueue will manage a queue of closures
+// and it will make sure they get executed on the
+// thread that created the WorkQueue. All pending
+// works are canceled when the queue gets destructed.
 class WorkQueue : private util::noncopyable {
 public:
     WorkQueue();
-    virtual ~WorkQueue();
+    ~WorkQueue();
 
+    // Push a closure to the queue. It is advised to
+    // only push tasks calling functions on the object
+    // that owns the queue to avoid use after free errors.
     void push(std::function<void()>&&);
 
 private: