ceph/src/rocksdb/include/rocksdb/utilities/db_ttl.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
   6 #pragma once
   7 #ifndef ROCKSDB_LITE
   8
   9 #include <string>
  10 #include <vector>
  11
  12 #include "rocksdb/db.h"
  13 #include "rocksdb/utilities/stackable_db.h"
  14
  15 namespace ROCKSDB_NAMESPACE {
  16
  17 // Database with TTL support.
  18 //
  19 // USE-CASES:
  20 // This API should be used to open the db when key-values inserted are
  21 //  meant to be removed from the db in a non-strict 'ttl' amount of time
  22 //  Therefore, this guarantees that key-values inserted will remain in the
  23 //  db for >= ttl amount of time and the db will make efforts to remove the
  24 //  key-values as soon as possible after ttl seconds of their insertion.
  25 //
  26 // BEHAVIOUR:
  27 // TTL is accepted in seconds
  28 // (int32_t)Timestamp(creation) is suffixed to values in Put internally
  29 // Expired TTL values deleted in compaction only:(Timestamp+ttl<time_now)
  30 // Get/Iterator may return expired entries(compaction not run on them yet)
  31 // Different TTL may be used during different Opens
  32 // Example: Open1 at t=0 with ttl=4 and insert k1,k2, close at t=2
  33 //          Open2 at t=3 with ttl=5. Now k1,k2 should be deleted at t>=5
  34 // read_only=true opens in the usual read-only mode. Compactions will not be
  35 //  triggered(neither manual nor automatic), so no expired entries removed
  36 //
  37 // CONSTRAINTS:
  38 // Not specifying/passing or non-positive TTL behaves like TTL = infinity
  39 //
  40 // !!!WARNING!!!:
  41 // Calling DB::Open directly to re-open a db created by this API will get
  42 //  corrupt values(timestamp suffixed) and no ttl effect will be there
  43 //  during the second Open, so use this API consistently to open the db
  44 // Be careful when passing ttl with a small positive value because the
  45 //  whole database may be deleted in a small amount of time
  46
  47 class DBWithTTL : public StackableDB {
  48  public:
  49   virtual Status CreateColumnFamilyWithTtl(
  50       const ColumnFamilyOptions& options, const std::string& column_family_name,
  51       ColumnFamilyHandle** handle, int ttl) = 0;
  52
  53   static Status Open(const Options& options, const std::string& dbname,
  54                      DBWithTTL** dbptr, int32_t ttl = 0,
  55                      bool read_only = false);
  56
  57   static Status Open(const DBOptions& db_options, const std::string& dbname,
  58                      const std::vector<ColumnFamilyDescriptor>& column_families,
  59                      std::vector<ColumnFamilyHandle*>* handles,
  60                      DBWithTTL** dbptr, std::vector<int32_t> ttls,
  61                      bool read_only = false);
  62
  63   virtual void SetTtl(int32_t ttl) = 0;
  64
  65   virtual void SetTtl(ColumnFamilyHandle* h, int32_t ttl) = 0;
  66
  67  protected:
  68   explicit DBWithTTL(DB* db) : StackableDB(db) {}
  69 };
  70
  71 }  // namespace ROCKSDB_NAMESPACE
  72 #endif  // ROCKSDB_LITE