From 0ce53c96c30fe5438edf50251ca60b7655db1f2a Mon Sep 17 00:00:00 2001
From: Wouter van Oortmerssen <wvo@google.com>
Date: Mon, 17 Nov 2014 13:14:31 -0800
Subject: [PATCH] Clarified note on multi-threading in the docs.

Change-Id: Ib36ec71aab02fc66d2a6d0c916ebfa4dd1d0d02f
---
 docs/html/md__cpp_usage.html |  3 ++-
 docs/source/CppUsage.md      | 13 ++++++++++---
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/docs/html/md__cpp_usage.html b/docs/html/md__cpp_usage.html
index 746bbb101..d71a278bb 100644
--- a/docs/html/md__cpp_usage.html
+++ b/docs/html/md__cpp_usage.html
@@ -137,7 +137,8 @@ $(document).ready(function(){initNavTree('md__cpp_usage.html','');});
 <p>After each JSON file, the <code>Parser::fbb</code> member variable is the <code>FlatBufferBuilder</code> that contains the binary buffer version of that file, that you can access as described above.</p>
 <p><code>samples/sample_text.cpp</code> is a code sample showing the above operations.</p>
 <h3>Threading</h3>
-<p>None of the code is thread-safe, by design. That said, since currently a FlatBuffer is read-only and entirely <code>const</code>, reading by multiple threads is possible. </p>
+<p>Reading a FlatBuffer does not touch any memory outside the original buffer, and is entirely read-only (all const), so is safe to access from multiple threads even without synchronisation primitives.</p>
+<p>Creating a FlatBuffer is not thread safe. All state related to building a FlatBuffer is contained in a FlatBufferBuilder instance, and no memory outside of it is touched. To make this thread safe, either do not share instances of FlatBufferBuilder between threads (recommended), or manually wrap it in synchronisation primites. There's no automatic way to accomplish this, by design, as we feel multithreaded construction of a single buffer will be rare, and synchronisation overhead would be costly. </p>
 </div></div><!-- contents -->
 </div><!-- doc-content -->
 <!-- Google Analytics -->
diff --git a/docs/source/CppUsage.md b/docs/source/CppUsage.md
index 9721c6c06..a941ce40f 100755
--- a/docs/source/CppUsage.md
+++ b/docs/source/CppUsage.md
@@ -291,7 +291,14 @@ file, that you can access as described above.
 
 ### Threading
 
-None of the code is thread-safe, by design. That said, since currently a
-FlatBuffer is read-only and entirely `const`, reading by multiple threads
-is possible.
+Reading a FlatBuffer does not touch any memory outside the original buffer,
+and is entirely read-only (all const), so is safe to access from multiple
+threads even without synchronisation primitives.
 
+Creating a FlatBuffer is not thread safe. All state related to building
+a FlatBuffer is contained in a FlatBufferBuilder instance, and no memory
+outside of it is touched. To make this thread safe, either do not
+share instances of FlatBufferBuilder between threads (recommended), or
+manually wrap it in synchronisation primites. There's no automatic way to
+accomplish this, by design, as we feel multithreaded construction
+of a single buffer will be rare, and synchronisation overhead would be costly.