src/Store.h

   1 /*
   2  * Copyright (C) 1996-2017 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_H
  10 #define SQUID_STORE_H
  11
  12 #include "base/Packable.h"
  13 #include "base/RefCount.h"
  14 #include "comm/forward.h"
  15 #include "CommRead.h"
  16 #include "hash.h"
  17 #include "http/forward.h"
  18 #include "http/RequestMethod.h"
  19 #include "HttpReply.h"
  20 #include "MemObject.h"
  21 #include "Range.h"
  22 #include "RemovalPolicy.h"
  23 #include "store/Controller.h"
  24 #include "store/forward.h"
  25 #include "store_key_md5.h"
  26 #include "StoreIOBuffer.h"
  27 #include "StoreStats.h"
  28
  29 #if USE_SQUID_ESI
  30 #include "esi/Element.h"
  31 #endif
  32
  33 #include <ostream>
  34
  35 class AsyncCall;
  36 class HttpRequest;
  37 class RequestFlags;
  38
  39 extern StoreIoStats store_io_stats;
  40
  41 class StoreEntry : public hash_link, public Packable
  42 {
  43
  44 public:
  45     static DeferredRead::DeferrableRead DeferReader;
  46     bool checkDeferRead(int fd) const;
  47
  48     virtual const char *getMD5Text() const;
  49     StoreEntry();
  50     virtual ~StoreEntry();
  51
  52     virtual HttpReply const *getReply() const;
  53     virtual void write (StoreIOBuffer);
  54
  55     /** Check if the Store entry is emtpty
  56      * \retval true   Store contains 0 bytes of data.
  57      * \retval false  Store contains 1 or more bytes of data.
  58      * \retval false  Store contains negative content !!!!!!
  59      */
  60     virtual bool isEmpty() const {
  61         assert (mem_obj);
  62         return mem_obj->endOffset() == 0;
  63     }
  64     virtual bool isAccepting() const;
  65     virtual size_t bytesWanted(Range<size_t> const aRange, bool ignoreDelayPool = false) const;
  66     /// flags [truncated or too big] entry with ENTRY_BAD_LENGTH and releases it
  67     void lengthWentBad(const char *reason);
  68     virtual void complete();
  69     virtual store_client_t storeClientType() const;
  70     virtual char const *getSerialisedMetaData();
  71     /// Store a prepared error response. MemObject locks the reply object.
  72     void storeErrorResponse(HttpReply *reply);
  73     void replaceHttpReply(HttpReply *, bool andStartWriting = true);
  74     void startWriting(); ///< pack and write reply headers and, maybe, body
  75     /// whether we may start writing to disk (now or in the future)
  76     virtual bool mayStartSwapOut();
  77     virtual void trimMemory(const bool preserveSwappable);
  78
  79     // called when a decision to cache in memory has been made
  80     void memOutDecision(const bool willCacheInRam);
  81     // called when a decision to cache on disk has been made
  82     void swapOutDecision(const MemObject::SwapOut::Decision &decision);
  83
  84     void abort();
  85     void makePublic(const KeyScope keyScope = ksDefault);
  86     void makePrivate();
  87     void setPublicKey(const KeyScope keyScope = ksDefault);
  88     /// Resets existing public key to a public key with default scope,
  89     /// releasing the old default-scope entry (if any).
  90     /// Does nothing if the existing public key already has default scope.
  91     void clearPublicKeyScope();
  92     void setPrivateKey();
  93     void expireNow();
  94     void releaseRequest();
  95     void negativeCache();
  96     void cacheNegatively();     /** \todo argh, why both? */
  97     void invokeHandlers();
  98     void purgeMem();
  99     void cacheInMemory(); ///< start or continue storing in memory cache
 100     void swapOut();
 101     /// whether we are in the process of writing this entry to disk
 102     bool swappingOut() const { return swap_status == SWAPOUT_WRITING; }
 103     void swapOutFileClose(int how);
 104     const char *url() const;
 105     /// Satisfies cachability requirements shared among disk and RAM caches.
 106     /// Encapsulates common checks of mayStartSwapOut() and memoryCachable().
 107     /// TODO: Rename and make private so only those two methods can call this.
 108     bool checkCachable();
 109     int checkNegativeHit() const;
 110     int locked() const;
 111     int validToSend() const;
 112     bool memoryCachable(); ///< checkCachable() and can be cached in memory
 113
 114     /// if needed, initialize mem_obj member w/o URI-related information
 115     MemObject *makeMemObject();
 116
 117     /// initialize mem_obj member (if needed) and supply URI-related info
 118     void createMemObject(const char *storeId, const char *logUri, const HttpRequestMethod &aMethod);
 119
 120     void dump(int debug_lvl) const;
 121     void hashDelete();
 122     void hashInsert(const cache_key *);
 123     void registerAbort(STABH * cb, void *);
 124     void reset();
 125     void setMemStatus(mem_status_t);
 126     bool timestampsSet();
 127     void unregisterAbort();
 128     void destroyMemObject();
 129     int checkTooSmall();
 130
 131     void delayAwareRead(const Comm::ConnectionPointer &conn, char *buf, int len, AsyncCall::Pointer callback);
 132
 133     void setNoDelay (bool const);
 134     void lastModified(const time_t when) { lastModified_ = when; }
 135     /// \returns entry's 'effective' modification time
 136     time_t lastModified() const {
 137         // may still return -1 if timestamp is not set
 138         return lastModified_ < 0 ? timestamp : lastModified_;
 139     }
 140     /// \returns a formatted string with entry's timestamps
 141     const char *describeTimestamps() const;
 142     // TODO: consider removing currently unsupported imslen parameter
 143     bool modifiedSince(const time_t ims, const int imslen = -1) const;
 144     /// has ETag matching at least one of the If-Match etags
 145     bool hasIfMatchEtag(const HttpRequest &request) const;
 146     /// has ETag matching at least one of the If-None-Match etags
 147     bool hasIfNoneMatchEtag(const HttpRequest &request) const;
 148     /// whether this entry has an ETag; if yes, puts ETag value into parameter
 149     bool hasEtag(ETag &etag) const;
 150
 151     /// the disk this entry is [being] cached on; asserts for entries w/o a disk
 152     Store::Disk &disk() const;
 153
 154     MemObject *mem_obj;
 155     RemovalPolicyNode repl;
 156     /* START OF ON-DISK STORE_META_STD TLV field */
 157     time_t timestamp;
 158     time_t lastref;
 159     time_t expires;
 160 private:
 161     time_t lastModified_; ///< received Last-Modified value or -1; use lastModified()
 162 public:
 163     uint64_t swap_file_sz;
 164     uint16_t refcount;
 165     uint16_t flags;
 166     /* END OF ON-DISK STORE_META_STD */
 167
 168     /// unique ID inside a cache_dir for swapped out entries; -1 for others
 169     sfileno swap_filen:25; // keep in sync with SwapFilenMax
 170
 171     sdirno swap_dirn:7;
 172
 173     mem_status_t mem_status:3;
 174
 175     ping_status_t ping_status:3;
 176
 177     store_status_t store_status:3;
 178
 179     swap_status_t swap_status:3;
 180
 181 public:
 182     static size_t inUseCount();
 183     static void getPublicByRequestMethod(StoreClient * aClient, HttpRequest * request, const HttpRequestMethod& method);
 184     static void getPublicByRequest(StoreClient * aClient, HttpRequest * request);
 185     static void getPublic(StoreClient * aClient, const char *uri, const HttpRequestMethod& method);
 186
 187     virtual bool isNull() {
 188         return false;
 189     };
 190
 191     void *operator new(size_t byteCount);
 192     void operator delete(void *address);
 193     void setReleaseFlag();
 194 #if USE_SQUID_ESI
 195
 196     ESIElement::Pointer cachedESITree;
 197 #endif
 198     virtual int64_t objectLen() const;
 199     virtual int64_t contentLen() const;
 200
 201     /// claim shared ownership of this entry (for use in a given context)
 202     /// matching lock() and unlock() contexts eases leak triage but is optional
 203     void lock(const char *context);
 204
 205     /// disclaim shared ownership; may remove entry from store and delete it
 206     /// returns remaning lock level (zero for unlocked and possibly gone entry)
 207     int unlock(const char *context);
 208
 209     /// returns a local concurrent use counter, for debugging
 210     int locks() const { return static_cast<int>(lock_count); }
 211
 212     /// update last reference timestamp and related Store metadata
 213     void touch();
 214
 215     virtual void release();
 216
 217 #if USE_ADAPTATION
 218     /// call back producer when more buffer space is available
 219     void deferProducer(const AsyncCall::Pointer &producer);
 220     /// calls back producer registered with deferProducer
 221     void kickProducer();
 222 #endif
 223
 224     /* Packable API */
 225     virtual void append(char const *, int);
 226     virtual void vappendf(const char *, va_list);
 227     virtual void buffer();
 228     virtual void flush();
 229
 230 protected:
 231     void transientsAbandonmentCheck();
 232
 233 private:
 234     bool checkTooBig() const;
 235     void forcePublicKey(const cache_key *newkey);
 236     void adjustVary();
 237     const cache_key *calcPublicKey(const KeyScope keyScope);
 238
 239     static MemAllocator *pool;
 240
 241     unsigned short lock_count;      /* Assume < 65536! */
 242
 243 #if USE_ADAPTATION
 244     /// producer callback registered with deferProducer
 245     AsyncCall::Pointer deferredProducer;
 246 #endif
 247
 248     bool validLength() const;
 249     bool hasOneOfEtags(const String &reqETags, const bool allowWeakMatch) const;
 250 };
 251
 252 std::ostream &operator <<(std::ostream &os, const StoreEntry &e);
 253
 254 /// \ingroup StoreAPI
 255 class NullStoreEntry:public StoreEntry
 256 {
 257
 258 public:
 259     static NullStoreEntry *getInstance();
 260     bool isNull() {
 261         return true;
 262     }
 263
 264     const char *getMD5Text() const;
 265     HttpReply const *getReply() const { return NULL; }
 266     void write (StoreIOBuffer) {}
 267
 268     bool isEmpty () const {return true;}
 269
 270     virtual size_t bytesWanted(Range<size_t> const aRange, bool) const { return aRange.end; }
 271
 272     void operator delete(void *address);
 273     void complete() {}
 274
 275 private:
 276     store_client_t storeClientType() const {return STORE_MEM_CLIENT;}
 277
 278     char const *getSerialisedMetaData();
 279     virtual bool mayStartSwapOut() { return false; }
 280
 281     void trimMemory(const bool) {}
 282
 283     static NullStoreEntry _instance;
 284 };
 285
 286 /// \ingroup StoreAPI
 287 typedef void (*STOREGETCLIENT) (StoreEntry *, void *cbdata);
 288
 289 namespace Store {
 290 void Stats(StoreEntry *output);
 291 void Maintain(void *unused);
 292 };
 293
 294 /// \ingroup StoreAPI
 295 size_t storeEntryInUse();
 296
 297 /// \ingroup StoreAPI
 298 const char *storeEntryFlags(const StoreEntry *);
 299
 300 /// \ingroup StoreAPI
 301 void storeEntryReplaceObject(StoreEntry *, HttpReply *);
 302
 303 /// \ingroup StoreAPI
 304 StoreEntry *storeGetPublic(const char *uri, const HttpRequestMethod& method);
 305
 306 /// \ingroup StoreAPI
 307 StoreEntry *storeGetPublicByRequest(HttpRequest * request, const KeyScope keyScope = ksDefault);
 308
 309 /// \ingroup StoreAPI
 310 StoreEntry *storeGetPublicByRequestMethod(HttpRequest * request, const HttpRequestMethod& method, const KeyScope keyScope = ksDefault);
 311
 312 /// \ingroup StoreAPI
 313 /// Like storeCreatePureEntry(), but also locks the entry and sets entry key.
 314 StoreEntry *storeCreateEntry(const char *, const char *, const RequestFlags &, const HttpRequestMethod&);
 315
 316 /// \ingroup StoreAPI
 317 /// Creates a new StoreEntry with mem_obj and sets initial flags/states.
 318 StoreEntry *storeCreatePureEntry(const char *storeId, const char *logUrl, const RequestFlags &, const HttpRequestMethod&);
 319
 320 /// \ingroup StoreAPI
 321 void storeInit(void);
 322
 323 /// \ingroup StoreAPI
 324 void storeConfigure(void);
 325
 326 /// \ingroup StoreAPI
 327 void storeFreeMemory(void);
 328
 329 /// \ingroup StoreAPI
 330 int expiresMoreThan(time_t, time_t);
 331
 332 /// \ingroup StoreAPI
 333 void storeAppendPrintf(StoreEntry *, const char *,...) PRINTF_FORMAT_ARG2;
 334
 335 /// \ingroup StoreAPI
 336 void storeAppendVPrintf(StoreEntry *, const char *, va_list ap);
 337
 338 /// \ingroup StoreAPI
 339 int storeTooManyDiskFilesOpen(void);
 340
 341 /// \ingroup StoreAPI
 342 void storeHeapPositionUpdate(StoreEntry *, SwapDir *);
 343
 344 /// \ingroup StoreAPI
 345 void storeSwapFileNumberSet(StoreEntry * e, sfileno filn);
 346
 347 /// \ingroup StoreAPI
 348 void storeFsInit(void);
 349
 350 /// \ingroup StoreAPI
 351 void storeFsDone(void);
 352
 353 /// \ingroup StoreAPI
 354 void storeReplAdd(const char *, REMOVALPOLICYCREATE *);
 355
 356 /// \ingroup StoreAPI
 357 extern FREE destroyStoreEntry;
 358
 359 /// \ingroup StoreAPI
 360 void storeGetMemSpace(int size);
 361
 362 #endif /* SQUID_STORE_H */
 363