Merge pull request #1215 from karczex/doc_tweaks

Documentation tweaks

Author: lukaszstolarczuk

examples/map_cli/ctree_map_persistent.hpp

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: BSD-3-Clause
-/* Copyright 2016-2018, Intel Corporation */
+/* Copyright 2016-2021, Intel Corporation */
 
 #ifndef LIBPMEMOBJ_CPP_EXAMPLES_CTREE_MAP_PERSISTENT_HPP
 #define LIBPMEMOBJ_CPP_EXAMPLES_CTREE_MAP_PERSISTENT_HPP
@@ -19,8 +19,6 @@
 
 #define BIT_IS_SET(n, i) (!!((n) & (1ULL << (i))))
 
-namespace nvobj = pmem::obj;
-
 namespace examples
 {
 
@@ -38,7 +36,7 @@ class ctree_map_p {
 	typedef K key_type;
 
 	/** Convenience typedef for the value type. */
-	typedef nvobj::persistent_ptr<T> value_type;
+	typedef pmem::obj::persistent_ptr<T> value_type;
 
 	/** Convenience typedef for the callback function. */
 	typedef std::function<int(key_type, value_type, void *)> callback;
@@ -48,10 +46,10 @@ class ctree_map_p {
 	 */
 	ctree_map_p()
 	{
-		auto pop = nvobj::pool_by_vptr(this);
+		auto pop = pmem::obj::pool_by_vptr(this);
 
-		nvobj::transaction::run(pop, [&] {
-			this->root = nvobj::make_persistent<entry>();
+		pmem::obj::transaction::run(pop, [&] {
+			this->root = pmem::obj::make_persistent<entry>();
 		});
 	}
 
@@ -79,10 +77,11 @@ class ctree_map_p {
 		}
 
 		entry e(key, value);
-		auto pop = nvobj::pool_by_vptr(this);
-		nvobj::transaction::run(pop, [&] {
+		auto pop = pmem::obj::pool_by_vptr(this);
+		pmem::obj::transaction::run(pop, [&] {
 			if (dest_entry->key == 0 || dest_entry->key == key) {
-				nvobj::delete_persistent<T>(dest_entry->value);
+				pmem::obj::delete_persistent<T>(
+					dest_entry->value);
 				*dest_entry = e;
 			} else {
 				insert_leaf(
@@ -109,9 +108,10 @@ class ctree_map_p {
 	int
 	insert_new(key_type key, const Args &... args)
 	{
-		auto pop = nvobj::pool_by_vptr(this);
-		nvobj::transaction::run(pop, [&] {
-			return insert(key, nvobj::make_persistent<T>(args...));
+		auto pop = pmem::obj::pool_by_vptr(this);
+		pmem::obj::transaction::run(pop, [&] {
+			return insert(key,
+				      pmem::obj::make_persistent<T>(args...));
 		});
 
 		return -1;
@@ -129,16 +129,16 @@ class ctree_map_p {
 	value_type
 	remove(key_type key)
 	{
-		nvobj::persistent_ptr<entry> parent = nullptr;
+		pmem::obj::persistent_ptr<entry> parent = nullptr;
 		auto leaf = get_leaf(key, &parent);
 
 		if (leaf == nullptr)
 			return nullptr;
 
 		auto ret = leaf->value;
 
-		auto pop = nvobj::pool_by_vptr(this);
-		nvobj::transaction::run(pop, [&] {
+		auto pop = pmem::obj::pool_by_vptr(this);
+		pmem::obj::transaction::run(pop, [&] {
 			if (parent == nullptr) {
 				leaf->key = 0;
 				leaf->value = nullptr;
@@ -149,9 +149,11 @@ class ctree_map_p {
 							   ->key == leaf->key]);
 
 				/* cleanup entries and the unnecessary node */
-				nvobj::delete_persistent<entry>(n->entries[0]);
-				nvobj::delete_persistent<entry>(n->entries[1]);
-				nvobj::delete_persistent<node>(n);
+				pmem::obj::delete_persistent<entry>(
+					n->entries[0]);
+				pmem::obj::delete_persistent<entry>(
+					n->entries[1]);
+				pmem::obj::delete_persistent<node>(n);
 			}
 		});
 
@@ -168,9 +170,10 @@ class ctree_map_p {
 	int
 	remove_free(key_type key)
 	{
-		auto pop = nvobj::pool_by_vptr(this);
-		nvobj::transaction::run(
-			pop, [&] { nvobj::delete_persistent<T>(remove(key)); });
+		auto pop = pmem::obj::pool_by_vptr(this);
+		pmem::obj::transaction::run(pop, [&] {
+			pmem::obj::delete_persistent<T>(remove(key));
+		});
 		return 0;
 	}
 
@@ -180,16 +183,16 @@ class ctree_map_p {
 	int
 	clear()
 	{
-		auto pop = nvobj::pool_by_vptr(this);
-		nvobj::transaction::run(pop, [&] {
+		auto pop = pmem::obj::pool_by_vptr(this);
+		pmem::obj::transaction::run(pop, [&] {
 			if (this->root->inode) {
 				this->root->inode->clear();
-				nvobj::delete_persistent<node>(
+				pmem::obj::delete_persistent<node>(
 					this->root->inode);
 				this->root->inode = nullptr;
 			}
 
-			nvobj::delete_persistent<T>(this->root->value);
+			pmem::obj::delete_persistent<T>(this->root->value);
 			this->root->value = nullptr;
 			this->root->key = 0;
 		});
@@ -286,19 +289,19 @@ class ctree_map_p {
 		{
 		}
 
-		nvobj::p<key_type> key;
-		nvobj::persistent_ptr<node> inode;
+		pmem::obj::p<key_type> key;
+		pmem::obj::persistent_ptr<node> inode;
 		value_type value;
 
 		void
 		clear()
 		{
 			if (inode) {
 				inode->clear();
-				nvobj::delete_persistent<node>(inode);
+				pmem::obj::delete_persistent<node>(inode);
 				inode = nullptr;
 			}
-			nvobj::delete_persistent<T>(value);
+			pmem::obj::delete_persistent<T>(value);
 			value = nullptr;
 		}
 	};
@@ -313,20 +316,20 @@ class ctree_map_p {
 			entries[1] = nullptr;
 		}
 
-		nvobj::p<int> diff; /* most significant differing bit */
-		nvobj::persistent_ptr<entry> entries[2];
+		pmem::obj::p<int> diff; /* most significant differing bit */
+		pmem::obj::persistent_ptr<entry> entries[2];
 
 		void
 		clear()
 		{
 			if (entries[0]) {
 				entries[0]->clear();
-				nvobj::delete_persistent<entry>(entries[0]);
+				pmem::obj::delete_persistent<entry>(entries[0]);
 				entries[0] = nullptr;
 			}
 			if (entries[1]) {
 				entries[1]->clear();
-				nvobj::delete_persistent<entry>(entries[1]);
+				pmem::obj::delete_persistent<entry>(entries[1]);
 				entries[1] = nullptr;
 			}
 		}
@@ -347,11 +350,11 @@ class ctree_map_p {
 	void
 	insert_leaf(const entry *e, int diff)
 	{
-		auto new_node = nvobj::make_persistent<node>();
+		auto new_node = pmem::obj::make_persistent<node>();
 		new_node->diff = diff;
 
 		int d = BIT_IS_SET(e->key, new_node->diff);
-		new_node->entries[d] = nvobj::make_persistent<entry>(*e);
+		new_node->entries[d] = pmem::obj::make_persistent<entry>(*e);
 
 		auto dest_entry = root;
 		while (dest_entry->inode != nullptr) {
@@ -363,7 +366,7 @@ class ctree_map_p {
 		}
 
 		new_node->entries[!d] =
-			nvobj::make_persistent<entry>(*dest_entry);
+			pmem::obj::make_persistent<entry>(*dest_entry);
 		dest_entry->key = 0;
 		dest_entry->inode = new_node;
 		dest_entry->value = nullptr;
@@ -372,11 +375,11 @@ class ctree_map_p {
 	/*
 	 * Fetch leaf from the tree.
 	 */
-	nvobj::persistent_ptr<entry>
-	get_leaf(key_type key, nvobj::persistent_ptr<entry> *parent)
+	pmem::obj::persistent_ptr<entry>
+	get_leaf(key_type key, pmem::obj::persistent_ptr<entry> *parent)
 	{
 		auto n = root;
-		nvobj::persistent_ptr<entry> p = nullptr;
+		pmem::obj::persistent_ptr<entry> p = nullptr;
 
 		while (n->inode != nullptr) {
 			p = n;
@@ -397,7 +400,7 @@ class ctree_map_p {
 	 * Recursive foreach on nodes.
 	 */
 	int
-	foreach_node(const nvobj::persistent_ptr<entry> e, callback clb,
+	foreach_node(const pmem::obj::persistent_ptr<entry> e, callback clb,
 		     void *arg)
 	{
 		int ret = 0;
@@ -414,7 +417,7 @@ class ctree_map_p {
 	}
 
 	/* Tree root */
-	nvobj::persistent_ptr<entry> root;
+	pmem::obj::persistent_ptr<entry> root;
 };
 
 } /* namespace examples */

examples/mutex/mutex.cpp

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: BSD-3-Clause
-/* Copyright 2016-2020, Intel Corporation */
+/* Copyright 2016-2021, Intel Corporation */
 
 /*
  * mutex.cpp -- C++ documentation snippets.
@@ -12,25 +12,23 @@
 #include <libpmemobj++/pool.hpp>
 #include <mutex>
 
-namespace nvobj = pmem::obj;
-
 void
 unique_guard_example()
 {
 	/* pool root structure */
 	struct root {
-		nvobj::mutex pmutex;
+		pmem::obj::mutex pmutex;
 	};
 
 	/* create a pmemobj pool */
-	auto pop = nvobj::pool<root>::create("poolfile", "layout",
-					     PMEMOBJ_MIN_POOL);
+	auto pop = pmem::obj::pool<root>::create("poolfile", "layout",
+						 PMEMOBJ_MIN_POOL);
 	auto proot = pop.root();
 
 	/* typical usage schemes */
-	std::lock_guard<nvobj::mutex> guard(proot->pmutex);
+	std::lock_guard<pmem::obj::mutex> guard(proot->pmutex);
 
-	std::unique_lock<nvobj::mutex> other_guard(proot->pmutex);
+	std::unique_lock<pmem::obj::mutex> other_guard(proot->pmutex);
 }
 //! [unique_guard_example]
 
@@ -40,25 +38,23 @@ unique_guard_example()
 #include <libpmemobj++/shared_mutex.hpp>
 #include <mutex>
 
-namespace nvobj = pmem::obj;
-
 void
 shared_mutex_example()
 {
 	/* pool root structure */
 	struct root {
-		nvobj::shared_mutex pmutex;
+		pmem::obj::shared_mutex pmutex;
 	};
 
 	/* create a pmemobj pool */
-	auto pop = nvobj::pool<root>::create("poolfile", "layout",
-					     PMEMOBJ_MIN_POOL);
+	auto pop = pmem::obj::pool<root>::create("poolfile", "layout",
+						 PMEMOBJ_MIN_POOL);
 	auto proot = pop.root();
 
 	/* typical usage schemes */
 	proot->pmutex.lock_shared();
 
-	std::unique_lock<nvobj::shared_mutex> guard(proot->pmutex);
+	std::unique_lock<pmem::obj::shared_mutex> guard(proot->pmutex);
 }
 //! [shared_mutex_example]
 
@@ -68,19 +64,17 @@ shared_mutex_example()
 #include <libpmemobj++/pool.hpp>
 #include <libpmemobj++/timed_mutex.hpp>
 
-namespace nvobj = pmem::obj;
-
 void
 timed_mutex_example()
 {
 	/* pool root structure */
 	struct root {
-		nvobj::timed_mutex pmutex;
+		pmem::obj::timed_mutex pmutex;
 	};
 
 	/* create a pmemobj pool */
-	auto pop = nvobj::pool<root>::create("poolfile", "layout",
-					     PMEMOBJ_MIN_POOL);
+	auto pop = pmem::obj::pool<root>::create("poolfile", "layout",
+						 PMEMOBJ_MIN_POOL);
 	auto proot = pop.root();
 
 	const auto timeout = std::chrono::milliseconds(100);
@@ -101,27 +95,25 @@ timed_mutex_example()
 #include <mutex>
 #include <thread>
 
-namespace nvobj = pmem::obj;
-
 void
 cond_var_example()
 {
 	/* pool root structure */
 	struct root {
-		nvobj::mutex pmutex;
-		nvobj::condition_variable cond;
+		pmem::obj::mutex pmutex;
+		pmem::obj::condition_variable cond;
 		int counter;
 	};
 
 	/* create a pmemobj pool */
-	auto pop = nvobj::pool<root>::create("poolfile", "layout",
-					     PMEMOBJ_MIN_POOL);
+	auto pop = pmem::obj::pool<root>::create("poolfile", "layout",
+						 PMEMOBJ_MIN_POOL);
 
 	auto proot = pop.root();
 
 	/* run worker to bump up the counter */
 	std::thread worker([&] {
-		std::unique_lock<nvobj::mutex> lock(proot->pmutex);
+		std::unique_lock<pmem::obj::mutex> lock(proot->pmutex);
 		while (proot->counter < 1000)
 			++proot->counter;
 		/* unlock before notifying to avoid blocking on waiting thread
@@ -131,7 +123,7 @@ cond_var_example()
 		proot->cond.notify_one();
 	});
 
-	std::unique_lock<nvobj::mutex> lock(proot->pmutex);
+	std::unique_lock<pmem::obj::mutex> lock(proot->pmutex);
 	/* wait on condition variable */
 	proot->cond.wait(lock, [&] { return proot->counter >= 1000; });
 

include/libpmemobj++/condition_variable.hpp

@@ -26,8 +26,9 @@ namespace obj
  * Persistent memory resident condition variable.
  *
  * This class is an implementation of a PMEM-resident condition
- * variable which mimics in behavior the C++11 std::condition_variable. The
- * typical usage example would be:
+ * variable which mimics in behavior the C++11
+ * [std::condition_variable](https://en.cppreference.com/w/cpp/thread/condition_variable).
+ * The typical usage example would be:
  * @snippet mutex/mutex.cpp cond_var_example
  * @ingroup synchronization
  */