1// Copyright (c) 2011 The LevelDB Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file. See the AUTHORS file for names of contributors.
4//
5// A Cache is an interface that maps keys to values. It has internal
6// synchronization and may be safely accessed concurrently from
7// multiple threads. It may automatically evict entries to make room
8// for new entries. Values have a specified charge against the cache
9// capacity. For example, a cache where the values are variable
10// length strings, may use the length of the string as the charge for
11// the string.
12//
13// A builtin cache implementation with a least-recently-used eviction
14// policy is provided. Clients may use their own implementations if
15// they want something more sophisticated (like scan-resistance, a
16// custom eviction policy, variable cache sizing, etc.)
17
18#ifndef STORAGE_LEVELDB_INCLUDE_CACHE_H_
19#define STORAGE_LEVELDB_INCLUDE_CACHE_H_
20
21#include <cstdint>
22
23#include "leveldb/export.h"
24#include "leveldb/slice.h"
25
26namespace leveldb {
27
28class LEVELDB_EXPORT Cache;
29
30// Create a new cache with a fixed size capacity. This implementation
31// of Cache uses a least-recently-used eviction policy.
32LEVELDB_EXPORT Cache* NewLRUCache(size_t capacity);
33
34class LEVELDB_EXPORT Cache {
35 public:
36 Cache() = default;
37
38 Cache(const Cache&) = delete;
39 Cache& operator=(const Cache&) = delete;
40
41 // Destroys all existing entries by calling the "deleter"
42 // function that was passed to the constructor.
43 virtual ~Cache();
44
45 // Opaque handle to an entry stored in the cache.
46 struct Handle {};
47
48 // Insert a mapping from key->value into the cache and assign it
49 // the specified charge against the total cache capacity.
50 //
51 // Returns a handle that corresponds to the mapping. The caller
52 // must call this->Release(handle) when the returned mapping is no
53 // longer needed.
54 //
55 // When the inserted entry is no longer needed, the key and
56 // value will be passed to "deleter".
57 virtual Handle* Insert(const Slice& key, void* value, size_t charge,
58 void (*deleter)(const Slice& key, void* value)) = 0;
59
60 // If the cache has no mapping for "key", returns nullptr.
61 //
62 // Else return a handle that corresponds to the mapping. The caller
63 // must call this->Release(handle) when the returned mapping is no
64 // longer needed.
65 virtual Handle* Lookup(const Slice& key) = 0;
66
67 // Release a mapping returned by a previous Lookup().
68 // REQUIRES: handle must not have been released yet.
69 // REQUIRES: handle must have been returned by a method on *this.
70 virtual void Release(Handle* handle) = 0;
71
72 // Return the value encapsulated in a handle returned by a
73 // successful Lookup().
74 // REQUIRES: handle must not have been released yet.
75 // REQUIRES: handle must have been returned by a method on *this.
76 virtual void* Value(Handle* handle) = 0;
77
78 // If the cache contains entry for key, erase it. Note that the
79 // underlying entry will be kept around until all existing handles
80 // to it have been released.
81 virtual void Erase(const Slice& key) = 0;
82
83 // Return a new numeric id. May be used by multiple clients who are
84 // sharing the same cache to partition the key space. Typically the
85 // client will allocate a new id at startup and prepend the id to
86 // its cache keys.
87 virtual uint64_t NewId() = 0;
88
89 // Remove all cache entries that are not actively in use. Memory-constrained
90 // applications may wish to call this method to reduce memory usage.
91 // Default implementation of Prune() does nothing. Subclasses are strongly
92 // encouraged to override the default implementation. A future release of
93 // leveldb may change Prune() to a pure abstract method.
94 virtual void Prune() {}
95
96 // Return an estimate of the combined charges of all elements stored in the
97 // cache.
98 virtual size_t TotalCharge() const = 0;
99};
100
101} // namespace leveldb
102
103#endif // STORAGE_LEVELDB_INCLUDE_CACHE_H_
104