Store.h
Go to the documentation of this file.
1/*
2 * Copyright (C) 1996-2023 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
13#include "base/Packable.h"
14#include "base/Range.h"
15#include "base/RefCount.h"
16#include "comm/forward.h"
17#include "hash.h"
18#include "http/forward.h"
19#include "http/RequestMethod.h"
20#include "HttpReply.h"
21#include "MemObject.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
35class AsyncCall;
36class HttpRequest;
37class RequestFlags;
38
40
41class StoreEntry : public hash_link, public Packable
42{
43
44public:
45 bool checkDeferRead(int fd) const;
46
47 const char *getMD5Text() const;
48 StoreEntry();
49 ~StoreEntry() override;
50
52 const MemObject &mem() const { assert(mem_obj); return *mem_obj; }
53
57 const HttpReply *hasFreshestReply() const { return mem_obj ? &mem_obj->freshestReply() : nullptr; }
58
59 void write(StoreIOBuffer);
60
66 bool isEmpty() const { return mem().endOffset() == 0; }
67 bool isAccepting() const;
68 size_t bytesWanted(Range<size_t> const aRange, bool ignoreDelayPool = false) const;
69
72 void completeSuccessfully(const char *whyWeAreSureWeStoredTheWholeReply);
73
76 void completeTruncated(const char *whyWeConsiderTheReplyTruncated);
77
79 void complete();
80
83 const char *getSerialisedMetaData(size_t &length) const;
85 void storeErrorResponse(HttpReply *reply);
86 void replaceHttpReply(const HttpReplyPointer &, const bool andStartWriting = true);
87 void startWriting();
89 bool mayStartSwapOut();
90 void trimMemory(const bool preserveSwappable);
91
92 // called when a decision to cache in memory has been made
93 void memOutDecision(const bool willCacheInRam);
94 // called when a decision to cache on disk has been made
97 void storeWriterDone();
98
99 void abort();
100 bool makePublic(const KeyScope keyScope = ksDefault);
101 void makePrivate(const bool shareable);
105 void clearPrivate();
106 bool setPublicKey(const KeyScope keyScope = ksDefault);
110 void clearPublicKeyScope();
111
113 const cache_key *publicKey() const {
114 return (!EBIT_TEST(flags, KEY_PRIVATE)) ?
115 reinterpret_cast<const cache_key*>(key): // may be nil
116 nullptr;
117 }
118
122 void setPrivateKey(const bool shareable, const bool permanent);
123
124 void expireNow();
127 void releaseRequest(const bool shareable = false);
128 void negativeCache();
129 bool cacheNegatively(); // TODO: why both negativeCache() and cacheNegatively() ?
130 void invokeHandlers();
132 void swapOut();
134 bool swappingOut() const { return swap_status == SWAPOUT_WRITING; }
136 bool swappedOut() const { return swap_status == SWAPOUT_DONE; }
138 bool swapoutFailed() const { return swap_status == SWAPOUT_FAILED; }
139 void swapOutFileClose(int how);
140 const char *url() const;
144 bool checkCachable();
145 int checkNegativeHit() const;
146 int locked() const { return lock_count; }
147 int validToSend() const;
148 bool memoryCachable();
149
152 void createMemObject();
153
155 void createMemObject(const char *storeId, const char *logUri, const HttpRequestMethod &aMethod);
156
158 void ensureMemObject(const char *storeId, const char *logUri, const HttpRequestMethod &aMethod);
159
160 void dump(int debug_lvl) const;
161 void hashDelete();
162 void hashInsert(const cache_key *);
165 void reset();
167 bool timestampsSet();
171 void unregisterAbortCallback(const char *reason);
172 void destroyMemObject();
173 int checkTooSmall();
174
175 void setNoDelay (bool const);
176 void lastModified(const time_t when) { lastModified_ = when; }
178 time_t lastModified() const {
179 // may still return -1 if timestamp is not set
181 }
183 const char *describeTimestamps() const;
184 // TODO: consider removing currently unsupported imslen parameter
185 bool modifiedSince(const time_t ims, const int imslen = -1) const;
187 bool hasIfMatchEtag(const HttpRequest &request) const;
189 bool hasIfNoneMatchEtag(const HttpRequest &request) const;
191 bool hasEtag(ETag &etag) const;
192
196 bool updateOnNotModified(const StoreEntry &e304);
197
199 Store::Disk &disk() const;
202 bool hasDisk(const sdirno dirn = -1, const sfileno filen = -1) const;
205 void attachToDisk(const sdirno, const sfileno, const swap_status_t);
208 void detachFromDisk();
209
211 bool hasTransients() const { return mem_obj && mem_obj->xitTable.index >= 0; }
213 bool hasMemStore() const { return mem_obj && mem_obj->memCache.index >= 0; }
214
217
219 void setCollapsingRequirement(const bool required);
220
223 /* START OF ON-DISK STORE_META_STD TLV field */
224 time_t timestamp;
225 time_t lastref;
226 time_t expires;
227private:
229public:
230 uint64_t swap_file_sz;
231 uint16_t refcount;
232 uint16_t flags;
233 /* END OF ON-DISK STORE_META_STD */
234
236 sfileno swap_filen:25; // keep in sync with SwapFilenMax
237
239
241
243
245
247
248public:
249 static size_t inUseCount();
250
251 void *operator new(size_t byteCount);
252 void operator delete(void *address);
253#if USE_SQUID_ESI
254
256#endif
257 int64_t objectLen() const { return mem().object_sz; }
258 int64_t contentLen() const { return objectLen() - mem().baseReply().hdr_sz; }
259
262 void lock(const char *context);
263
266 int unlock(const char *context);
267
269 int locks() const { return static_cast<int>(lock_count); }
270
272 void touch();
273
278 void release(const bool shareable = false);
279
284 void abandon(const char *context) { if (!locked()) doAbandon(context); }
285
288 bool mayStartHitting() const {
290 }
291
292#if USE_ADAPTATION
294 void deferProducer(const AsyncCall::Pointer &producer);
296 void kickProducer();
297#endif
298
299 /* Packable API */
300 void append(char const *, int) override;
301 void vappendf(const char *, va_list) override;
302 void buffer() override;
303 void flush() override;
304
305protected:
307
310 void checkDisk() const;
311
312private:
313 void doAbandon(const char *context);
314 bool checkTooBig() const;
315 void forcePublicKey(const cache_key *newkey);
317 const cache_key *calcPublicKey(const KeyScope keyScope);
318
320 void lengthWentBad(const char *reason);
321
323
324 unsigned short lock_count; /* Assume < 65536! */
325
332
333#if USE_ADAPTATION
336#endif
337
338 bool validLength() const;
339 bool hasOneOfEtags(const String &reqETags, const bool allowWeakMatch) const;
340
341 friend std::ostream &operator <<(std::ostream &os, const StoreEntry &e);
342};
343
344std::ostream &operator <<(std::ostream &os, const StoreEntry &e);
345
347typedef void (*STOREGETCLIENT) (StoreEntry *, void *cbdata);
348
349namespace Store {
350
354public:
357 EntryGuard(Entry *entry, const char *context):
358 entry_(entry), context_(context) {
359 assert(!entry_ || entry_->locked());
360 }
361
363 if (entry_) {
364 // something went wrong -- the caller did not unlockAndReset() us
365 onException();
366 }
367 }
368
369 EntryGuard(EntryGuard &&) = delete; // no copying or moving (for now)
370
374 return entry_;
375 }
376
380 void unlockAndReset(const char *resetContext = nullptr) {
381 if (entry_) {
382 entry_->unlock(resetContext ? resetContext : context_);
383 entry_ = nullptr;
384 }
385 }
386
387private:
388 void onException() noexcept;
389
391 const char *context_;
392};
393
394void Stats(StoreEntry *output);
395void Maintain(void *unused);
396}; // namespace Store
397
400
402const char *storeEntryFlags(const StoreEntry *);
403
406
408StoreEntry *storeGetPublic(const char *uri, const HttpRequestMethod& method);
409
412
415
418StoreEntry *storeCreateEntry(const char *, const char *, const RequestFlags &, const HttpRequestMethod&);
419
422StoreEntry *storeCreatePureEntry(const char *storeId, const char *logUrl, const HttpRequestMethod&);
423
425void storeInit(void);
426
428void storeConfigure(void);
429
431int expiresMoreThan(time_t, time_t);
432
434void storeAppendPrintf(StoreEntry *, const char *,...) PRINTF_FORMAT_ARG2;
435
437void storeAppendVPrintf(StoreEntry *, const char *, va_list ap);
438
441
444
447
449void storeFsInit(void);
450
452void storeFsDone(void);
453
455void storeReplAdd(const char *, REMOVALPOLICYCREATE *);
456
462
464void storeGetMemSpace(int size);
465
466#endif /* SQUID_STORE_H */
467
int size
Definition: ModDevPoll.cc:75
RemovalPolicy * REMOVALPOLICYCREATE(wordlist *args)
Definition: RemovalPolicy.h:80
int expiresMoreThan(time_t, time_t)
Definition: store.cc:1324
void storeHeapPositionUpdate(StoreEntry *, SwapDir *)
void storeEntryReplaceObject(StoreEntry *, HttpReply *)
void storeGetMemSpace(int size)
Definition: store.cc:1107
StoreIoStats store_io_stats
Definition: store_io.cc:16
void storeConfigure(void)
Definition: store.cc:1256
int storeTooManyDiskFilesOpen(void)
Definition: store.cc:875
void storeSwapFileNumberSet(StoreEntry *e, sfileno filn)
void storeInit(void)
Definition: store.cc:1243
void storeFsDone(void)
void(* STOREGETCLIENT)(StoreEntry *, void *cbdata)
Definition: Store.h:347
StoreEntry * storeGetPublicByRequestMethod(HttpRequest *request, const HttpRequestMethod &method, const KeyScope keyScope=ksDefault)
Definition: store.cc:496
size_t storeEntryInUse()
std::ostream & operator<<(std::ostream &os, const StoreEntry &e)
Definition: store.cc:2031
StoreEntry * storeGetPublic(const char *uri, const HttpRequestMethod &method)
Definition: store.cc:490
StoreEntry * storeGetPublicByRequest(HttpRequest *request, const KeyScope keyScope=ksDefault)
Definition: store.cc:502
StoreEntry * storeCreatePureEntry(const char *storeId, const char *logUrl, const HttpRequestMethod &)
Definition: store.cc:727
void storeReplAdd(const char *, REMOVALPOLICYCREATE *)
Definition: store.cc:1631
const char * storeEntryFlags(const StoreEntry *)
Definition: stat.cc:253
FREE destroyStoreEntry
void storeFsInit(void)
Definition: store.cc:1622
void storeAppendVPrintf(StoreEntry *, const char *, va_list ap)
Definition: store.cc:851
StoreEntry * storeCreateEntry(const char *, const char *, const RequestFlags &, const HttpRequestMethod &)
Definition: store.cc:745
void storeAppendPrintf(StoreEntry *, const char *,...) PRINTF_FORMAT_ARG2
Definition: store.cc:841
#define assert(EX)
Definition: assert.h:17
Definition: ETag.h:18
int hdr_sz
Definition: Message.h:81
int32_t index
entry position inside the memory cache
Definition: MemObject.h:205
Decision
Decision states for StoreEntry::swapoutPossible() and related code.
Definition: MemObject.h:165
int32_t index
entry position inside the in-transit table
Definition: MemObject.h:196
XitTable xitTable
current [shared] memory caching state for the entry
Definition: MemObject.h:199
const HttpReply & freshestReply() const
Definition: MemObject.h:68
MemCache memCache
current [shared] memory caching state for the entry
Definition: MemObject.h:210
int64_t endOffset() const
Definition: MemObject.cc:214
const HttpReply & baseReply() const
Definition: MemObject.h:60
int64_t object_sz
Definition: MemObject.h:222
Definition: Range.h:19
void storeWritingCheckpoint()
Definition: store.cc:1747
int locks() const
returns a local concurrent use counter, for debugging
Definition: Store.h:269
void negativeCache()
Definition: store.cc:1307
int checkTooSmall()
Definition: store.cc:887
void completeSuccessfully(const char *whyWeAreSureWeStoredTheWholeReply)
Definition: store.cc:1003
void hashInsert(const cache_key *)
Definition: store.cc:410
void doAbandon(const char *context)
Definition: store.cc:472
size_t bytesWanted(Range< size_t > const aRange, bool ignoreDelayPool=false) const
Definition: store.cc:212
mem_status_t mem_status
Definition: Store.h:240
bool isAccepting() const
Definition: store.cc:1975
void unregisterAbortCallback(const char *reason)
Definition: store.cc:1475
const cache_key * calcPublicKey(const KeyScope keyScope)
Definition: store.cc:638
bool swappedOut() const
whether the entire entry is now on disk (possibly marked for deletion)
Definition: Store.h:136
bool shareableWhenPrivate
Definition: Store.h:331
uint16_t flags
Definition: Store.h:232
StoreEntry * adjustVary()
Definition: store.cc:651
void invokeHandlers()
unsigned short lock_count
Definition: Store.h:324
MemObject & mem()
Definition: Store.h:51
sdirno swap_dirn
Definition: Store.h:238
bool hasIfMatchEtag(const HttpRequest &request) const
has ETag matching at least one of the If-Match etags
Definition: store.cc:1859
void setCollapsingRequirement(const bool required)
allow or forbid collapsed requests feeding
Definition: store.cc:1999
const char * getSerialisedMetaData(size_t &length) const
Definition: store.cc:1736
void ensureMemObject(const char *storeId, const char *logUri, const HttpRequestMethod &aMethod)
initialize mem_obj (if needed) and set URIs/method (if missing)
Definition: store.cc:1575
int locked() const
Definition: Store.h:146
bool hasIfNoneMatchEtag(const HttpRequest &request) const
has ETag matching at least one of the If-None-Match etags
Definition: store.cc:1866
void dump(int debug_lvl) const
Definition: store.cc:1485
void checkDisk() const
does nothing except throwing if disk-associated data members are inconsistent
Definition: store.cc:1948
void completeTruncated(const char *whyWeConsiderTheReplyTruncated)
Definition: store.cc:1010
int unlock(const char *context)
Definition: store.cc:455
const char * url() const
Definition: store.cc:1552
bool hasMemStore() const
whether there is a corresponding locked shared memory table entry
Definition: Store.h:213
void complete()
Definition: store.cc:1017
void startWriting()
Definition: store.cc:1707
time_t lastModified() const
Definition: Store.h:178
Store::EntryGuard EntryGuard
Definition: Store.h:306
time_t expires
Definition: Store.h:226
bool hasEtag(ETag &etag) const
whether this entry has an ETag; if yes, puts ETag value into parameter
Definition: store.cc:1848
void lastModified(const time_t when)
Definition: Store.h:176
void release(const bool shareable=false)
Definition: store.cc:1132
bool memoryCachable()
checkCachable() and can be cached in memory
Definition: store.cc:1262
void detachFromDisk()
Definition: store.cc:1940
bool hasDisk(const sdirno dirn=-1, const sfileno filen=-1) const
Definition: store.cc:1915
swap_status_t swap_status
Definition: Store.h:246
void write(StoreIOBuffer)
Definition: store.cc:766
void lock(const char *context)
Definition: store.cc:431
bool checkDeferRead(int fd) const
Definition: store.cc:230
void swapOutDecision(const MemObject::SwapOut::Decision &decision)
Definition: store.cc:1786
void flush() override
Definition: store.cc:1598
time_t timestamp
Definition: Store.h:224
bool makePublic(const KeyScope keyScope=ksDefault)
Definition: store.cc:166
bool timestampsSet()
Definition: store.cc:1373
void clearPublicKeyScope()
Definition: store.cc:595
const cache_key * publicKey() const
Definition: Store.h:113
void memOutDecision(const bool willCacheInRam)
Definition: store.cc:1777
void clearPrivate()
Definition: store.cc:179
void abandon(const char *context)
Definition: Store.h:284
bool swappingOut() const
whether we are in the process of writing this entry to disk
Definition: Store.h:134
void lengthWentBad(const char *reason)
flags [truncated or too big] entry with ENTRY_BAD_LENGTH and releases it
Definition: store.cc:995
bool validLength() const
Definition: store.cc:1190
void expireNow()
Definition: store.cc:759
bool updateOnNotModified(const StoreEntry &e304)
Definition: store.cc:1438
time_t lastModified_
received Last-Modified value or -1; use lastModified()
Definition: Store.h:228
void registerAbortCallback(const AsyncCall::Pointer &)
notify the StoreEntry writer of a 3rd-party initiated StoreEntry abort
Definition: store.cc:1467
const char * describeTimestamps() const
Definition: store.cc:1987
Store::Disk & disk() const
the disk this entry is [being] cached on; asserts for entries w/o a disk
Definition: store.cc:1906
ESIElement::Pointer cachedESITree
Definition: Store.h:255
bool mayStartSwapOut()
whether we may start writing to disk (now or in the future)
friend std::ostream & operator<<(std::ostream &os, const StoreEntry &e)
Definition: store.cc:2031
void forcePublicKey(const cache_key *newkey)
Definition: store.cc:612
void storeErrorResponse(HttpReply *reply)
Store a prepared error response. MemObject locks the reply object.
Definition: store.cc:1674
bool mayStartHitting() const
Definition: Store.h:288
const char * getMD5Text() const
Definition: store.cc:206
const MemObject & mem() const
Definition: Store.h:52
sfileno swap_filen
unique ID inside a cache_dir for swapped out entries; -1 for others
Definition: Store.h:236
void storeWriterDone()
called when a store writer ends its work (successfully or not)
Definition: store.cc:1794
void setPrivateKey(const bool shareable, const bool permanent)
Definition: store.cc:534
void hashDelete()
Definition: store.cc:419
void makePrivate(const bool shareable)
Definition: store.cc:173
int checkNegativeHit() const
Definition: store.cc:1286
void attachToDisk(const sdirno, const sfileno, const swap_status_t)
Definition: store.cc:1926
void kickProducer()
calls back producer registered with deferProducer
Definition: store.cc:362
RemovalPolicyNode repl
Definition: Store.h:222
AsyncCall::Pointer deferredProducer
producer callback registered with deferProducer
Definition: Store.h:335
static size_t inUseCount()
Definition: store.cc:198
void replaceHttpReply(const HttpReplyPointer &, const bool andStartWriting=true)
Definition: store.cc:1691
bool hasOneOfEtags(const String &reqETags, const bool allowWeakMatch) const
whether at least one of the request ETags matches entity ETag
Definition: store.cc:1877
MemObject * mem_obj
Definition: Store.h:221
void vappendf(const char *, va_list) override
Definition: store.cc:807
StoreEntry()
Definition: store.cc:324
ping_status_t ping_status
Definition: Store.h:242
void setNoDelay(bool const)
Definition: store.cc:236
void reset()
Definition: store.cc:1607
void cacheInMemory()
start or continue storing in memory cache
bool modifiedSince(const time_t ims, const int imslen=-1) const
Definition: store.cc:1822
void append(char const *, int) override
Appends a c-string to existing packed data.
Definition: store.cc:789
void abort()
Definition: store.cc:1063
void trimMemory(const bool preserveSwappable)
Definition: store.cc:1800
int64_t objectLen() const
Definition: Store.h:257
~StoreEntry() override
Definition: store.cc:345
store_status_t store_status
Definition: Store.h:244
void buffer() override
Definition: store.cc:1587
void releaseRequest(const bool shareable=false)
Definition: store.cc:444
time_t lastref
Definition: Store.h:225
store_client_t storeClientType() const
Definition: store.cc:250
static Mem::Allocator * pool
Definition: Store.h:322
bool isEmpty() const
Definition: Store.h:66
void touch()
update last reference timestamp and related Store metadata
Definition: store.cc:438
int64_t contentLen() const
Definition: Store.h:258
void createMemObject()
Definition: store.cc:1561
bool swapoutFailed() const
whether we failed to write this entry to disk
Definition: Store.h:138
bool checkTooBig() const
Definition: store.cc:904
bool setPublicKey(const KeyScope keyScope=ksDefault)
Definition: store.cc:561
void deferProducer(const AsyncCall::Pointer &producer)
call back producer when more buffer space is available
Definition: store.cc:352
const HttpReply * hasFreshestReply() const
Definition: Store.h:57
uint64_t swap_file_sz
Definition: Store.h:230
uint16_t refcount
Definition: Store.h:231
void swapOut()
bool checkCachable()
Definition: store.cc:915
bool hasTransients() const
whether there is a corresponding locked transients table entry
Definition: Store.h:211
void swapOutFileClose(int how)
bool hittingRequiresCollapsing() const
whether this entry can feed collapsed requests and only them
Definition: Store.h:216
int validToSend() const
Definition: store.cc:1333
void setMemStatus(mem_status_t)
Definition: store.cc:1510
void destroyMemObject()
Definition: store.cc:372
bool cacheNegatively()
Definition: store.cc:187
Store statistics related to low-level I/O.
Definition: StoreStats.h:58
manages a single cache_dir
Definition: Disk.h:22
Entry * entry_
the guarded Entry or nil
Definition: Store.h:390
const char * context_
default unlock() message
Definition: Store.h:391
EntryGuard(EntryGuard &&)=delete
EntryGuard(Entry *entry, const char *context)
Definition: Store.h:357
Entry * get()
Definition: Store.h:373
void onException() noexcept
Definition: store.cc:2087
void unlockAndReset(const char *resetContext=nullptr)
Definition: Store.h:380
Definition: cbdata.cc:38
#define PRINTF_FORMAT_ARG2
#define EBIT_TEST(flag, bit)
Definition: defines.h:69
ping_status_t
Definition: enums.h:39
enum _mem_status_t mem_status_t
swap_status_t
StoreEntry relationship with a disk cache.
Definition: enums.h:55
@ SWAPOUT_FAILED
Definition: enums.h:68
@ SWAPOUT_WRITING
Definition: enums.h:61
@ SWAPOUT_DONE
Definition: enums.h:64
@ ENTRY_REQUIRES_COLLAPSING
Definition: enums.h:118
@ KEY_PRIVATE
Definition: enums.h:102
store_client_t
Definition: enums.h:71
store_status_t
Definition: enums.h:49
void FREE(void *)
Definition: forward.h:37
void Maintain(void *unused)
Definition: store.cc:1118
void Stats(StoreEntry *output)
Definition: store.cc:125
signed int sdirno
Definition: forward.h:23
unsigned char cache_key
Store key.
Definition: forward.h:29
signed_int32_t sfileno
Definition: forward.h:22
KeyScope
Definition: store_key_md5.h:18
@ ksDefault
Definition: store_key_md5.h:19
static const char * storeId(const int i)
Definition: testRock.cc:159

 

Introduction

Documentation

Support

Miscellaneous

Web Site Translations

Mirrors