3 * SQUID Web Proxy Cache http://www.squid-cache.org/
4 * ----------------------------------------------------------
6 * Squid is the result of efforts by numerous individuals from
7 * the Internet community; see the CONTRIBUTORS file for full
8 * details. Many organizations have provided support for Squid's
9 * development; see the SPONSORS file for full details. Squid is
10 * Copyrighted (C) 2001 by the Regents of the University of
11 * California; see the COPYRIGHT file for full details. Squid
12 * incorporates software developed and/or copyrighted by other
13 * sources; see the CREDITS file for full details.
15 * This program is free software; you can redistribute it and/or modify
16 * it under the terms of the GNU General Public License as published by
17 * the Free Software Foundation; either version 2 of the License, or
18 * (at your option) any later version.
20 * This program is distributed in the hope that it will be useful,
21 * but WITHOUT ANY WARRANTY; without even the implied warranty of
22 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23 * GNU General Public License for more details.
25 * You should have received a copy of the GNU General Public License
26 * along with this program; if not, write to the Free Software
27 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
34 \defgroup StoreAPI Store API
38 #include "base/RefCount.h"
39 #include "comm/forward.h"
42 #include "http/forward.h"
43 #include "http/RequestMethod.h"
44 #include "HttpReply.h"
45 #include "MemObject.h"
47 #include "RemovalPolicy.h"
48 #include "StoreIOBuffer.h"
49 #include "StoreStats.h"
52 #include "esi/Element.h"
65 extern StoreIoStats store_io_stats
;
67 /// maximum number of entries per cache_dir
68 enum { SwapFilenMax
= 0xFFFFFF }; // keep in sync with StoreEntry::swap_filen
73 class StoreEntry
: public hash_link
77 static DeferredRead::DeferrableRead DeferReader
;
78 bool checkDeferRead(int fd
) const;
80 virtual const char *getMD5Text() const;
82 virtual ~StoreEntry();
84 virtual HttpReply
const *getReply() const;
85 virtual void write (StoreIOBuffer
);
87 /** Check if the Store entry is emtpty
88 * \retval true Store contains 0 bytes of data.
89 * \retval false Store contains 1 or more bytes of data.
90 * \retval false Store contains negative content !!!!!!
92 virtual bool isEmpty() const {
94 return mem_obj
->endOffset() == 0;
96 virtual bool isAccepting() const;
97 virtual size_t bytesWanted(Range
<size_t> const aRange
, bool ignoreDelayPool
= false) const;
98 virtual void complete();
99 virtual store_client_t
storeClientType() const;
100 virtual char const *getSerialisedMetaData();
101 /// Store a prepared error response. MemObject locks the reply object.
102 void storeErrorResponse(HttpReply
*reply
);
103 void replaceHttpReply(HttpReply
*, bool andStartWriting
= true);
104 void startWriting(); ///< pack and write reply headers and, maybe, body
105 /// whether we may start writing to disk (now or in the future)
106 virtual bool mayStartSwapOut();
107 virtual void trimMemory(const bool preserveSwappable
);
109 // called when a decision to cache in memory has been made
110 void memOutDecision(const bool willCacheInRam
);
111 // called when a decision to cache on disk has been made
112 void swapOutDecision(const MemObject::SwapOut::Decision
&decision
);
119 void setPrivateKey();
121 void releaseRequest();
122 void negativeCache();
123 void cacheNegatively(); /** \todo argh, why both? */
124 void invokeHandlers();
126 void cacheInMemory(); ///< start or continue storing in memory cache
128 /// whether we are in the process of writing this entry to disk
129 bool swappingOut() const { return swap_status
== SWAPOUT_WRITING
; }
130 void swapOutFileClose(int how
);
131 const char *url() const;
132 /// Satisfies cachability requirements shared among disk and RAM caches.
133 /// Encapsulates common checks of mayStartSwapOut() and memoryCachable().
134 /// TODO: Rename and make private so only those two methods can call this.
135 bool checkCachable();
136 int checkNegativeHit() const;
138 int validToSend() const;
139 bool memoryCachable(); ///< checkCachable() and can be cached in memory
141 /// if needed, initialize mem_obj member w/o URI-related information
142 MemObject
*makeMemObject();
144 /// initialize mem_obj member (if needed) and supply URI-related info
145 void createMemObject(const char *storeId
, const char *logUri
, const HttpRequestMethod
&aMethod
);
147 void dump(int debug_lvl
) const;
149 void hashInsert(const cache_key
*);
150 void registerAbort(STABH
* cb
, void *);
152 void setMemStatus(mem_status_t
);
153 void timestampsSet();
154 void unregisterAbort();
155 void destroyMemObject();
158 void delayAwareRead(const Comm::ConnectionPointer
&conn
, char *buf
, int len
, AsyncCall::Pointer callback
);
160 void setNoDelay (bool const);
161 bool modifiedSince(HttpRequest
* request
) const;
162 /// has ETag matching at least one of the If-Match etags
163 bool hasIfMatchEtag(const HttpRequest
&request
) const;
164 /// has ETag matching at least one of the If-None-Match etags
165 bool hasIfNoneMatchEtag(const HttpRequest
&request
) const;
166 /// whether this entry has an ETag; if yes, puts ETag value into parameter
167 bool hasEtag(ETag
&etag
) const;
169 /** What store does this entry belong too ? */
170 virtual RefCount
<SwapDir
> store() const;
173 RemovalPolicyNode repl
;
174 /* START OF ON-DISK STORE_META_STD TLV field */
179 uint64_t swap_file_sz
;
182 /* END OF ON-DISK STORE_META_STD */
184 /// unique ID inside a cache_dir for swapped out entries; -1 for others
185 sfileno swap_filen
:25; // keep in sync with SwapFilenMax
189 mem_status_t mem_status
:3;
191 ping_status_t ping_status
:3;
193 store_status_t store_status
:3;
195 swap_status_t swap_status
:3;
198 static size_t inUseCount();
199 static void getPublicByRequestMethod(StoreClient
* aClient
, HttpRequest
* request
, const HttpRequestMethod
& method
);
200 static void getPublicByRequest(StoreClient
* aClient
, HttpRequest
* request
);
201 static void getPublic(StoreClient
* aClient
, const char *uri
, const HttpRequestMethod
& method
);
203 virtual bool isNull() {
207 void *operator new(size_t byteCount
);
208 void operator delete(void *address
);
209 void setReleaseFlag();
212 ESIElement::Pointer cachedESITree
;
214 /** append bytes to the buffer */
215 virtual void append(char const *, int len
);
216 /** disable sending content to the clients */
217 virtual void buffer();
218 /** flush any buffered content */
219 virtual void flush();
220 virtual int64_t objectLen() const;
221 virtual int64_t contentLen() const;
223 /// claim shared ownership of this entry (for use in a given context)
224 /// matching lock() and unlock() contexts eases leak triage but is optional
225 void lock(const char *context
);
227 /// disclaim shared ownership; may remove entry from store and delete it
228 /// returns remaning lock level (zero for unlocked and possibly gone entry)
229 int unlock(const char *context
);
231 /// returns a local concurrent use counter, for debugging
232 int locks() const { return static_cast<int>(lock_count
); }
234 /// update last reference timestamp and related Store metadata
237 virtual void release();
240 /// call back producer when more buffer space is available
241 void deferProducer(const AsyncCall::Pointer
&producer
);
242 /// calls back producer registered with deferProducer
247 void transientsAbandonmentCheck();
250 static MemAllocator
*pool
;
252 unsigned short lock_count
; /* Assume < 65536! */
255 /// producer callback registered with deferProducer
256 AsyncCall::Pointer deferredProducer
;
259 bool validLength() const;
260 bool hasOneOfEtags(const String
&reqETags
, const bool allowWeakMatch
) const;
263 std::ostream
&operator <<(std::ostream
&os
, const StoreEntry
&e
);
265 /// \ingroup StoreAPI
266 class NullStoreEntry
:public StoreEntry
270 static NullStoreEntry
*getInstance();
275 const char *getMD5Text() const;
276 HttpReply
const *getReply() const { return NULL
; }
277 void write (StoreIOBuffer
) {}
279 bool isEmpty () const {return true;}
281 virtual size_t bytesWanted(Range
<size_t> const aRange
, bool ignoreDelayPool
= false) const { return aRange
.end
; }
283 void operator delete(void *address
);
287 store_client_t
storeClientType() const {return STORE_MEM_CLIENT
;}
289 char const *getSerialisedMetaData();
290 virtual bool mayStartSwapOut() { return false; }
292 void trimMemory(const bool preserveSwappable
) {}
294 static NullStoreEntry _instance
;
297 /// \ingroup StoreAPI
298 typedef void (*STOREGETCLIENT
) (StoreEntry
*, void *cbdata
);
302 * Abstract base class that will replace the whole store and swapdir interface.
304 class Store
: public RefCountable
308 /** The root store */
309 static Store
&Root() {
310 if (CurrentRoot
== NULL
)
311 fatal("No Store Root has been set");
314 static void Root(Store
*);
315 static void Root(RefCount
<Store
>);
316 static void Stats(StoreEntry
* output
);
317 static void Maintain(void *unused
);
321 /** Handle pending callbacks - called by the event loop. */
322 virtual int callback() = 0;
324 /** create the resources needed for this store to operate */
325 virtual void create();
328 * Notify this store that its disk is full.
329 \todo XXX move into a protected api call between store files and their stores, rather than a top level api call
331 virtual void diskFull();
333 /** Retrieve a store entry from the store */
334 virtual StoreEntry
* get(const cache_key
*) = 0;
336 /** \todo imeplement the async version */
337 virtual void get(String
const key
, STOREGETCLIENT callback
, void *cbdata
) = 0;
339 /* prepare the store for use. The store need not be usable immediately,
340 * it should respond to readable() and writable() with true as soon
341 * as it can provide those services
343 virtual void init() = 0;
346 * The maximum size the store will support in normal use. Inaccuracy is permitted,
347 * but may throw estimates for memory etc out of whack.
349 virtual uint64_t maxSize() const = 0;
351 /** The minimum size the store will shrink to via normal housekeeping */
352 virtual uint64_t minSize() const = 0;
354 /** current store size */
355 virtual uint64_t currentSize() const = 0;
357 /** the total number of objects stored */
358 virtual uint64_t currentCount() const = 0;
360 /** the maximum object size that can be stored, -1 if unlimited */
361 virtual int64_t maxObjectSize() const = 0;
363 /// collect cache storage-related statistics
364 virtual void getStats(StoreInfoStats
&stats
) const = 0;
367 * Output stats to the provided store entry.
368 \todo make these calls asynchronous
370 virtual void stat(StoreEntry
&) const = 0;
372 /** Sync the store prior to shutdown */
375 /** remove a Store entry from the store */
376 virtual void unlink (StoreEntry
&);
378 /* search in the store */
379 virtual StoreSearch
*search(String
const url
, HttpRequest
*) = 0;
381 /* pulled up from SwapDir for migration.... probably do not belong here */
382 virtual void reference(StoreEntry
&) = 0; /* Reference this object */
384 /// Undo reference(), returning false iff idle e should be destroyed
385 virtual bool dereference(StoreEntry
&e
, bool wantsLocalMemory
) = 0;
387 virtual void maintain() = 0; /* perform regular maintenance should be private and self registered ... */
389 // XXX: This method belongs to Store::Root/StoreController, but it is here
390 // to avoid casting Root() to StoreController until Root() API is fixed.
391 /// informs stores that this entry will be eventually unlinked
392 virtual void markForUnlink(StoreEntry
&e
) {}
394 // XXX: This method belongs to Store::Root/StoreController, but it is here
395 // because test cases use non-StoreController derivatives as Root
396 /// called when the entry is no longer needed by any transaction
397 virtual void handleIdleEntry(StoreEntry
&e
) {}
399 // XXX: This method belongs to Store::Root/StoreController, but it is here
400 // because test cases use non-StoreController derivatives as Root
401 /// called to get rid of no longer needed entry data in RAM, if any
402 virtual void memoryOut(StoreEntry
&e
, const bool preserveSwappable
) {}
404 // XXX: This method belongs to Store::Root/StoreController, but it is here
405 // to avoid casting Root() to StoreController until Root() API is fixed.
406 /// makes the entry available for collapsing future requests
407 virtual void allowCollapsing(StoreEntry
*e
, const RequestFlags
&reqFlags
, const HttpRequestMethod
&reqMethod
) {}
409 // XXX: This method belongs to Store::Root/StoreController, but it is here
410 // to avoid casting Root() to StoreController until Root() API is fixed.
411 /// marks the entry completed for collapsed requests
412 virtual void transientsCompleteWriting(StoreEntry
&e
) {}
414 // XXX: This method belongs to Store::Root/StoreController, but it is here
415 // to avoid casting Root() to StoreController until Root() API is fixed.
416 /// Update local intransit entry after changes made by appending worker.
417 virtual void syncCollapsed(const sfileno xitIndex
) {}
419 // XXX: This method belongs to Store::Root/StoreController, but it is here
420 // to avoid casting Root() to StoreController until Root() API is fixed.
421 /// calls Root().transients->abandon() if transients are tracked
422 virtual void transientsAbandon(StoreEntry
&e
) {}
424 // XXX: This method belongs to Store::Root/StoreController, but it is here
425 // to avoid casting Root() to StoreController until Root() API is fixed.
426 /// number of the transient entry readers some time ago
427 virtual int transientReaders(const StoreEntry
&e
) const { return 0; }
429 // XXX: This method belongs to Store::Root/StoreController, but it is here
430 // to avoid casting Root() to StoreController until Root() API is fixed.
431 /// disassociates the entry from the intransit table
432 virtual void transientsDisconnect(MemObject
&mem_obj
) {}
434 // XXX: This method belongs to Store::Root/StoreController, but it is here
435 // to avoid casting Root() to StoreController until Root() API is fixed.
436 /// removes the entry from the memory cache
437 virtual void memoryUnlink(StoreEntry
&e
) {}
439 // XXX: This method belongs to Store::Root/StoreController, but it is here
440 // to avoid casting Root() to StoreController until Root() API is fixed.
441 /// disassociates the entry from the memory cache, preserving cached data
442 virtual void memoryDisconnect(StoreEntry
&e
) {}
444 /// If the entry is not found, return false. Otherwise, return true after
445 /// tying the entry to this cache and setting inSync to updateCollapsed().
446 virtual bool anchorCollapsed(StoreEntry
&collapsed
, bool &inSync
) { return false; }
448 /// update a local collapsed entry with fresh info from this cache (if any)
449 virtual bool updateCollapsed(StoreEntry
&collapsed
) { return false; }
452 static RefCount
<Store
> CurrentRoot
;
455 /// \ingroup StoreAPI
456 typedef RefCount
<Store
> StorePointer
;
458 /// \ingroup StoreAPI
459 size_t storeEntryInUse();
461 /// \ingroup StoreAPI
462 const char *storeEntryFlags(const StoreEntry
*);
464 /// \ingroup StoreAPI
465 void storeEntryReplaceObject(StoreEntry
*, HttpReply
*);
467 /// \ingroup StoreAPI
468 StoreEntry
*storeGetPublic(const char *uri
, const HttpRequestMethod
& method
);
470 /// \ingroup StoreAPI
471 StoreEntry
*storeGetPublicByRequest(HttpRequest
* request
);
473 /// \ingroup StoreAPI
474 StoreEntry
*storeGetPublicByRequestMethod(HttpRequest
* request
, const HttpRequestMethod
& method
);
476 /// \ingroup StoreAPI
477 /// Like storeCreatePureEntry(), but also locks the entry and sets entry key.
478 StoreEntry
*storeCreateEntry(const char *, const char *, const RequestFlags
&, const HttpRequestMethod
&);
480 /// \ingroup StoreAPI
481 /// Creates a new StoreEntry with mem_obj and sets initial flags/states.
482 StoreEntry
*storeCreatePureEntry(const char *storeId
, const char *logUrl
, const RequestFlags
&, const HttpRequestMethod
&);
484 /// \ingroup StoreAPI
485 void storeInit(void);
487 /// \ingroup StoreAPI
488 void storeConfigure(void);
490 /// \ingroup StoreAPI
491 void storeFreeMemory(void);
493 /// \ingroup StoreAPI
494 int expiresMoreThan(time_t, time_t);
496 /// \ingroup StoreAPI
497 void storeAppendPrintf(StoreEntry
*, const char *,...) PRINTF_FORMAT_ARG2
;
499 /// \ingroup StoreAPI
500 void storeAppendVPrintf(StoreEntry
*, const char *, va_list ap
);
502 /// \ingroup StoreAPI
503 int storeTooManyDiskFilesOpen(void);
506 /// \ingroup StoreAPI
507 void storeHeapPositionUpdate(StoreEntry
*, SwapDir
*);
509 /// \ingroup StoreAPI
510 void storeSwapFileNumberSet(StoreEntry
* e
, sfileno filn
);
512 /// \ingroup StoreAPI
513 void storeFsInit(void);
515 /// \ingroup StoreAPI
516 void storeFsDone(void);
518 /// \ingroup StoreAPI
519 void storeReplAdd(const char *, REMOVALPOLICYCREATE
*);
521 /// \ingroup StoreAPI
522 extern FREE destroyStoreEntry
;
526 \todo should be a subclass of Packer perhaps ?
528 void packerToStoreInit(Packer
* p
, StoreEntry
* e
);
530 /// \ingroup StoreAPI
531 void storeGetMemSpace(int size
);
533 #endif /* SQUID_STORE_H */