pooled_list.h 7.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209
  1. /**************************************************************************/
  2. /* pooled_list.h */
  3. /**************************************************************************/
  4. /* This file is part of: */
  5. /* GODOT ENGINE */
  6. /* https://godotengine.org */
  7. /**************************************************************************/
  8. /* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
  9. /* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. */
  10. /* */
  11. /* Permission is hereby granted, free of charge, to any person obtaining */
  12. /* a copy of this software and associated documentation files (the */
  13. /* "Software"), to deal in the Software without restriction, including */
  14. /* without limitation the rights to use, copy, modify, merge, publish, */
  15. /* distribute, sublicense, and/or sell copies of the Software, and to */
  16. /* permit persons to whom the Software is furnished to do so, subject to */
  17. /* the following conditions: */
  18. /* */
  19. /* The above copyright notice and this permission notice shall be */
  20. /* included in all copies or substantial portions of the Software. */
  21. /* */
  22. /* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */
  23. /* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */
  24. /* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
  25. /* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */
  26. /* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */
  27. /* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */
  28. /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */
  29. /**************************************************************************/
  30. #pragma once
  31. // Simple template to provide a pool with O(1) allocate and free.
  32. // The freelist could alternatively be a linked list placed within the unused elements
  33. // to use less memory, however a separate freelist is probably more cache friendly.
  34. // NOTE : Take great care when using this with non POD types. The construction and destruction
  35. // is done in the LocalVector, NOT as part of the pool. So requesting a new item does not guarantee
  36. // a constructor is run, and free does not guarantee a destructor.
  37. // You should generally handle clearing
  38. // an item explicitly after a request, as it may contain 'leftovers'.
  39. // This is by design for fastest use in the BVH. If you want a more general pool
  40. // that does call constructors / destructors on request / free, this should probably be
  41. // a separate template.
  42. // The zero_on_first_request feature is optional and is useful for e.g. pools of handles,
  43. // which may use a ref count which we want to be initialized to zero the first time a handle is created,
  44. // but left alone on subsequent allocations (as will typically be incremented).
  45. // Note that there is no function to compact the pool - this would
  46. // invalidate any existing pool IDs held externally.
  47. // Compaction can be done but would rely on a more complex method
  48. // of preferentially giving out lower IDs in the freelist first.
  49. #include "core/local_vector.h"
  50. template <class T, class U = uint32_t, bool force_trivial = false, bool zero_on_first_request = false>
  51. class PooledList {
  52. LocalVector<T, U, force_trivial> list;
  53. LocalVector<U, U, true> freelist;
  54. // not all list members are necessarily used
  55. U _used_size;
  56. public:
  57. PooledList() {
  58. _used_size = 0;
  59. }
  60. // Use with care, in most cases you should make sure to
  61. // free all elements first (i.e. _used_size would be zero),
  62. // although it could also be used without this as an optimization
  63. // in some cases.
  64. void clear() {
  65. list.clear();
  66. freelist.clear();
  67. _used_size = 0;
  68. }
  69. uint64_t estimate_memory_use() const {
  70. return ((uint64_t)list.size() * sizeof(T)) + ((uint64_t)freelist.size() * sizeof(U));
  71. }
  72. const T &operator[](U p_index) const {
  73. return list[p_index];
  74. }
  75. T &operator[](U p_index) {
  76. return list[p_index];
  77. }
  78. // To be explicit in a pool there is a distinction
  79. // between the number of elements that are currently
  80. // in use, and the number of elements that have been reserved.
  81. // Using size() would be vague.
  82. U used_size() const { return _used_size; }
  83. U reserved_size() const { return list.size(); }
  84. T *request(U &r_id) {
  85. _used_size++;
  86. if (freelist.size()) {
  87. // pop from freelist
  88. int new_size = freelist.size() - 1;
  89. r_id = freelist[new_size];
  90. freelist.resize(new_size);
  91. return &list[r_id];
  92. }
  93. r_id = list.size();
  94. list.resize(r_id + 1);
  95. static_assert((!zero_on_first_request) || (__is_pod(T)), "zero_on_first_request requires trivial type");
  96. if (zero_on_first_request && __is_pod(T)) {
  97. list[r_id] = {};
  98. }
  99. return &list[r_id];
  100. }
  101. void free(const U &p_id) {
  102. // should not be on free list already
  103. ERR_FAIL_UNSIGNED_INDEX(p_id, list.size());
  104. freelist.push_back(p_id);
  105. ERR_FAIL_COND_MSG(!_used_size, "_used_size has become out of sync, have you double freed an item?");
  106. _used_size--;
  107. }
  108. };
  109. // a pooled list which automatically keeps a list of the active members
  110. template <class T, class U = uint32_t, bool force_trivial = false, bool zero_on_first_request = false>
  111. class TrackedPooledList {
  112. public:
  113. U pool_used_size() const { return _pool.used_size(); }
  114. U pool_reserved_size() const { return _pool.reserved_size(); }
  115. U active_size() const { return _active_list.size(); }
  116. // use with care, see the earlier notes in the PooledList clear()
  117. void clear() {
  118. _pool.clear();
  119. _active_list.clear();
  120. _active_map.clear();
  121. }
  122. U get_active_id(U p_index) const {
  123. return _active_list[p_index];
  124. }
  125. const T &get_active(U p_index) const {
  126. return _pool[get_active_id(p_index)];
  127. }
  128. T &get_active(U p_index) {
  129. return _pool[get_active_id(p_index)];
  130. }
  131. const T &operator[](U p_index) const {
  132. return _pool[p_index];
  133. }
  134. T &operator[](U p_index) {
  135. return _pool[p_index];
  136. }
  137. T *request(U &r_id) {
  138. T *item = _pool.request(r_id);
  139. // add to the active list
  140. U active_list_id = _active_list.size();
  141. _active_list.push_back(r_id);
  142. // expand the active map (this should be in sync with the pool list
  143. if (_pool.used_size() > _active_map.size()) {
  144. _active_map.resize(_pool.used_size());
  145. }
  146. // store in the active map
  147. _active_map[r_id] = active_list_id;
  148. return item;
  149. }
  150. void free(const U &p_id) {
  151. _pool.free(p_id);
  152. // remove from the active list.
  153. U list_id = _active_map[p_id];
  154. // zero the _active map to detect bugs (only in debug?)
  155. _active_map[p_id] = -1;
  156. _active_list.remove_unordered(list_id);
  157. // keep the replacement in sync with the correct list Id
  158. if (list_id < _active_list.size()) {
  159. // which pool id has been replaced in the active list
  160. U replacement_id = _active_list[list_id];
  161. // keep that replacements map up to date with the new position
  162. _active_map[replacement_id] = list_id;
  163. }
  164. }
  165. const LocalVector<U, U> &get_active_list() const { return _active_list; }
  166. private:
  167. PooledList<T, U, force_trivial, zero_on_first_request> _pool;
  168. LocalVector<U, U> _active_map;
  169. LocalVector<U, U> _active_list;
  170. };