1 // Copyright (c) 2011-present, Facebook, Inc.  All rights reserved.
2 //  This source code is licensed under both the GPLv2 (found in the
3 //  COPYING file in the root directory) and Apache 2.0 License
4 //  (found in the LICENSE.Apache file in the root directory).
5 
6 #pragma once
7 
8 #include <stdint.h>
9 #include <memory>
10 #include <string>
11 #include "rocksdb/cache.h"
12 #include "rocksdb/env.h"
13 #include "rocksdb/slice.h"
14 #include "rocksdb/statistics.h"
15 #include "rocksdb/status.h"
16 
17 namespace ROCKSDB_NAMESPACE {
18 
19 class SimCache;
20 
21 // For instrumentation purpose, use NewSimCache instead of NewLRUCache API
22 // NewSimCache is a wrapper function returning a SimCache instance that can
23 // have additional interface provided in Simcache class besides Cache interface
24 // to predict block cache hit rate without actually allocating the memory. It
25 // can help users tune their current block cache size, and determine how
26 // efficient they are using the memory.
27 //
28 // Since GetSimCapacity() returns the capacity for simulutation, it differs from
29 // actual memory usage, which can be estimated as:
30 // sim_capacity * entry_size / (entry_size + block_size),
31 // where 76 <= entry_size <= 104,
32 // BlockBasedTableOptions.block_size = 4096 by default but is configurable,
33 // Therefore, generally the actual memory overhead of SimCache is Less than
34 // sim_capacity * 2%
35 extern std::shared_ptr<SimCache> NewSimCache(std::shared_ptr<Cache> cache,
36                                              size_t sim_capacity,
37                                              int num_shard_bits);
38 
39 extern std::shared_ptr<SimCache> NewSimCache(std::shared_ptr<Cache> sim_cache,
40                                              std::shared_ptr<Cache> cache,
41                                              int num_shard_bits);
42 
43 class SimCache : public Cache {
44  public:
SimCache()45   SimCache() {}
46 
~SimCache()47   ~SimCache() override {}
48 
Name()49   const char* Name() const override { return "SimCache"; }
50 
51   // returns the maximum configured capacity of the simcache for simulation
52   virtual size_t GetSimCapacity() const = 0;
53 
54   // simcache doesn't provide internal handler reference to user, so always
55   // PinnedUsage = 0 and the behavior will be not exactly consistent the
56   // with real cache.
57   // returns the memory size for the entries residing in the simcache.
58   virtual size_t GetSimUsage() const = 0;
59 
60   // sets the maximum configured capacity of the simcache. When the new
61   // capacity is less than the old capacity and the existing usage is
62   // greater than new capacity, the implementation will purge old entries
63   // to fit new capapicty.
64   virtual void SetSimCapacity(size_t capacity) = 0;
65 
66   // returns the lookup times of simcache
67   virtual uint64_t get_miss_counter() const = 0;
68   // returns the hit times of simcache
69   virtual uint64_t get_hit_counter() const = 0;
70   // reset the lookup and hit counters
71   virtual void reset_counter() = 0;
72   // String representation of the statistics of the simcache
73   virtual std::string ToString() const = 0;
74 
75   // Start storing logs of the cache activity (Add/Lookup) into
76   // a file located at activity_log_file, max_logging_size option can be used to
77   // stop logging to the file automatically after reaching a specific size in
78   // bytes, a values of 0 disable this feature
79   virtual Status StartActivityLogging(const std::string& activity_log_file,
80                                       Env* env,
81                                       uint64_t max_logging_size = 0) = 0;
82 
83   // Stop cache activity logging if any
84   virtual void StopActivityLogging() = 0;
85 
86   // Status of cache logging happening in background
87   virtual Status GetActivityLoggingStatus() = 0;
88 
89  private:
90   SimCache(const SimCache&);
91   SimCache& operator=(const SimCache&);
92 };
93 
94 }  // namespace ROCKSDB_NAMESPACE
95