Clear external tileset skeletons from tile tree to save memory usage

CHANGES.md

@@ -18,6 +18,7 @@
 
 - Fixed parsing URIs that have a scheme followed by `:` instead of `://`.
 - Fixed decoding of KHR_mesh_quantization normalized values.
+- `Tile` children of external tilesets will now be cleared when the external tileset is unloaded, fixing a memory leak that happened as a result of these `Tile` skeletons accumulating over time.
 
 ### v0.44.3 - 2025-02-12
 

CMakeLists.txt

@@ -185,6 +185,7 @@ option(CESIUM_TESTS_ENABLED "Whether to enable tests" ON)
 option(CESIUM_GLM_STRICT_ENABLED "Whether to force strict GLM compile definitions." ON)
 option(CESIUM_DISABLE_DEFAULT_ELLIPSOID "Whether to disable the WGS84 default value for ellipsoid parameters across cesium-native." OFF)
 option(CESIUM_MSVC_STATIC_RUNTIME_ENABLED "Whether to enable static linking for MSVC runtimes" OFF)
+option(CESIUM_DEBUG_TILE_UNLOADING "Whether to enable tracking of tile _doNotUnloadCount modifications for tile unloading debugging." OFF)
 
 if (CESIUM_MSVC_STATIC_RUNTIME_ENABLED)
     set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")

Cesium3DTilesSelection/include/Cesium3DTilesSelection/Tile.h

@@ -17,11 +17,35 @@
 #include <optional>
 #include <span>
 #include <string>
+#ifdef CESIUM_DEBUG_TILE_UNLOADING
+#include <unordered_map>
+#endif
 #include <vector>
 
 namespace Cesium3DTilesSelection {
 class TilesetContentLoader;
 
+#ifdef CESIUM_DEBUG_TILE_UNLOADING
+class TileDoNotUnloadCountTracker {
+private:
+  struct Entry {
+    std::string reason;
+    bool increment;
+    int32_t newCount;
+  };
+
+public:
+  static void addEntry(
+      const uint64_t id,
+      bool increment,
+      const std::string& reason,
+      int32_t newCount);
+
+private:
+  static std::unordered_map<std::string, std::vector<Entry>> _entries;
+};
+#endif
+
 /**
  * The current state of this tile in the loading process.
  */
@@ -188,6 +212,13 @@ class CESIUM3DTILESSELECTION_API Tile final {
     return std::span<const Tile>(this->_children);
   }
 
+  /**
+   * @brief Clears the children of this tile.
+   *
+   * This function is not supposed to be called by clients.
+   */
+  void clearChildren() noexcept;
+
   /**
    * @brief Assigns the given child tiles to this tile.
    *
@@ -485,7 +516,64 @@ class CESIUM3DTILESSELECTION_API Tile final {
    */
   TileLoadState getState() const noexcept;
 
+  /**
+   * @brief Returns the internal count denoting that the tile and its ancestors
+   * should not be unloaded.
+   *
+   * This function is not supposed to be called by clients.
+   */
+  int32_t getDoNotUnloadCount() const noexcept {
+    return this->_doNotUnloadCount;
+  }
+
+  /**
+   * @brief Increments the internal count denoting that the tile and its
+   * ancestors should not be unloaded.
+   *
+   * This function is not supposed to be called by clients.
+   */
+  void incrementDoNotUnloadCount(const char* reason) noexcept;
+
+  /**
+   * @brief Decrements the internal count denoting that the tile and its
+   * ancestors should not be unloaded.
+   *
+   * This function is not supposed to be called by clients.
+   */
+  void decrementDoNotUnloadCount(const char* reason) noexcept;
+
+  /**
+   * @brief Marks this tile as having content that has not yet been unloaded,
+   * preventing a parent external tileset from cleaning up. This count will be
+   * propagated to any ancestors.
+   *
+   * This function is not supposed to be called by clients.
+   */
+  void incrementTilesStillNotUnloadedCount() noexcept;
+
+  /**
+   * @brief Unmarks this tile as having content that has not yet been unloaded,
+   * allowing a parent external tileset to clean up. This count will be
+   * propagated to any ancestors.
+   *
+   * This function is not supposed to be called by clients.
+   */
+  void decrementTilesStillNotUnloadedCount() noexcept;
+
+  /**
+   * @brief Obtains the number of tiles at or below this tile (that is, the tile
+   * itself and its children) that still have content that has not yet been
+   * unloaded, preventing a parent external tileset from cleaning up.
+   */
+  int32_t getTilesStillNotUnloadedCount() const noexcept {
+    return this->_tilesStillNotUnloadedCount;
+  }
+
 private:
+  void incrementDoNotUnloadCount(const std::string& reason) noexcept;
+
+  void decrementDoNotUnloadCount(const std::string& reason) noexcept;
+
   struct TileConstructorImpl {};
   template <
       typename... TileContentArgs,
@@ -548,6 +636,12 @@ class CESIUM3DTILESSELECTION_API Tile final {
   // mapped raster overlay
   std::vector<RasterMappedTo3DTile> _rasterTiles;
 
+  // Number of existing claims on this tile preventing it and its parent
+  // external tileset (if any) from being unloaded from the tree.
+  int32_t _doNotUnloadCount = 0;
+
+  int32_t _tilesStillNotUnloadedCount = 0;
+
   friend class TilesetContentManager;
   friend class MockTilesetContentManagerTestFixture;
 

Cesium3DTilesSelection/include/Cesium3DTilesSelection/Tileset.h

@@ -471,6 +471,7 @@ class CESIUM3DTILESSELECTION_API Tileset final {
   void _processWorkerThreadLoadQueue();
   void _processMainThreadLoadQueue();
 
+  void _clearChildrenRecursively(Tile* pTile) noexcept;
   void _unloadCachedTiles(double timeBudget) noexcept;
   void _markTileVisited(Tile& tile) noexcept;
 

Cesium3DTilesSelection/src/Tile.cpp

@@ -6,13 +6,17 @@
 #include <CesiumGltf/BufferView.h>
 #include <CesiumGltf/Image.h>
 #include <CesiumGltf/Model.h>
+#include <CesiumUtility/Assert.h>
 #include <CesiumUtility/Math.h>
 
 #include <algorithm>
 #include <cstddef>
 #include <cstdint>
 #include <memory>
 #include <stdexcept>
+#ifdef CESIUM_DEBUG_TILE_UNLOADING
+#include <unordered_map>
+#endif
 #include <utility>
 #include <vector>
 
@@ -22,6 +26,28 @@ using namespace CesiumUtility;
 using namespace std::string_literals;
 
 namespace Cesium3DTilesSelection {
+#ifdef CESIUM_DEBUG_TILE_UNLOADING
+std::unordered_map<std::string, std::vector<TileDoNotUnloadCountTracker::Entry>>
+    TileDoNotUnloadCountTracker::_entries;
+
+void TileDoNotUnloadCountTracker::addEntry(
+    uint64_t id,
+    bool increment,
+    const std::string& reason,
+    int32_t newCount) {
+  const std::string idString = fmt::format("{:x}", id);
+  const auto foundIt = TileDoNotUnloadCountTracker::_entries.find(idString);
+  if (foundIt != TileDoNotUnloadCountTracker::_entries.end()) {
+    foundIt->second.push_back(Entry{reason, increment, newCount});
+  } else {
+    std::vector<Entry> entries{Entry{reason, increment, newCount}};
+
+    TileDoNotUnloadCountTracker::_entries.insert(
+        {idString, std::move(entries)});
+  }
+}
+#endif
+
 Tile::Tile(TilesetContentLoader* pLoader) noexcept
     : Tile(TileConstructorImpl{}, TileLoadState::Unloaded, pLoader) {}
 
@@ -63,7 +89,12 @@ Tile::Tile(
       _content{std::forward<TileContentArgs>(args)...},
       _pLoader{pLoader},
       _loadState{loadState},
-      _mightHaveLatentChildren{true} {}
+      _mightHaveLatentChildren{true} {
+  if (_loadState != TileLoadState::Unloaded && !_content.isUnknownContent() &&
+      !_content.isEmptyContent()) {
+    incrementTilesStillNotUnloadedCount();
+  }
+}
 
 Tile::Tile(Tile&& rhs) noexcept
     : _pParent(rhs._pParent),
@@ -80,7 +111,8 @@ Tile::Tile(Tile&& rhs) noexcept
       _content(std::move(rhs._content)),
       _pLoader{rhs._pLoader},
       _loadState{rhs._loadState},
-      _mightHaveLatentChildren{rhs._mightHaveLatentChildren} {
+      _mightHaveLatentChildren{rhs._mightHaveLatentChildren},
+      _tilesStillNotUnloadedCount{rhs._tilesStillNotUnloadedCount} {
   // since children of rhs will have the parent pointed to rhs,
   // we will reparent them to this tile as rhs will be destroyed after this
   for (Tile& tile : this->_children) {
@@ -112,6 +144,15 @@ Tile& Tile::operator=(Tile&& rhs) noexcept {
     this->_pLoader = rhs._pLoader;
     this->_loadState = rhs._loadState;
     this->_mightHaveLatentChildren = rhs._mightHaveLatentChildren;
+    this->_tilesStillNotUnloadedCount = rhs._tilesStillNotUnloadedCount;
+    // We deliberately do *not* copy the _doNotUnloadCount of rhs here.
+    // This is because the _doNotUnloadCount is a count of instances of the
+    // *pointer* to the tile, denoting the number of active pointers that would
+    // be invalidated if the Tile were to be deleted. Because the memory
+    // location of the tile will have changed as a result of the move operation,
+    // the new Tile object will not have any pointers referencing it, so copying
+    // over the count would be incorrect and could result in a Tile not being
+    // removed when it otherwise should be.
   }
 
   return *this;
@@ -122,9 +163,19 @@ void Tile::createChildTiles(std::vector<Tile>&& children) {
     throw std::runtime_error("Children already created.");
   }
 
+  int32_t prevLoadedContentsCount = this->_tilesStillNotUnloadedCount;
   this->_children = std::move(children);
   for (Tile& tile : this->_children) {
     tile.setParent(this);
+    this->_tilesStillNotUnloadedCount += tile._tilesStillNotUnloadedCount;
+  }
+
+  // Propagate new loaded contents count up the chain
+  Tile* pParent = this->_pParent;
+  while (pParent != nullptr) {
+    pParent->_tilesStillNotUnloadedCount -= prevLoadedContentsCount;
+    pParent->_tilesStillNotUnloadedCount += this->_tilesStillNotUnloadedCount;
+    pParent = pParent->_pParent;
   }
 }
 
@@ -243,4 +294,82 @@ void Tile::setMightHaveLatentChildren(bool mightHaveLatentChildren) noexcept {
   this->_mightHaveLatentChildren = mightHaveLatentChildren;
 }
 
+void Tile::clearChildren() noexcept {
+  CESIUM_ASSERT(this->_doNotUnloadCount == 0);
+  this->_children.clear();
+}
+
+void Tile::incrementDoNotUnloadCount(
+    [[maybe_unused]] const char* reason) noexcept {
+#ifdef CESIUM_DEBUG_TILE_UNLOADING
+  const std::string reasonStr = fmt::format(
+      "Initiator ID: {:x}, {}",
+      reinterpret_cast<uint64_t>(this),
+      reason);
+  this->incrementDoNotUnloadCount(reasonStr);
+#else
+  this->incrementDoNotUnloadCount(std::string());
+#endif
+}
+
+void Tile::decrementDoNotUnloadCount(
+    [[maybe_unused]] const char* reason) noexcept {
+#ifdef CESIUM_DEBUG_TILE_UNLOADING
+  const std::string reasonStr = fmt::format(
+      "Initiator ID: {:x}, {}",
+      reinterpret_cast<uint64_t>(this),
+      reason);
+  this->decrementDoNotUnloadCount(reasonStr);
+#else
+  this->decrementDoNotUnloadCount(std::string());
+#endif
+}
+
+void Tile::incrementDoNotUnloadCount(
+    [[maybe_unused]] const std::string& reason) noexcept {
+  ++this->_doNotUnloadCount;
+#ifdef CESIUM_DEBUG_TILE_UNLOADING
+  TileDoNotUnloadCountTracker::addEntry(
+      reinterpret_cast<uint64_t>(this),
+      true,
+      std::string(reason),
+      this->_doNotUnloadCount);
+#endif
+  if (this->getParent() != nullptr) {
+    this->getParent()->incrementDoNotUnloadCount(reason);
+  }
+}
+
+void Tile::decrementDoNotUnloadCount(
+    [[maybe_unused]] const std::string& reason) noexcept {
+  CESIUM_ASSERT(this->_doNotUnloadCount > 0);
+  --this->_doNotUnloadCount;
+#ifdef CESIUM_DEBUG_TILE_UNLOADING
+  TileDoNotUnloadCountTracker::addEntry(
+      reinterpret_cast<uint64_t>(this),
+      false,
+      std::string(reason),
+      this->_doNotUnloadCount);
+#endif
+  if (this->getParent() != nullptr) {
+    this->getParent()->decrementDoNotUnloadCount(reason);
+  }
+}
+
+void Tile::incrementTilesStillNotUnloadedCount() noexcept {
+  CESIUM_ASSERT(this->_tilesStillNotUnloadedCount >= 0);
+  this->_tilesStillNotUnloadedCount++;
+  if (this->getParent() != nullptr) {
+    this->getParent()->incrementTilesStillNotUnloadedCount();
+  }
+}
+
+void Tile::decrementTilesStillNotUnloadedCount() noexcept {
+  CESIUM_ASSERT(this->_tilesStillNotUnloadedCount > 0);
+  --this->_tilesStillNotUnloadedCount;
+  if (this->getParent() != nullptr) {
+    this->getParent()->decrementTilesStillNotUnloadedCount();
+  }
+}
+
 } // namespace Cesium3DTilesSelection