YugabyteDB (2.13.0.0-b42, bfc6a6643e7399ac8a0e81d06a3ee6d6571b33ab)

// Copyright (c) 2011-present, Facebook, Inc.  All rights reserved.

// This source code is licensed under the BSD-style license found in the

// LICENSE file in the root directory of this source tree. An additional grant

// of patent rights can be found in the PATENTS file in the same directory.

// Copyright (c) 2011 The LevelDB Authors. All rights reserved.

// Use of this source code is governed by a BSD-style license that can be

// found in the LICENSE file. See the AUTHORS file for names of contributors.

//

// The following only applies to changes made to this file as part of YugaByte development.

//

// Portions Copyright (c) YugaByte, Inc.

//

// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except

// in compliance with the License.  You may obtain a copy of the License at

//

// http://www.apache.org/licenses/LICENSE-2.0

//

// Unless required by applicable law or agreed to in writing, software distributed under the License

// is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express

// or implied.  See the License for the specific language governing permissions and limitations

// under the License.

//

// A Cache is an interface that maps keys to values.  It has internal

// synchronization and may be safely accessed concurrently from

// multiple threads.  It may automatically evict entries to make room

// for new entries.  Values have a specified charge against the cache

// capacity.  For example, a cache where the values are variable

// length strings, may use the length of the string as the charge for

// the string.

//

// A builtin cache implementation with a least-recently-used eviction

// policy is provided.  Clients may use their own implementations if

// they want something more sophisticated (like scan-resistance, a

// custom eviction policy, variable cache sizing, etc.)

#ifndef YB_ROCKSDB_CACHE_H

#define YB_ROCKSDB_CACHE_H

#include <stdint.h>

#include <memory>

#include "yb/rocksdb/statistics.h"

#include "yb/rocksdb/status.h"

#include "yb/util/slice.h"

namespace rocksdb {

using std::shared_ptr;

// Classifies the type of the subcache.

enum SubCacheType {

  SINGLE_TOUCH,

  MULTI_TOUCH

};

class Cache;

// Create a new cache with a fixed size capacity. The cache is sharded

// to 2^num_shard_bits shards, by hash of the key. The total capacity

// is divided and evenly assigned to each shard.

//

// The parameter num_shard_bits defaults to 4, and strict_capacity_limit

// defaults to false.

extern shared_ptr<Cache> NewLRUCache(size_t capacity);

extern shared_ptr<Cache> NewLRUCache(size_t capacity, int num_shard_bits);

extern shared_ptr<Cache> NewLRUCache(size_t capacity, int num_shard_bits,

                                     bool strict_capacity_limit);

using QueryId = int64_t;

// Query ids to represent values for the default query id.

constexpr QueryId kDefaultQueryId = 0;

// Query ids to represent values that should be in multi-touch cache.

constexpr QueryId kInMultiTouchId = -1;

// Query ids to represent values that should not be in any cache.

constexpr QueryId kNoCacheQueryId = -2;

class Cache {

 public:

  Cache() { }

  // Destroys all existing entries by calling the "deleter"

  // function that was passed via the Insert() function.

  //

  // @See Insert

  virtual ~Cache();

  // Opaque handle to an entry stored in the cache.

  struct Handle { };

  // Insert a mapping from key->value into the cache and assign it

  // the specified charge against the total cache capacity.

  // If strict_capacity_limit is true and cache reaches its full capacity,

  // return Status::Incomplete.

  //

  // If handle is not nullptr, returns a handle that corresponds to the

  // mapping. The caller must call this->Release(handle) when the returned

  // mapping is no longer needed. In case of error caller is responsible to

  // cleanup the value (i.e. calling "deleter").

  //

  // If handle is nullptr, it is as if Release is called immediately after

  // insert. In case of error value will be cleanup.

  //

  // When the inserted entry is no longer needed, the key and

  // value will be passed to "deleter".

  // The query ids will allow the cache values to be included in the

  // single touch or multi touch cache, which gives scan resistance to the

  // cache.

  virtual Status Insert(const Slice& key, const QueryId query_id,

                        void* value, size_t charge,

                        void (*deleter)(const Slice& key, void* value),

                        Handle** handle = nullptr,

                        Statistics* statistics = nullptr) = 0;

  // If the cache has no mapping for "key", returns nullptr.

  //

  // Else return a handle that corresponds to the mapping.  The caller

  // must call this->Release(handle) when the returned mapping is no

  // longer needed.

  virtual Handle* Lookup(const Slice& key, const QueryId query_id,

                         Statistics* statistics = nullptr) = 0;

  // Release a mapping returned by a previous Lookup().

  // REQUIRES: handle must not have been released yet.

  // REQUIRES: handle must have been returned by a method on *this.

  virtual void Release(Handle* handle) = 0;

  // Return the value encapsulated in a handle returned by a

  // successful Lookup().

  // REQUIRES: handle must not have been released yet.

  // REQUIRES: handle must have been returned by a method on *this.

  virtual void* Value(Handle* handle) = 0;

  // If the cache contains entry for key, erase it.  Note that the

  // underlying entry will be kept around until all existing handles

  // to it have been released.

  virtual void Erase(const Slice& key) = 0;

  // Return a new numeric id.  May be used by multiple clients who are

  // sharing the same cache to partition the key space.  Typically the

  // client will allocate a new id at startup and prepend the id to

  // its cache keys.

  virtual uint64_t NewId() = 0;

  // sets the maximum configured capacity of the cache. When the new

  // capacity is less than the old capacity and the existing usage is

  // greater than new capacity, the implementation will do its best job to

  // purge the released entries from the cache in order to lower the usage

  virtual void SetCapacity(size_t capacity) = 0;

  // Set whether to return error on insertion when cache reaches its full

  // capacity.

  virtual bool HasStrictCapacityLimit() const = 0;

  // returns the maximum configured capacity of the cache

  virtual size_t GetCapacity() const = 0;

  // returns the memory size for the entries residing in the cache.

  virtual size_t GetUsage() const = 0;

  // returns the memory size for a specific entry in the cache.

  virtual size_t GetUsage(Handle* handle) const = 0;

  // returns the memory size for the entries in use by the system

  virtual size_t GetPinnedUsage() const = 0;

  // Gets the sub_cache type of the handle.

  virtual SubCacheType GetSubCacheType(Handle* e) const {

    // Default implementation assumes multi-touch.

    return MULTI_TOUCH;

  }

  // Call this on shutdown if you want to speed it up. Cache will disown

  // any underlying data and will not free it on delete. This call will leak

  // memory - call this only if you're shutting down the process.

  // Any attempts of using cache after this call will fail terribly.

  // Always delete the DB object before calling this method!

  virtual void DisownData() {

    // default implementation is noop

  }

  // Apply callback to all entries in the cache

  // If thread_safe is true, it will also lock the accesses. Otherwise, it will

  // access the cache without the lock held

  virtual void ApplyToAllCacheEntries(void (*callback)(void*, size_t),

                                      bool thread_safe) = 0;

  virtual void SetMetrics(const scoped_refptr<yb::MetricEntity>& entity) = 0;

  // Tries to evict specified amount of bytes from cache.

  virtual size_t Evict(size_t required) { return 0; }

  // Returns the single-touch and multi-touch cache usages for each of the shard.

  virtual std::vector<std::pair<size_t, size_t>> TEST_GetIndividualUsages() = 0;

 private:

  void LRU_Remove(Handle* e);

  void LRU_Append(Handle* e);

  void Unref(Handle* e);

  // No copying allowed

  Cache(const Cache&);

  void operator=(const Cache&);

};

}  // namespace rocksdb

#endif  // YB_ROCKSDB_CACHE_H