Document exclusive access guarantees for evicted track objects

2 files changed, 12 insertions, 0 deletions

diff --git a/src/track/globaltrackcache.cpp b/src/track/globaltrackcache.cpp
index b5da81acfa..f5450b22a6 100644
--- a/src/track/globaltrackcache.cpp
+++ b/src/track/globaltrackcache.cpp
@@ -675,6 +675,9 @@ void GlobalTrackCache::slotEvictAndSave(
     DEBUG_ASSERT_QOBJECT_THREAD_AFFINITY(this);
     DEBUG_ASSERT(cacheEntryPtr);
 
+    // GlobalTrackCacheSaver::saveEvictedTrack() requires that
+    // exclusive access is guaranteed for the duration of the
+    // whole invocation!
     GlobalTrackCacheLocker cacheLocker;
 
     if (!cacheEntryPtr->expired()) {
diff --git a/src/track/globaltrackcache.h b/src/track/globaltrackcache.h
index 5ea0ace327..e10ad765e1 100644
--- a/src/track/globaltrackcache.h
+++ b/src/track/globaltrackcache.h
@@ -185,9 +185,18 @@ private:
     ///
     /// GlobalTrackCache ensures that the given pointer is valid
     /// and the last and only reference to this Track object.
+    /// While invoked the GlobalTrackCache is locked to ensure
+    /// that this particular track is not accessible while
+    /// saving the Track object, e.g. by updating the database
+    /// and exporting file tags.
     ///
     /// This callback method will always be invoked from the
     /// event loop thread of the owning GlobalTrackCache instance.
+    /// Typically the GlobalTrackCache lives on the main thread
+    /// that also controls access to the database.
+    /// NOTE(2020-06-06): If these assumptions about thread affinity
+    /// are no longer valid the design decisions need to be revisited
+    /// carefully!
     virtual void saveEvictedTrack(
             Track* pEvictedTrack) noexcept = 0;