hashmap: minor docs updates

Author: lukaszstolarczuk

examples/concurrent_hash_map/concurrent_hash_map.cpp

@@ -15,16 +15,16 @@
 
 using namespace pmem::obj;
 
-/* In this example we will be using concurrent_hash_map with p<int> type for
- * both keys and values */
+/* In this example we use concurrent_hash_map with p<int> type as
+ * both keys and values. */
 using hashmap_type = concurrent_hash_map<p<int>, p<int>>;
 
 const int THREADS_NUM = 30;
 const bool remove_hashmap = false;
 
 /* This is basic example and we only need to use concurrent_hash_map. Hence we
- * will correlate memory pool root object with single instance of persistent
- * pointer to hasmap_type */
+ * correlate memory pool root object with a single instance of persistent
+ * pointer to hashmap_type. */
 struct root {
 	persistent_ptr<hashmap_type> pptr;
 };
@@ -69,7 +69,7 @@ main(int argc, char *argv[])
 
 			r->runtime_initialize();
 
-			/* defragment the whole pool at the beginning */
+			/* Defragment the whole pool at the beginning. */
 			try {
 				r->defragment();
 			} catch (const pmem::defrag_error &e) {
@@ -84,8 +84,8 @@ main(int argc, char *argv[])
 		std::vector<std::thread> threads;
 		threads.reserve(static_cast<size_t>(THREADS_NUM));
 
-		/* Insert THREADS_NUM / 3 key-value pairs to the hashmap. This
-		 * operation is thread-safe. */
+		/* Start THREADS_NUM/3 threads to insert key-value pairs
+		 * to the hashmap. This operation is thread-safe. */
 		for (int i = 0; i < THREADS_NUM / 3; ++i) {
 			threads.emplace_back([&]() {
 				for (int i = 0; i < 10 * THREADS_NUM; ++i) {
@@ -95,8 +95,8 @@ main(int argc, char *argv[])
 			});
 		}
 
-		/* Erase THREADS_NUM /3 key-value pairs from the hashmap. This
-		 * operation is thread-safe. */
+		/* Start THREADS_NUM/3 threads to erase key-value pairs
+		 * from the hashmap. This operation is thread-safe. */
 		for (int i = 0; i < THREADS_NUM / 3; ++i) {
 			threads.emplace_back([&]() {
 				for (int i = 0; i < 10 * THREADS_NUM; ++i) {
@@ -105,8 +105,9 @@ main(int argc, char *argv[])
 			});
 		}
 
-		/* Check if given key is in the hashmap. For the time of an
-		 * accessor life, the read-write lock is taken on the item. */
+		/* Start THREADS_NUM/3 threads to check if given key is
+		 * in the hashmap. For the time of an accessor life,
+		 * the read-write lock is taken on the item. */
 		for (int i = 0; i < THREADS_NUM / 3; ++i) {
 			threads.emplace_back([&]() {
 				for (int i = 0; i < 10 * THREADS_NUM; ++i) {
@@ -127,7 +128,7 @@ main(int argc, char *argv[])
 			t.join();
 		}
 		try {
-			/* defragment the whole pool at the end */
+			/* Defragment the whole pool at the end. */
 			map.defragment();
 		} catch (const pmem::defrag_error &e) {
 			std::cerr << "Defragmentation exception: " << e.what()
@@ -148,7 +149,7 @@ main(int argc, char *argv[])
 		}
 		/* Erase remaining itemes in map. This function is not
 		 * thread-safe, hence the function is being called only after
-		 * thread execution has completed. */
+		 * execution of all threads has completed. */
 		try {
 			map.clear();
 		} catch (const pmem::transaction_out_of_memory &e) {
@@ -162,14 +163,14 @@ main(int argc, char *argv[])
 		}
 
 		/* If hash map is to be removed, free_data() method should be
-		 * called first. Otherwise, if deallocating internal hash map
-		 * metadata in a destructor fail program might terminate. */
+		 * called first. Otherwise, program might terminate, if
+		 * deallocating internal hash map metadata in a destructor
+		 * fails. */
 		if (remove_hashmap) {
 			map.free_data();
 
 			/* map.clear() // WRONG
-			 * After free_data() concurrent hash map cannot be used
-			 * anymore! */
+			 * After free_data() hash map cannot be used anymore! */
 
 			transaction::run(pop, [&] {
 				delete_persistent<hashmap_type>(r);

include/libpmemobj++/container/concurrent_hash_map.hpp

@@ -333,7 +333,7 @@ struct hash_map_node {
 
 /**
  * The class provides the way to access certain properties of segments
- * used by hash map
+ * used by hash map.
  */
 template <typename Bucket>
 class segment_traits {
@@ -1319,7 +1319,7 @@ class hash_map_base {
 
 	/**
 	 * Swap hash_map_base
-	 * @throws std::transaction_error in case of PMDK transaction failed
+	 * @throw std::transaction_error in case of PMDK transaction failed
 	 */
 	void
 	internal_swap(hash_map_base<Key, T, mutex_t, scoped_t> &table)
@@ -1575,7 +1575,7 @@ operator!=(const hash_map_iterator<Container, M> &i,
  * Persistent memory aware implementation of Intel TBB concurrent_hash_map.
  * The implementation is based on a concurrent hash table algorithm
  * (https://arxiv.org/ftp/arxiv/papers/1509/1509.02235.pdf) where elements
- * assigned to buckets based on a hash code are calculated from a key.
+ * are assigned to buckets based on a hash code calculated from a key.
  * In addition to concurrent find, insert, and erase operations, the algorithm
  * employs resizing and on-demand per-bucket rehashing. The hash table consists
  * of an array of buckets, and each bucket consists of a list of nodes and a
@@ -2273,7 +2273,7 @@ class concurrent_hash_map
 	 * Clear hash map content
 	 * Not thread safe.
 	 *
-	 * @throws pmem::transaction_error in case of PMDK transaction failure
+	 * @throw pmem::transaction_error in case of PMDK transaction failure
 	 */
 	void clear();
 
@@ -2795,7 +2795,7 @@ class concurrent_hash_map
 	 * Remove element with corresponding key
 	 *
 	 * @return true if element was deleted by this call
-	 * @throws pmem::transaction_free_error in case of PMDK unable to free
+	 * @throw pmem::transaction_free_error in case of PMDK unable to free
 	 * the memory
 	 * @throw pmem::transaction_scope_error if called inside transaction
 	 */
@@ -2884,7 +2884,7 @@ class concurrent_hash_map
 	 * this function without constructing an instance of Key
 	 *
 	 * @return true if element was deleted by this call
-	 * @throws pmem::transaction_free_error in case of PMDK unable to free
+	 * @throw pmem::transaction_free_error in case of PMDK unable to free
 	 * the memory
 	 * @throw pmem::transaction_scope_error if called inside transaction
 	 */