ceph/src/rocksdb/include/rocksdb/slice_transform.h

   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 // Copyright (c) 2012 The LevelDB Authors. All rights reserved.
   6 // Use of this source code is governed by a BSD-style license that can be
   7 // found in the LICENSE file. See the AUTHORS file for names of contributors.
   8 //
   9 // Class for specifying user-defined functions which perform a
  10 // transformation on a slice.  It is not required that every slice
  11 // belong to the domain and/or range of a function.  Subclasses should
  12 // define InDomain and InRange to determine which slices are in either
  13 // of these sets respectively.
  14
  15 #pragma once
  16
  17 #include <string>
  18
  19 namespace rocksdb {
  20
  21 class Slice;
  22
  23 /*
  24  * A SliceTransform is a generic pluggable way of transforming one string
  25  * to another. Its primary use-case is in configuring rocksdb
  26  * to store prefix blooms by setting prefix_extractor in
  27  * ColumnFamilyOptions.
  28  */
  29 class SliceTransform {
  30  public:
  31   virtual ~SliceTransform() {};
  32
  33   // Return the name of this transformation.
  34   virtual const char* Name() const = 0;
  35
  36   // Extract a prefix from a specified key. This method is called when
  37   // a key is inserted into the db, and the returned slice is used to
  38   // create a bloom filter.
  39   virtual Slice Transform(const Slice& key) const = 0;
  40
  41   // Determine whether the specified key is compatible with the logic
  42   // specified in the Transform method. This method is invoked for every
  43   // key that is inserted into the db. If this method returns true,
  44   // then Transform is called to translate the key to its prefix and
  45   // that returned prefix is inserted into the bloom filter. If this
  46   // method returns false, then the call to Transform is skipped and
  47   // no prefix is inserted into the bloom filters.
  48   //
  49   // For example, if the Transform method operates on a fixed length
  50   // prefix of size 4, then an invocation to InDomain("abc") returns
  51   // false because the specified key length(3) is shorter than the
  52   // prefix size of 4.
  53   //
  54   // Wiki documentation here:
  55   // https://github.com/facebook/rocksdb/wiki/Prefix-Seek-API-Changes
  56   //
  57   virtual bool InDomain(const Slice& key) const = 0;
  58
  59   // This is currently not used and remains here for backward compatibility.
  60   virtual bool InRange(const Slice& /*dst*/) const { return false; }
  61
  62   // Some SliceTransform will have a full length which can be used to
  63   // determine if two keys are consecuitive. Can be disabled by always
  64   // returning 0
  65   virtual bool FullLengthEnabled(size_t* /*len*/) const { return false; }
  66
  67   // Transform(s)=Transform(`prefix`) for any s with `prefix` as a prefix.
  68   //
  69   // This function is not used by RocksDB, but for users. If users pass
  70   // Options by string to RocksDB, they might not know what prefix extractor
  71   // they are using. This function is to help users can determine:
  72   //   if they want to iterate all keys prefixing `prefix`, whether it is
  73   //   safe to use prefix bloom filter and seek to key `prefix`.
  74   // If this function returns true, this means a user can Seek() to a prefix
  75   // using the bloom filter. Otherwise, user needs to skip the bloom filter
  76   // by setting ReadOptions.total_order_seek = true.
  77   //
  78   // Here is an example: Suppose we implement a slice transform that returns
  79   // the first part of the string after splitting it using delimiter ",":
  80   // 1. SameResultWhenAppended("abc,") should return true. If applying prefix
  81   //    bloom filter using it, all slices matching "abc:.*" will be extracted
  82   //    to "abc,", so any SST file or memtable containing any of those key
  83   //    will not be filtered out.
  84   // 2. SameResultWhenAppended("abc") should return false. A user will not
  85   //    guaranteed to see all the keys matching "abc.*" if a user seek to "abc"
  86   //    against a DB with the same setting. If one SST file only contains
  87   //    "abcd,e", the file can be filtered out and the key will be invisible.
  88   //
  89   // i.e., an implementation always returning false is safe.
  90   virtual bool SameResultWhenAppended(const Slice& /*prefix*/) const {
  91     return false;
  92   }
  93 };
  94
  95 extern const SliceTransform* NewFixedPrefixTransform(size_t prefix_len);
  96
  97 extern const SliceTransform* NewCappedPrefixTransform(size_t cap_len);
  98
  99 extern const SliceTransform* NewNoopTransform();
 100
 101 }