ceph/src/rocksdb/utilities/transactions/lock/lock_tracker.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
   8 #include <memory>
   9
  10 #include "rocksdb/rocksdb_namespace.h"
  11 #include "rocksdb/status.h"
  12 #include "rocksdb/types.h"
  13
  14 namespace ROCKSDB_NAMESPACE {
  15
  16 // Request for locking a single key.
  17 struct PointLockRequest {
  18   // The id of the key's column family.
  19   ColumnFamilyId column_family_id = 0;
  20   // The key to lock.
  21   std::string key;
  22   // The sequence number from which there is no concurrent update to key.
  23   SequenceNumber seq = 0;
  24   // Whether the lock is acquired only for read.
  25   bool read_only = false;
  26   // Whether the lock is in exclusive mode.
  27   bool exclusive = true;
  28 };
  29
  30 // Request for locking a range of keys.
  31 struct RangeLockRequest {
  32   // TODO
  33 };
  34
  35 struct PointLockStatus {
  36   // Whether the key is locked.
  37   bool locked = false;
  38   // Whether the key is locked in exclusive mode.
  39   bool exclusive = true;
  40   // The sequence number in the tracked PointLockRequest.
  41   SequenceNumber seq = 0;
  42 };
  43
  44 // Return status when calling LockTracker::Untrack.
  45 enum class UntrackStatus {
  46   // The lock is not tracked at all, so no lock to untrack.
  47   NOT_TRACKED,
  48   // The lock is untracked but not removed from the tracker.
  49   UNTRACKED,
  50   // The lock is removed from the tracker.
  51   REMOVED,
  52 };
  53
  54 // Tracks the lock requests.
  55 // In PessimisticTransaction, it tracks the locks acquired through LockMgr;
  56 // In OptimisticTransaction, since there is no LockMgr, it tracks the lock
  57 // intention. Not thread-safe.
  58 class LockTracker {
  59  public:
  60   virtual ~LockTracker() {}
  61
  62   // Whether supports locking a specific key.
  63   virtual bool IsPointLockSupported() const = 0;
  64
  65   // Whether supports locking a range of keys.
  66   virtual bool IsRangeLockSupported() const = 0;
  67
  68   // Tracks the acquirement of a lock on key.
  69   //
  70   // If this method is not supported, leave it as a no-op.
  71   virtual void Track(const PointLockRequest& /*lock_request*/) = 0;
  72
  73   // Untracks the lock on a key.
  74   // seq and exclusive in lock_request are not used.
  75   //
  76   // If this method is not supported, leave it as a no-op and
  77   // returns NOT_TRACKED.
  78   virtual UntrackStatus Untrack(const PointLockRequest& /*lock_request*/) = 0;
  79
  80   // Counterpart of Track(const PointLockRequest&) for RangeLockRequest.
  81   virtual void Track(const RangeLockRequest& /*lock_request*/) = 0;
  82
  83   // Counterpart of Untrack(const PointLockRequest&) for RangeLockRequest.
  84   virtual UntrackStatus Untrack(const RangeLockRequest& /*lock_request*/) = 0;
  85
  86   // Merges lock requests tracked in the specified tracker into the current
  87   // tracker.
  88   //
  89   // E.g. for point lock, if a key in tracker is not yet tracked,
  90   // track this new key; otherwise, merge the tracked information of the key
  91   // such as lock's exclusiveness, read/write statistics.
  92   //
  93   // If this method is not supported, leave it as a no-op.
  94   //
  95   // REQUIRED: the specified tracker must be of the same concrete class type as
  96   // the current tracker.
  97   virtual void Merge(const LockTracker& /*tracker*/) = 0;
  98
  99   // This is a reverse operation of Merge.
 100   //
 101   // E.g. for point lock, if a key exists in both current and the sepcified
 102   // tracker, then subtract the information (such as read/write statistics) of
 103   // the key in the specified tracker from the current tracker.
 104   //
 105   // If this method is not supported, leave it as a no-op.
 106   //
 107   // REQUIRED:
 108   // The specified tracker must be of the same concrete class type as
 109   // the current tracker.
 110   // The tracked locks in the specified tracker must be a subset of those
 111   // tracked by the current tracker.
 112   virtual void Subtract(const LockTracker& /*tracker*/) = 0;
 113
 114   // Clears all tracked locks.
 115   virtual void Clear() = 0;
 116
 117   // Gets the new locks (excluding the locks that have been tracked before the
 118   // save point) tracked since the specified save point, the result is stored
 119   // in an internally constructed LockTracker and returned.
 120   //
 121   // save_point_tracker is the tracker used by a SavePoint to track locks
 122   // tracked after creating the SavePoint.
 123   //
 124   // The implementation should document whether point lock, or range lock, or
 125   // both are considered in this method.
 126   // If this method is not supported, returns nullptr.
 127   //
 128   // REQUIRED:
 129   // The save_point_tracker must be of the same concrete class type as the
 130   // current tracker.
 131   // The tracked locks in the specified tracker must be a subset of those
 132   // tracked by the current tracker.
 133   virtual LockTracker* GetTrackedLocksSinceSavePoint(
 134       const LockTracker& /*save_point_tracker*/) const = 0;
 135
 136   // Gets lock related information of the key.
 137   //
 138   // If point lock is not supported, always returns LockStatus with
 139   // locked=false.
 140   virtual PointLockStatus GetPointLockStatus(
 141       ColumnFamilyId /*column_family_id*/,
 142       const std::string& /*key*/) const = 0;
 143
 144   // Gets number of tracked point locks.
 145   //
 146   // If point lock is not supported, always returns 0.
 147   virtual uint64_t GetNumPointLocks() const = 0;
 148
 149   class ColumnFamilyIterator {
 150    public:
 151     virtual ~ColumnFamilyIterator() {}
 152
 153     // Whether there are remaining column families.
 154     virtual bool HasNext() const = 0;
 155
 156     // Gets next column family id.
 157     //
 158     // If HasNext is false, calling this method has undefined behavior.
 159     virtual ColumnFamilyId Next() = 0;
 160   };
 161
 162   // Gets an iterator for column families.
 163   //
 164   // Returned iterator must not be nullptr.
 165   // If there is no column family to iterate,
 166   // returns an empty non-null iterator.
 167   // Caller owns the returned pointer.
 168   virtual ColumnFamilyIterator* GetColumnFamilyIterator() const = 0;
 169
 170   class KeyIterator {
 171    public:
 172     virtual ~KeyIterator() {}
 173
 174     // Whether there are remaining keys.
 175     virtual bool HasNext() const = 0;
 176
 177     // Gets the next key.
 178     //
 179     // If HasNext is false, calling this method has undefined behavior.
 180     virtual const std::string& Next() = 0;
 181   };
 182
 183   // Gets an iterator for keys with tracked point locks in the column family.
 184   //
 185   // The column family must exist.
 186   // Returned iterator must not be nullptr.
 187   // Caller owns the returned pointer.
 188   virtual KeyIterator* GetKeyIterator(
 189       ColumnFamilyId /*column_family_id*/) const = 0;
 190 };
 191
 192 // LockTracker should always be constructed through this factory.
 193 // Each LockManager owns a LockTrackerFactory.
 194 class LockTrackerFactory {
 195  public:
 196   // Caller owns the returned pointer.
 197   virtual LockTracker* Create() const = 0;
 198   virtual ~LockTrackerFactory() {}
 199 };
 200
 201 }  // namespace ROCKSDB_NAMESPACE