diff options
author | Jacques Lucke <jacques@blender.org> | 2021-04-01 16:55:08 +0300 |
---|---|---|
committer | Jacques Lucke <jacques@blender.org> | 2021-04-01 16:55:23 +0300 |
commit | b5c2c3aba886f521a0cade5b8450683c20843d3a (patch) | |
tree | 46878da186ccb49b2bcc3e1de816476aea5cf750 /source/blender/blenlib | |
parent | f674976edd884d7a9a409042708f2b1169fd4e98 (diff) |
BLI: rename resource collector to resource scope
Differential Revision: https://developer.blender.org/D10857
Diffstat (limited to 'source/blender/blenlib')
-rw-r--r-- | source/blender/blenlib/BLI_resource_scope.hh (renamed from source/blender/blenlib/BLI_resource_collector.hh) | 40 | ||||
-rw-r--r-- | source/blender/blenlib/CMakeLists.txt | 2 |
2 files changed, 27 insertions, 15 deletions
diff --git a/source/blender/blenlib/BLI_resource_collector.hh b/source/blender/blenlib/BLI_resource_scope.hh index 70804ceb1f1..f606dc0c0a1 100644 --- a/source/blender/blenlib/BLI_resource_collector.hh +++ b/source/blender/blenlib/BLI_resource_scope.hh @@ -19,12 +19,24 @@ /** \file * \ingroup bli * - * A ResourceCollector holds an arbitrary set of resources, that will be destructed and/or freed - * when the ResourceCollector is destructed. This is useful when some object has to take ownership - * of other objects, but it does not know the type of those other objects. + * A `ResourceScope` takes ownership of arbitrary data/resources. Those resources will be + * destructed and/or freed when the `ResourceScope` is destructed. Destruction happens in reverse + * order. That allows resources do depend on other resources that have been added before. * - * Resources owned by the ResourceCollector will be freed in reverse order. That allows resources - * that are added later to depend on resources that have been added before. + * A `ResourceScope` can also be thought of as a dynamic/runtime version of normal scopes in C++ + * that are surrounded by braces. + * + * The main purpose of a `ResourceScope` is to allow functions to inject data into the scope of the + * caller. Traditionally, that can only be done by returning a value that owns everything it needs. + * This is fine until one has to deal with optional ownership. There are many ways to have a type + * optionally own something else, all of which are fairly annoying. A `ResourceScope` can be used + * to avoid having to deal with optional ownership. If some value would be owned, it can just be + * added to the resource scope, otherwise not. + * + * When a function takes a `ResourceScope` as parameter, it usually means that its return value + * will live at least as long as the passed in resources scope. However, it might also live longer. + * That can happen when the function returns a reference to statically allocated data or + * dynamically allocated data depending on some condition. */ #include "BLI_linear_allocator.hh" @@ -33,7 +45,7 @@ namespace blender { -class ResourceCollector : NonCopyable, NonMovable { +class ResourceScope : NonCopyable, NonMovable { private: struct ResourceData { void *data; @@ -45,9 +57,9 @@ class ResourceCollector : NonCopyable, NonMovable { Vector<ResourceData> m_resources; public: - ResourceCollector() = default; + ResourceScope() = default; - ~ResourceCollector() + ~ResourceScope() { /* Free in reversed order. */ for (int64_t i = m_resources.size(); i--;) { @@ -57,7 +69,7 @@ class ResourceCollector : NonCopyable, NonMovable { } /** - * Pass ownership of the resource to the ResourceCollector. It will be destructed and freed when + * Pass ownership of the resource to the ResourceScope. It will be destructed and freed when * the collector is destructed. */ template<typename T> void add(std::unique_ptr<T> resource, const char *name) @@ -73,7 +85,7 @@ class ResourceCollector : NonCopyable, NonMovable { } /** - * Pass ownership of the resource to the ResourceCollector. It will be destructed when the + * Pass ownership of the resource to the ResourceScope. It will be destructed when the * collector is destructed. */ template<typename T> void add(destruct_ptr<T> resource, const char *name) @@ -95,7 +107,7 @@ class ResourceCollector : NonCopyable, NonMovable { } /** - * Pass ownership of some resource to the ResourceCollector. The given free function will be + * Pass ownership of some resource to the ResourceScope. The given free function will be * called when the collector is destructed. */ void add(void *userdata, void (*free)(void *), const char *name) @@ -108,7 +120,7 @@ class ResourceCollector : NonCopyable, NonMovable { } /** - * Construct an object with the same value in the ResourceCollector and return a reference to the + * Construct an object with the same value in the ResourceScope and return a reference to the * new value. */ template<typename T> T &add_value(T &&value, const char *name) @@ -126,7 +138,7 @@ class ResourceCollector : NonCopyable, NonMovable { } /** - * Utility method to construct an instance of type T that will be owned by the ResourceCollector. + * Utility method to construct an instance of type T that will be owned by the ResourceScope. */ template<typename T, typename... Args> T &construct(const char *name, Args &&... args) { @@ -137,7 +149,7 @@ class ResourceCollector : NonCopyable, NonMovable { } /** - * Print the names of all the resources that are owned by this ResourceCollector. This can be + * Print the names of all the resources that are owned by this ResourceScope. This can be * useful for debugging. */ void print(StringRef name) const diff --git a/source/blender/blenlib/CMakeLists.txt b/source/blender/blenlib/CMakeLists.txt index d7a27cc4531..e66049c9bd6 100644 --- a/source/blender/blenlib/CMakeLists.txt +++ b/source/blender/blenlib/CMakeLists.txt @@ -258,7 +258,7 @@ set(SRC BLI_rand.h BLI_rand.hh BLI_rect.h - BLI_resource_collector.hh + BLI_resource_scope.hh BLI_scanfill.h BLI_session_uuid.h BLI_set.hh |