[Bf-blender-cvs] [4b6799394f1] functions: Some documentation for the C++ data structures in BLI
Jacques Lucke
noreply at git.blender.org
Mon May 13 18:38:46 CEST 2019
Commit: 4b6799394f107cb86dffdc20525713e8fadae67c
Author: Jacques Lucke
Date: Mon May 13 18:38:37 2019 +0200
Branches: functions
https://developer.blender.org/rB4b6799394f107cb86dffdc20525713e8fadae67c
Some documentation for the C++ data structures in BLI
===================================================================
M source/blender/blenlib/BLI_array_lookup.hpp
M source/blender/blenlib/BLI_array_ref.hpp
M source/blender/blenlib/BLI_composition.hpp
M source/blender/blenlib/BLI_lazy_init.hpp
M source/blender/blenlib/BLI_listbase_wrapper.hpp
M source/blender/blenlib/BLI_mempool.hpp
M source/blender/blenlib/BLI_multimap.hpp
M source/blender/blenlib/BLI_multipool.hpp
M source/blender/blenlib/BLI_object_pool.hpp
M source/blender/blenlib/BLI_optional.hpp
M source/blender/blenlib/BLI_range.hpp
M source/blender/blenlib/BLI_shared.hpp
M source/blender/blenlib/BLI_shared_immutable.hpp
M source/blender/blenlib/BLI_small_map.hpp
M source/blender/blenlib/BLI_small_set.hpp
M source/blender/blenlib/BLI_small_set_vector.hpp
M source/blender/blenlib/BLI_small_stack.hpp
M source/blender/blenlib/BLI_small_vector.hpp
M source/blender/blenlib/BLI_timeit.hpp
===================================================================
diff --git a/source/blender/blenlib/BLI_array_lookup.hpp b/source/blender/blenlib/BLI_array_lookup.hpp
index 53b234c3791..e40a5cec5b6 100644
--- a/source/blender/blenlib/BLI_array_lookup.hpp
+++ b/source/blender/blenlib/BLI_array_lookup.hpp
@@ -1,5 +1,13 @@
#pragma once
+/* The ArrayLookup allows sharing code between a
+ * map and set implementation without hacks
+ * (like using an empty value when a set is needed).
+ *
+ * It is search index for another array. Once build,
+ * it allows fast `contains` and `find` calls on that array.
+ */
+
#include "BLI_utildefines.h"
#include "BLI_small_vector.hpp"
#include "BLI_math_bits.h"
diff --git a/source/blender/blenlib/BLI_array_ref.hpp b/source/blender/blenlib/BLI_array_ref.hpp
index 8f28b880d25..35377f72821 100644
--- a/source/blender/blenlib/BLI_array_ref.hpp
+++ b/source/blender/blenlib/BLI_array_ref.hpp
@@ -1,5 +1,11 @@
#pragma once
+/* An ArrayRef references some memory buffer owned
+ * by someone else. If possible, functions should take
+ * an ArrayRef as input. This allows passing on different
+ * kinds of class types without doing unnecessary conversions.
+ */
+
#include "BLI_small_vector.hpp"
namespace BLI {
diff --git a/source/blender/blenlib/BLI_composition.hpp b/source/blender/blenlib/BLI_composition.hpp
index 68e67b764f9..a59b929b992 100644
--- a/source/blender/blenlib/BLI_composition.hpp
+++ b/source/blender/blenlib/BLI_composition.hpp
@@ -1,5 +1,13 @@
#pragma once
+/* This class allows to create a set of objects
+ * of different types. Only one instance of a type
+ * can exist in the set.
+ *
+ * In some cases, this approach should be preferred
+ * over multiple inheritance.
+ */
+
#include "BLI_small_map.hpp"
namespace BLI {
diff --git a/source/blender/blenlib/BLI_lazy_init.hpp b/source/blender/blenlib/BLI_lazy_init.hpp
index 34dc9e1e292..ae926b3cc4b 100644
--- a/source/blender/blenlib/BLI_lazy_init.hpp
+++ b/source/blender/blenlib/BLI_lazy_init.hpp
@@ -1,3 +1,5 @@
+#pragma once
+
/* These macros help to define functions that initialize
* some data the first time it is used.
* Currently the memory is freed after Blender prints information
diff --git a/source/blender/blenlib/BLI_listbase_wrapper.hpp b/source/blender/blenlib/BLI_listbase_wrapper.hpp
index 32696a896fc..2f99b15713d 100644
--- a/source/blender/blenlib/BLI_listbase_wrapper.hpp
+++ b/source/blender/blenlib/BLI_listbase_wrapper.hpp
@@ -1,5 +1,10 @@
#pragma once
+/* The purpose of this wrapper is just to make it more
+ * comfortable to iterate of ListBase instances, that
+ * are used in many places in Blender.
+ */
+
#include "BLI_listbase.h"
#include "DNA_listBase.h"
@@ -65,4 +70,4 @@ template<typename T, bool intrusive> class ListBaseWrapper {
}
};
-} /* namespace BLI */
\ No newline at end of file
+} /* namespace BLI */
diff --git a/source/blender/blenlib/BLI_mempool.hpp b/source/blender/blenlib/BLI_mempool.hpp
index 24be1672526..5fa8d92b8aa 100644
--- a/source/blender/blenlib/BLI_mempool.hpp
+++ b/source/blender/blenlib/BLI_mempool.hpp
@@ -1,5 +1,24 @@
#pragma once
+/* Use this memory allocator when:
+ * - all allocations have the same size
+ * - only a single thread allocates from this allocator
+ * - all allocated memory should be returned to the system at once
+ *
+ * The allocator keeps track of all unused allocated chunks
+ * in a stack. Allocation pops the top chunk, while deallocation
+ * pushes the chunk back to the stack.
+ *
+ * Memory is never returned to the system in this allocator.
+ * If the task requires that to happen, another allocator should be
+ * used, so that this allocator can stay simple.
+ *
+ * allocate: O(1) amortized
+ * deallocate: O(1)
+ * internal allocations: O(lg n) where n is the number of allocations
+ *
+ */
+
#include "BLI_small_stack.hpp"
#include "BLI_small_set.hpp"
diff --git a/source/blender/blenlib/BLI_multimap.hpp b/source/blender/blenlib/BLI_multimap.hpp
index 3b4fe86b33d..e6b2064d012 100644
--- a/source/blender/blenlib/BLI_multimap.hpp
+++ b/source/blender/blenlib/BLI_multimap.hpp
@@ -1,5 +1,14 @@
#pragma once
+/* A map that allows storing multiple values per key.
+ *
+ * Values per key are stored in an array without being
+ * able to efficiently check if a specific value exists
+ * for a key. A linear search through all values for
+ * a key has to be performed. When the number of values
+ * per key is expected to be small, this is still fast.
+ */
+
#include "BLI_small_map.hpp"
#include "BLI_multipool.hpp"
#include "BLI_array_ref.hpp"
diff --git a/source/blender/blenlib/BLI_multipool.hpp b/source/blender/blenlib/BLI_multipool.hpp
index 36f6cfb3817..d11fc0bddbf 100644
--- a/source/blender/blenlib/BLI_multipool.hpp
+++ b/source/blender/blenlib/BLI_multipool.hpp
@@ -1,5 +1,14 @@
#pragma once
+/* This is similar to a normal MemPool, but supports
+ * allocating different sizes. It should only be used
+ * when the amount of different sizes is expected to
+ * be very small.
+ *
+ * It is not thread-safe, so only a single thread should
+ * allocate memory using this pool at the same time.
+ */
+
#include "BLI_small_map.hpp"
#include "BLI_mempool.hpp"
diff --git a/source/blender/blenlib/BLI_object_pool.hpp b/source/blender/blenlib/BLI_object_pool.hpp
index 2c11543ad9b..fe50bb77fec 100644
--- a/source/blender/blenlib/BLI_object_pool.hpp
+++ b/source/blender/blenlib/BLI_object_pool.hpp
@@ -1,5 +1,18 @@
#pragma once
+/* This structure allows reusing the same object.
+ *
+ * Aquire:
+ * Get an object that might have been used before.
+ * If no unused object exists currently, a new one
+ * will be allocated and constructed.
+ *
+ * Release:
+ * Give back the object instance, so that someone
+ * else can use it later. The destructor is not
+ * necessarily called.
+ */
+
#include <mutex>
#include "BLI_small_stack.hpp"
diff --git a/source/blender/blenlib/BLI_optional.hpp b/source/blender/blenlib/BLI_optional.hpp
index 17729aaa6c7..c1ee980577e 100644
--- a/source/blender/blenlib/BLI_optional.hpp
+++ b/source/blender/blenlib/BLI_optional.hpp
@@ -1,5 +1,9 @@
#pragma once
+/* Simple version of std::optional, which is only
+ * available since C++17.
+ */
+
#include "BLI_utildefines.h"
#include <algorithm>
diff --git a/source/blender/blenlib/BLI_range.hpp b/source/blender/blenlib/BLI_range.hpp
index 0253aededc0..0b383d14b16 100644
--- a/source/blender/blenlib/BLI_range.hpp
+++ b/source/blender/blenlib/BLI_range.hpp
@@ -1,5 +1,9 @@
#pragma once
+/* Allows passing iterators over ranges of integers without
+ * actually allocating an array.
+ */
+
#include "BLI_utildefines.h"
namespace BLI {
diff --git a/source/blender/blenlib/BLI_shared.hpp b/source/blender/blenlib/BLI_shared.hpp
index 5ec672ccbb4..cce6376d2b3 100644
--- a/source/blender/blenlib/BLI_shared.hpp
+++ b/source/blender/blenlib/BLI_shared.hpp
@@ -1,5 +1,21 @@
#pragma once
+/* Objects with shared ownership require a reference
+ * counter, so that it can be freed when it is not
+ * referenced anymore.
+ *
+ * Classes can subclass RefCountedBase to be extended
+ * with an intrusive reference count (the counter is
+ * stored directly in the object). This is necessary,
+ * because the object might have to be used by different
+ * languages (C, C++, Python).
+ *
+ * To avoid error-prone manual reference counting,
+ * there is an AutoRefCount class that works similar
+ * to std::shared, but deals with objects of type
+ * RefCountedBase.
+ */
+
#include <atomic>
#include <utility>
#include "BLI_utildefines.h"
diff --git a/source/blender/blenlib/BLI_shared_immutable.hpp b/source/blender/blenlib/BLI_shared_immutable.hpp
index fefc8637192..2d1e787d4a9 100644
--- a/source/blender/blenlib/BLI_shared_immutable.hpp
+++ b/source/blender/blenlib/BLI_shared_immutable.hpp
@@ -1,5 +1,23 @@
#pragma once
+/* A shared immutable type has a reference count and
+ * is freed automatically, when it is not used anymore.
+ * Furthermore, it must not be modified, when it is
+ * referenced in two or more places.
+ *
+ * When the reference is one, it can be mutated.
+ *
+ * This approach reduces the amount of defensive
+ * copies of data (data that is copied to make sure
+ * that nobody does not change it anymore). Instead,
+ * to one just have to increase the user count.
+ *
+ * A copy has to be made, when the user count is >= 2.
+ *
+ * Reference counting can be automated with the
+ * AutoRefCount class.
+ */
+
#include "BLI_shared.hpp"
namespace BLI {
@@ -50,4 +68,4 @@ class SharedImmutable : protected RefCountedBase {
}
};
-} /* namespace BLI */
\ No newline at end of file
+} /* namespace BLI */
diff --git a/source/blender/blenlib/BLI_small_map.hpp b/source/blender/blenlib/BLI_small_map.hpp
index 7ee35cfad8e..fa802cadde7 100644
--- a/source/blender/blenlib/BLI_small_map.hpp
+++ b/source/blender/blenlib/BLI_small_map.hpp
@@ -1,5 +1,10 @@
#pragma once
+/* An unordered map implementation with small object optimization.
+ * Similar to SmallSet, this builds on top of SmallVector
+ * and ArrayLookup to reduce what this code has to deal with.
+ */
+
#include "BLI_small_vector.hpp"
#include "BLI_array_lookup.hpp"
#include "BLI_array_ref.hpp"
diff --git a/source/blender/blenlib/BLI_small_set.hpp b/source/blender/blenlib/BLI_small_set.hpp
index ea327f0758c..41308735e5d 100644
--- a/source/blender/blenlib/BLI_small_set.hpp
+++ b/source/blender/blenlib/BLI_small_set.hpp
@@ -1,5 +1,11 @@
#pragma once
+/* A unordered set implementation that supports small object optimization.
+ * It builds on top of SmallVector and ArrayLookup, so that
+ * it does not have to deal with memory management and the
+ * details of the hashing and probing algorithm.
+ */
+
#include "BLI_small_vector.hpp"
#include "BLI_array_lookup.hpp"
diff --git a/source/blender/blenlib/BLI_small_set_vector.hpp b/source/blender/blenlib/BLI_small_set_vector.hpp
index 35779b2e1cf..4027735fca7 100644
--- a/source/blender/blenlib/BLI_small_set_vector.hpp
+++ b/source/blender/blenlib/BLI_small_set_vector.hpp
@@ -1,5 +1,10 @@
#pragma once
+/* A set with small object optimization that keeps track
+ * of insertion order. Internally, it is the same as SmallSet
+ * but that could potentially change in t
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list