src/store/Controller.h

   1 /*
   2  * Copyright (C) 1996-2018 The Squid Software Foundation and contributors
   3  *
   4  * Squid software is distributed under GPLv2+ license and includes
   5  * contributions from numerous individuals and organizations.
   6  * Please see the COPYING and CONTRIBUTORS files for details.
   7  */
   8
   9 #ifndef SQUID_STORE_CONTROLLER_H
  10 #define SQUID_STORE_CONTROLLER_H
  11
  12 #include "store/Storage.h"
  13
  14 class MemObject;
  15 class RequestFlags;
  16 class HttpRequestMethod;
  17
  18 namespace Store {
  19
  20 /// Public Store interface. Coordinates the work of memory/disk/transient stores
  21 /// and hides their individual existence/differences from the callers.
  22 class Controller: public Storage
  23 {
  24 public:
  25     Controller();
  26     virtual ~Controller() override;
  27
  28     /* Storage API */
  29     virtual void create() override;
  30     virtual void init() override;
  31     virtual uint64_t maxSize() const override;
  32     virtual uint64_t minSize() const override;
  33     virtual uint64_t currentSize() const override;
  34     virtual uint64_t currentCount() const override;
  35     virtual int64_t maxObjectSize() const override;
  36     virtual void getStats(StoreInfoStats &stats) const override;
  37     virtual void stat(StoreEntry &) const override;
  38     virtual void sync() override;
  39     virtual void maintain() override;
  40     virtual void evictCached(StoreEntry &) override;
  41     virtual void evictIfFound(const cache_key *) override;
  42     virtual int callback() override;
  43     virtual bool smpAware() const override;
  44
  45     /// \returns a locally indexed and SMP-tracked matching StoreEntry (or nil)
  46     /// Slower than peek() but does not restrict StoreEntry use and storage.
  47     /// Counts as an entry reference from the removal policy p.o.v.
  48     StoreEntry *find(const cache_key *);
  49
  50     /// \returns a matching StoreEntry not suitable for long-term use (or nil)
  51     /// Faster than find() but the returned entry may not receive updates, may
  52     /// lack information from some of the Stores, and should not be updated
  53     /// except that purging peek()ed entries is supported.
  54     /// Does not count as an entry reference from the removal policy p.o.v.
  55     StoreEntry *peek(const cache_key *);
  56
  57     /// \returns matching StoreEntry associated with local ICP/HTCP transaction
  58     /// Warning: The returned StoreEntry is not synced and may be marked for
  59     /// deletion. It can only be used for extracting transaction callback details.
  60     /// New code should be designed to avoid this deprecated API.
  61     StoreEntry *findCallbackXXX(const cache_key *);
  62
  63     /// Whether a transient entry with the given public key exists and (but) was
  64     /// marked for removal some time ago; get(key) returns nil in such cases.
  65     bool markedForDeletion(const cache_key *key) const;
  66
  67     /// markedForDeletion() with no readers
  68     /// this is one method because the two conditions must be checked in the right order
  69     bool markedForDeletionAndAbandoned(const StoreEntry &) const;
  70
  71     /// whether there is a disk entry with e.key
  72     bool hasReadableDiskEntry(const StoreEntry &) const;
  73
  74     /// Additional unknown-size entry bytes required by Store in order to
  75     /// reduce the risk of selecting the wrong disk cache for the growing entry.
  76     int64_t accumulateMore(StoreEntry &) const;
  77
  78     /// slowly calculate (and cache) hi/lo watermarks and similar limits
  79     void updateLimits();
  80
  81     /// called when the entry is no longer needed by any transaction
  82     void handleIdleEntry(StoreEntry &);
  83
  84     /// Evict memory cache entries to free at least `spaceRequired` bytes.
  85     /// Should be called via storeGetMemSpace().
  86     /// Unreliable: Fails if enough victims cannot be found fast enough.
  87     void freeMemorySpace(const int spaceRequired);
  88
  89     /// called to get rid of no longer needed entry data in RAM, if any
  90     void memoryOut(StoreEntry &, const bool preserveSwappable);
  91
  92     /// update old entry metadata and HTTP headers using a newer entry
  93     void updateOnNotModified(StoreEntry *old, const StoreEntry &newer);
  94
  95     /// tries to make the entry available for collapsing future requests
  96     bool allowCollapsing(StoreEntry *, const RequestFlags &, const HttpRequestMethod &);
  97
  98     /// register a being-read StoreEntry (to optimize concurrent cache reads
  99     /// and to receive remote DELETE events)
 100     void addReading(StoreEntry *, const cache_key *);
 101
 102     /// register a being-written StoreEntry (to support concurrent cache reads
 103     /// and to receive remote DELETE events)
 104     void addWriting(StoreEntry *, const cache_key *);
 105
 106     /// whether the entry is in "reading from Transients" I/O state
 107     bool transientsReader(const StoreEntry &) const;
 108
 109     /// whether the entry is in "writing to Transients" I/O state
 110     bool transientsWriter(const StoreEntry &) const;
 111
 112     /// marks the entry completed for collapsed requests
 113     void transientsCompleteWriting(StoreEntry &);
 114
 115     /// Update local intransit entry after changes made by appending worker.
 116     void syncCollapsed(const sfileno);
 117
 118     /// stop any current (and prevent any future) SMP sharing of the given entry
 119     void stopSharing(StoreEntry &);
 120
 121     /// number of the transient entry readers some time ago
 122     int transientReaders(const StoreEntry &) const;
 123
 124     /// disassociates the entry from the intransit table
 125     void transientsDisconnect(StoreEntry &);
 126
 127     /// removes collapsing requirement (for future hits)
 128     void transientsClearCollapsingRequirement(StoreEntry &e);
 129
 130     /// disassociates the entry from the memory cache, preserving cached data
 131     void memoryDisconnect(StoreEntry &);
 132
 133     /// \returns an iterator for all Store entries
 134     StoreSearch *search();
 135
 136     /// the number of cache_dirs being rebuilt; TODO: move to Disks::Rebuilding
 137     static int store_dirs_rebuilding;
 138
 139 private:
 140     bool memoryCacheHasSpaceFor(const int pagesRequired) const;
 141
 142     void referenceBusy(StoreEntry &e);
 143     bool dereferenceIdle(StoreEntry &, bool wantsLocalMemory);
 144
 145     void allowSharing(StoreEntry &, const cache_key *);
 146     StoreEntry *peekAtLocal(const cache_key *);
 147
 148     void memoryEvictCached(StoreEntry &);
 149     void transientsUnlinkByKeyIfFound(const cache_key *);
 150     bool keepForLocalMemoryCache(StoreEntry &e) const;
 151     bool anchorToCache(StoreEntry &e, bool &inSync);
 152     void checkTransients(const StoreEntry &) const;
 153
 154     Disks *swapDir; ///< summary view of all disk caches
 155     Memory *memStore; ///< memory cache
 156
 157     /// A shared table of public store entries that do not know whether they
 158     /// will belong to a memory cache, a disk cache, or will be uncachable
 159     /// when the response header comes. Used for SMP collapsed forwarding.
 160     Transients *transients;
 161
 162     /// Hack: Relays page shortage from freeMemorySpace() to handleIdleEntry().
 163     int memoryPagesDebt_ = 0;
 164 };
 165
 166 /// safely access controller singleton
 167 extern Controller &Root();
 168
 169 /// initialize the storage module; a custom root is used by unit tests only
 170 extern void Init(Controller *root = nullptr);
 171
 172 /// undo Init()
 173 extern void FreeMemory();
 174
 175 } // namespace Store
 176
 177 #endif /* SQUID_STORE_CONTROLLER_H */
 178