Add some thread-safety guarantees to interface

include/VersionedMap.h

@@ -27,7 +27,14 @@ namespace weaselab {
  * key and version, and provides an iterator api which can be used to merge
  * versioned results with an underlying unversioned data structure. @warning you
  * must not apply mutations to your data structure through a version that
- * overtakes a concurrent versioned reader.  */
+ * overtakes a concurrent versioned reader.
+
+  * Thread safety:
+ *   - It's safe to operate on two different VersionedMaps in two different
+ * threads concurrently
+ *   - It's safe to have multiple threads operating on the same VersionedMap
+ * concurrently if and only if all threads only call const methods.
+ */
 struct VersionedMap {
 
   /** Indicates how `Mutation::param1` and `Mutation::param2` are to be
@@ -126,12 +133,14 @@ struct VersionedMap {
 
   /** Perform `count` "first greater than or equal to" queries. The result of
    * querying `key[i]` at `version[i]` is `iterator[i]`. `version[i]` must be >=
-   * `getOldestVersion()` and <= `getVersion()`. */
+   * `getOldestVersion()` and <= `getVersion()`. Thread-safe as long as a
+   * version is not concurrently invalidated by `setOldestVersion`. */
   void firstGeq(const Key *key, const int64_t *version, Iterator *iterator,
                 int count) const;
 
   /** Returns an iterator to the first mutation visible at `version`, or `end()`
-   * if none exists.*/
+   * if none exists. Thread-safe as long as `version` is not concurrently
+   * invalidated by `setOldestVersion`. */
   Iterator begin(int64_t version) const;
 
   /** The "past-the-end" iterator. */