Sharing map documentation

Author: danpoe

src/util/sharing_map.h

@@ -39,6 +39,72 @@ Author: Daniel Poetzl
   CV typename sharing_mapt<keyT, valueT, hashT, predT>::ST \
   sharing_mapt<keyT, valueT, hashT, predT>
 
+/// A map implemented as a tree where subtrees can be shared between different
+/// maps.
+///
+/// The map is implemented as a fixed-height n-ary trie. The height H and the
+/// maximum number of children per inner node S are determined by the two
+/// configuration parameters `bits` and `chunks` in sharing_map.h. It holds
+/// that H = `bits` / `chunks` and S = 2 ^ `chunks`.
+///
+/// When inserting a key-value pair into the map, first the hash of its key is
+/// computed. The `bits` number of lower order bits of the hash are deemed
+/// significant, and are grouped into `bits` / `chunk` chunks. The hash is then
+/// treated as a string (with each chunk representing a character) for the
+/// purposes of determining the position of the key-value pair in the trie. The
+/// actual key-value pairs are stored in the leaf nodes. Collisions (i.e., two
+/// different keys yield the same "string"), are handled by chaining the
+/// corresponding key-value pairs in a `std::list`.
+///
+/// The use of a trie in combination with hashing has the advantage that the
+/// tree is unlikely to degenerate (if the number of hash collisions is low).
+/// This makes re-balancing operations unnecessary which do not interact well
+/// with sharing. A disadvantage is that the height of the tree is likely
+/// greater than if the elements had been stored in a balanced tree (with
+/// greater differences for sparser maps).
+///
+/// The nodes in the sharing map are objects of type sharing_nodet. Each sharing
+/// node has a `shared_ptr` to an object of type `dt` which can be shared
+/// between nodes.
+///
+/// Sharing is initially generated when a map is assigned to another map or
+/// copied via the copy constructor. Then both maps contain a pointer to the
+/// root node of the tree that represents the maps. On subsequent modifications
+/// to one of the maps, nodes are copied and sharing is lessened as described in
+/// the following.
+///
+/// Retrieval, insertion, and removal operations interact with sharing as
+/// follows:
+/// - When a non-const reference to a value in the map that is contained in a
+/// shared subtree is retrieved, the nodes on the path from the root of the
+/// subtree to the corresponding key-value pair (and the key-value pair itself)
+/// are copied and integrated with the map.
+/// - When a key-value pair is inserted into the map and its position is in a
+/// shared subtree, already existing nodes from the root of the subtree to the
+/// position of the key-value pair are copied and integrated with the map, and
+/// new nodes are created as needed.
+/// - When a key-value pair is erased from the map that is in a shared subtree,
+/// nodes from the root of the subtree to the last node that will still exist on
+/// the path to the erased element after the element has been removed are
+/// copied and integrated with the map, and the remaining nodes are removed.
+///
+/// Several methods take a hint indicating whether the element is known not to
+/// be in the map (`false`), known to be in the map (`true`), or it is unknown
+/// whether the element is in the map (`unknown`). The value `unknown` is always
+/// valid. When `true` or `false` are given they need to be accurate, otherwise
+/// the behavior is undefined. A correct hint can prevent the need to follow a
+/// path from the root to a key-value pair twice (e.g., once for checking that
+/// it exists, and second for copying nodes).
+///
+/// In the descriptions of the methods of the sharing map we also give the
+/// complexity of the operations. We use the following symbols:
+/// - N: number of key-value pairs in the map
+/// - M: maximum number of key-value pairs that are chained in a leaf node
+/// - H: height of the tree
+/// - S: maximum number of children per internal node
+///
+/// The first two symbols denote dynamic properties of a given map, whereas the
+/// last two symbols are static configuration parameters of the map class.
 template <
   class keyT,
   class valueT,
@@ -68,7 +134,16 @@ class sharing_mapt
 
   typedef size_t size_type;
 
+  /// Return type of methods that retrieve a const reference to a value. First
+  /// component is a reference to the value (or a dummy value if the given key
+  /// does not exist), and the second component indicates if the value with the
+  /// given key was found.
   typedef const std::pair<const mapped_type &, const bool> const_find_type;
+
+  /// Return type of methods that retrieve a reference to a value. First
+  /// component is a reference to the value (or a dummy value if the given key
+  /// does not exist), and the second component indicates if the value with the
+  /// given key was found.
   typedef const std::pair<mapped_type &, const bool> find_type;
 
   typedef std::vector<key_type> keyst;
@@ -89,7 +164,10 @@ class sharing_mapt
 
   static const std::string not_found_msg;
 
+  /// Number of bits in the hash deemed significant
   static const size_t bits;
+
+  /// Size of a chunk of the hash that represents a character
   static const size_t chunk;
 
   static const size_t mask;
@@ -136,6 +214,9 @@ class sharing_mapt
 
   mapped_type &operator[](const key_type &k);
 
+  /// Swap with other map
+  ///
+  /// Complexity: O(1)
   void swap(self_type &other)
   {
     map.swap(other.map);
@@ -145,22 +226,32 @@ class sharing_mapt
     other.num=tmp;
   }
 
+  /// Get number of elements in map
+  ///
+  /// Complexity: O(1)
   size_type size() const
   {
     return num;
   }
 
+  /// Check if map is empty
   bool empty() const
   {
     return num==0;
   }
 
+  /// Clear map
   void clear()
   {
     map.clear();
     num=0;
   }
 
+  /// Check if key is in map
+  ///
+  /// Complexity:
+  /// - Worst case: O(H * log(S) + M)
+  /// - Best case: O(H)
   bool has_key(const key_type &k) const
   {
     return get_leaf_node(k)!=nullptr;
@@ -169,6 +260,9 @@ class sharing_mapt
   // views
 
   typedef std::pair<const key_type &, const mapped_type &> view_itemt;
+
+  /// View of the key-value pairs in the map. A view is a list of pairs with
+  /// the components being const references to the keys and values in the map.
   typedef std::vector<view_itemt> viewt;
 
   class delta_view_itemt
@@ -194,6 +288,9 @@ class sharing_mapt
     const mapped_type &other_m;
   };
 
+  /// Delta view of the key-value pairs in two maps. A delta view of two maps is
+  /// a view of the key-value pairs in the maps that are contained in subtrees
+  /// that are not shared between them (also see get_delta_view()).
   typedef std::vector<delta_view_itemt> delta_viewt;
 
   void get_view(viewt &view) const;
@@ -214,6 +311,15 @@ class sharing_mapt
   void gather_all(const node_type &n, delta_viewt &delta_view) const;
 };
 
+/// Get a view of the elements in the map
+/// A view is a list of pairs with the components being const references to the
+/// keys and values in the map.
+///
+/// Complexity:
+/// - Worst case: O(N * H * log(S))
+/// - Best case: O(N + H)
+///
+/// \param[out] view: Empty view
 SHARING_MAPT(void)::get_view(viewt &view) const
 {
   assert(view.empty());
@@ -286,6 +392,39 @@ SHARING_MAPT(void)::gather_all(const node_type &n, delta_viewt &delta_view)
   while(!stack.empty());
 }
 
+/// Get a delta view of the elements in the map
+///
+/// Informally, a delta view of two maps is a view of the key-value pairs in the
+/// maps that are contained in subtrees that are not shared between them.
+///
+/// A delta view is represented as a list of structs, with each struct having
+/// four members (`in_both`, `key`, `value1`, `value2`). The elements `key`,
+/// `value1`, and `value2` are const references to the corresponding elements in
+/// the map. The first element indicates whether the key exists in both maps,
+/// the second element is the key, the third element is the mapped value of the
+/// first map, and the fourth element is the mapped value of the second map, or
+/// a dummy element if the key exists only in the first map (in which case
+/// `in_both` is false).
+///
+/// Calling `A.delta_view(B, ...)` yields a view such that for each element in
+/// the view one of two things holds:
+/// - the key is contained in both A and B, and in the maps the corresponding
+///   key-value pairs are not contained in a subtree that is shared between them
+/// - the key is only contained in A
+///
+/// When `only_common=true`, the first case above holds for every element in the
+/// view.
+///
+/// Complexity:
+/// - Worst case: O(max(N1, N2) * H * log(S) * M1 * M2) (no sharing)
+/// - Best case: O(1) (maximum sharing)
+///
+/// The symbols N1, M1 refer to map A, and symbols N2, M2 refer to map B.
+///
+/// \param other: other map
+/// \param[out] delta_view: Empty delta view
+/// \param only_common: Indicates if the returned delta view should only
+///   contain key-value pairs for keys that exist in both maps
 SHARING_MAPT(void)::get_delta_view(
   const self_type &other,
   delta_viewt &delta_view,
@@ -439,6 +578,15 @@ SHARING_MAPT2(const, node_type *)::get_leaf_node(const key_type &k) const
   return p;
 }
 
+/// Erase element
+///
+/// Complexity:
+/// - Worst case: O(H * S + M)
+/// - Best case: O(H)
+///
+/// \param k: The key of the element to erase
+/// \param key_exists: Hint to indicate whether the element is known to exist
+///   (possible values `unknown` or` true`)
 SHARING_MAPT2(, size_type)::erase(
   const key_type &k,
   const tvt &key_exists)
@@ -488,6 +636,17 @@ SHARING_MAPT2(, size_type)::erase(
   return 1;
 }
 
+/// Erase all elements
+///
+/// Complexity:
+/// - Worst case: O(K * (H * S + M))
+/// - Best case: O(K * H)
+///
+/// \param ks: The keys of the element to erase
+/// \param key_exists: Hint to indicate whether the elements are known to exist
+///   (possible values `unknown` or `true`). Applies to all elements (i.e., have
+///   to use `unknown` if for at least one element it is not known whether it
+///   exists)
 SHARING_MAPT2(, size_type)::erase_all(
   const keyst &ks,
   const tvt &key_exists)
@@ -502,6 +661,18 @@ SHARING_MAPT2(, size_type)::erase_all(
   return cnt;
 }
 
+/// Insert element, return const reference
+///
+/// Complexity:
+/// - Worst case: O(H * S + M)
+/// - Best case: O(H)
+///
+/// \param k: The key of the element to insert
+/// \param m: The mapped value to insert
+/// \param key_exists: Hint to indicate whether the element is known to exist
+///   (possible values `false` or `unknown`)
+/// \return Pair of const reference to existing or newly inserted element, and
+///   boolean indicating if new element was inserted
 SHARING_MAPT2(, const_find_type)::insert(
   const key_type &k,
   const mapped_type &m,
@@ -525,13 +696,26 @@ SHARING_MAPT2(, const_find_type)::insert(
   return const_find_type(as_const(p)->get_value(), true);
 }
 
+// Insert element, return const reference
 SHARING_MAPT2(, const_find_type)::insert(
   const value_type &p,
   const tvt &key_exists)
 {
   return insert(p.first, p.second, key_exists);
 }
 
+/// Insert element, return non-const reference
+///
+/// Complexity:
+/// - Worst case: O(H * S + M)
+/// - Best case: O(H)
+///
+/// \param k: The key of the element to insert
+/// \param m: The mapped value to insert
+/// \param key_exists: Hint to indicate whether the element is known to exist
+///   (possible values false or unknown)
+/// \return Pair of reference to existing or newly inserted element, and boolean
+///   indicating if new element was inserted
 SHARING_MAPT2(, find_type)::place(
   const key_type &k,
   const mapped_type &m)
@@ -550,12 +734,24 @@ SHARING_MAPT2(, find_type)::place(
   return find_type(p->get_value(), true);
 }
 
+/// Insert element, return non-const reference
 SHARING_MAPT2(, find_type)::place(
   const value_type &p)
 {
   return place(p.first, p.second);
 }
 
+/// Find element
+///
+/// Complexity:
+/// - Worst case: O(H * S + M)
+/// - Best case: O(H)
+///
+/// \param k: The key of the element to search for
+/// \param key_exists: Hint to indicate whether the element is known to exist
+///   (possible values `unknown` or `true`)
+/// \return Pair of reference to found value (or dummy value if not found), and
+///   boolean indicating if element was found.
 SHARING_MAPT2(, find_type)::find(
   const key_type &k,
   const tvt &key_exists)
@@ -575,6 +771,17 @@ SHARING_MAPT2(, find_type)::find(
 
 }
 
+/// Find element
+///
+/// Complexity:
+/// - Worst case: O(H * log(S) + M)
+/// - Best case: O(H)
+///
+/// \param k: The key of the element to search
+/// \param key_exists: Hint to indicate whether the element is known to exist
+///   (possible values `unknown` or `true`)
+/// \return Pair of const reference to found value (or dummy value if not
+///   found), and boolean indicating if element was found.
 SHARING_MAPT2(, const_find_type)::find(const key_type &k) const
 {
   const node_type *p=get_leaf_node(k);
@@ -585,6 +792,17 @@ SHARING_MAPT2(, const_find_type)::find(const key_type &k) const
   return const_find_type(p->get_value(), true);
 }
 
+/// Get element at key
+///
+/// Complexity:
+/// - Worst case: O(H * S + M)
+/// - Best case: O(H)
+///
+/// \param k: The key of the element
+/// \param key_exists: Hint to indicate whether the element is known to exist
+///   (possible values `unknown` or `true`)
+/// \throw `std::out_of_range` if key not found
+/// \return The mapped value
 SHARING_MAPT2(, mapped_type &)::at(
   const key_type &k,
   const tvt &key_exists)
@@ -597,6 +815,15 @@ SHARING_MAPT2(, mapped_type &)::at(
   return r.first;
 }
 
+/// Get element at key
+///
+/// Complexity:
+/// - Worst case: O(H * log(S) + M)
+/// - Best case: O(H)
+///
+/// \param k: The key of the element
+/// \throw std::out_of_range if key not found
+/// \return The mapped value
 SHARING_MAPT2(const, mapped_type &)::at(const key_type &k) const
 {
   const_find_type r=find(k);
@@ -606,6 +833,14 @@ SHARING_MAPT2(const, mapped_type &)::at(const key_type &k) const
   return r.first;
 }
 
+/// Get element at key, insert new if non-existent
+///
+/// Complexity:
+/// - Worst case: O(H * S + M)
+/// - Best case: O(H)
+///
+/// \param k: The key of the element
+/// \return The mapped value
 SHARING_MAPT2(, mapped_type &)::operator[](const key_type &k)
 {
   return place(k, mapped_type()).first;