Prepare for specialized interface for row cache (#11620)

Summary:
An internal user wants to implement a key-aware row cache policy. For that, they need to know the components of the cache key, especially the user key component. With a specialized `RowCache` interface, we will be able to tell them the components so they won't have to make assumptions about our internal key schema.

This PR prepares for the specialized `RowCache` interface by updating the migration plan of https://github.com/facebook/rocksdb/issues/11450. I added a release note for the removed APIs and didn't mention the added ones for now.

Pull Request resolved: https://github.com/facebook/rocksdb/pull/11620

Reviewed By: pdillinger

Differential Revision: D47536962

Pulled By: ajkr

fbshipit-source-id: bbee0fc4ad67fc699a66b8f2b4ea4544dd003691

cache/lru_cache.cc

@@ -712,12 +712,12 @@ std::shared_ptr<Cache> LRUCacheOptions::MakeSharedCache() const {
   return cache;
 }
 
-std::shared_ptr<GeneralCache> LRUCacheOptions::MakeSharedGeneralCache() const {
+std::shared_ptr<RowCache> LRUCacheOptions::MakeSharedRowCache() const {
   if (secondary_cache) {
-    // Not allowed for a GeneralCache
+    // Not allowed for a RowCache
     return nullptr;
   }
-  // Works while GeneralCache is an alias for Cache
+  // Works while RowCache is an alias for Cache
   return MakeSharedCache();
 }
 }  // namespace ROCKSDB_NAMESPACE

db/db_test.cc

@@ -6902,16 +6902,16 @@ TEST_F(DBTest, RowCache) {
   options.statistics = ROCKSDB_NAMESPACE::CreateDBStatistics();
   LRUCacheOptions cache_options;
   cache_options.capacity = 8192;
-  options.row_cache = cache_options.MakeSharedGeneralCache();
+  options.row_cache = cache_options.MakeSharedRowCache();
   // BEGIN check that Cache classes as aliases of each other.
-  // Currently, GeneralCache and BlockCache are aliases for Cache.
+  // Currently, RowCache and BlockCache are aliases for Cache.
   // This is expected to change (carefully, intentionally)
-  std::shared_ptr<GeneralCache> general_cache = options.row_cache;
-  std::shared_ptr<Cache> cache = general_cache;
-  std::shared_ptr<BlockCache> block_cache = general_cache;
-  general_cache = cache;
+  std::shared_ptr<RowCache> row_cache = options.row_cache;
+  std::shared_ptr<Cache> cache = row_cache;
+  std::shared_ptr<BlockCache> block_cache = row_cache;
+  row_cache = cache;
   block_cache = cache;
-  general_cache = block_cache;
+  row_cache = block_cache;
   cache = block_cache;
   // END check that Cache classes as aliases of each other.
   DestroyAndReopen(options);

include/rocksdb/cache.h

@@ -32,18 +32,18 @@ class SecondaryCache;
 // example, HyperClockCache is not usable as a general cache because it expects
 // only fixed-size block cache keys, but this limitation is not yet reflected
 // in the API function signatures.
-// * Phase 1 (done) - Make both BlockCache and GeneralCache aliases for Cache,
-// and make a factory function for general caches. Encourage users of row_cache
-// (not common) to switch to the factory function for general caches.
-// * Phase 2 - Split off GenericCache as its own class, removing secondary
+// * Phase 1 (done) - Make both BlockCache and RowCache aliases for Cache,
+// and make a factory function for row caches. Encourage users of row_cache
+// (not common) to switch to the factory function for row caches.
+// * Phase 2 - Split off RowCache as its own class, removing secondary
 // cache support features and more from the API to simplify it. Between Phase 1
 // and Phase 2 users of row_cache will need to update their code. Any time
-// after Phase 2, the block cache API can become more specialized in ways
-// incompatible with general caches.
+// after Phase 2, the block cache and row cache APIs can become more specialized
+// in ways incompatible with general caches.
 // * Phase 3 - Move existing RocksDB uses of Cache to BlockCache, and deprecate
 // (but not yet remove) Cache as an alias for BlockCache.
 using BlockCache = Cache;
-using GeneralCache = Cache;
+using RowCache = Cache;
 
 // Classifications of block cache entries.
 //
@@ -155,7 +155,7 @@ struct ShardedCacheOptions {
   CacheMetadataChargePolicy metadata_charge_policy =
       kDefaultCacheMetadataChargePolicy;
 
-  // A SecondaryCache instance to use the non-volatile tier. For a GeneralCache
+  // A SecondaryCache instance to use the non-volatile tier. For a RowCache
   // this option must be kept as default empty.
   std::shared_ptr<SecondaryCache> secondary_cache;
 
@@ -260,9 +260,9 @@ struct LRUCacheOptions : public ShardedCacheOptions {
   // Construct an instance of LRUCache using these options
   std::shared_ptr<Cache> MakeSharedCache() const;
 
-  // Construct an instance of LRUCache for use as a general cache (e.g. for
-  // row_cache). Some options are not relevant to general caches.
-  std::shared_ptr<GeneralCache> MakeSharedGeneralCache() const;
+  // Construct an instance of LRUCache for use as a row cache, typically for
+  // `DBOptions::row_cache`. Some options are not relevant to row caches.
+  std::shared_ptr<RowCache> MakeSharedRowCache() const;
 };
 
 // DEPRECATED wrapper function

include/rocksdb/options.h

@@ -1157,7 +1157,7 @@ struct DBOptions {
 
   // A global cache for table-level rows.
   // Default: nullptr (disabled)
-  std::shared_ptr<GeneralCache> row_cache = nullptr;
+  std::shared_ptr<RowCache> row_cache = nullptr;
 
   // A filter object supplied to be invoked while processing write-ahead-logs
   // (WALs) during recovery. The filter provides a way to inspect log

unreleased_history/public_api_changes/rename_migration_caches.md

@@ -0,0 +1 @@
+Removed recently added APIs `GeneralCache` and `MakeSharedGeneralCache()` as our plan changed to stop exposing a general-purpose cache interface. The old forms of these APIs, `Cache` and `NewLRUCache()`, are still available, although general-purpose caching support will be dropped eventually.