Store.h

Go to the documentation of this file.

/*
 * Copyright (C) 1996-2025 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
 */
 
#ifndef SQUID_SRC_STORE_H
#define SQUID_SRC_STORE_H
 
#include "base/DelayedAsyncCalls.h"
#include "base/Packable.h"
#include "base/Range.h"
#include "base/RefCount.h"
#include "comm/forward.h"
#include "hash.h"
#include "http/forward.h"
#include "http/RequestMethod.h"
#include "HttpReply.h"
#include "MemObject.h"
#include "RemovalPolicy.h"
#include "store/Controller.h"
#include "store/forward.h"
#include "store_key_md5.h"
#include "StoreIOBuffer.h"
#include "StoreStats.h"
 
#include <ostream>
 
class AsyncCall;
class HttpRequest;
class RequestFlags;
 
extern StoreIoStats store_io_stats;
 
class StoreEntry : public hash_link, public Packable
{
 
public:
    bool checkDeferRead(int fd) const;
 
    const char *getMD5Text() const;
    StoreEntry();
    ~StoreEntry() override;
 
    MemObject &mem() { assert(mem_obj); return *mem_obj; }
    const MemObject &mem() const { assert(mem_obj); return *mem_obj; }
 
    const HttpReply *hasFreshestReply() const { return mem_obj ? &mem_obj->freshestReply() : nullptr; }
 
    bool hasParsedReplyHeader() const;
 
    void write(StoreIOBuffer);
 
    bool isEmpty() const { return mem().endOffset() == 0; }
    bool isAccepting() const;
    size_t bytesWanted(Range<size_t> const aRange, bool ignoreDelayPool = false) const;
 
    void completeSuccessfully(const char *whyWeAreSureWeStoredTheWholeReply);
 
    void completeTruncated(const char *whyWeConsiderTheReplyTruncated);
 
    void complete();
 
    store_client_t storeClientType() const;
    const char *getSerialisedMetaData(size_t &length) const;
    void storeErrorResponse(HttpReply *reply);
    void replaceHttpReply(const HttpReplyPointer &, const bool andStartWriting = true);
    void startWriting(); 
    bool mayStartSwapOut();
    void trimMemory(const bool preserveSwappable);
 
    // called when a decision to cache in memory has been made
    void memOutDecision(const bool willCacheInRam);
    // called when a decision to cache on disk has been made
    void swapOutDecision(const MemObject::SwapOut::Decision &decision);
    void storeWriterDone();
 
    void abort();
    bool makePublic(const KeyScope keyScope = ksDefault);
    void makePrivate(const bool shareable);
    void clearPrivate();
    bool setPublicKey(const KeyScope keyScope = ksDefault);
    void clearPublicKeyScope();
 
    const cache_key *publicKey() const {
        return (!EBIT_TEST(flags, KEY_PRIVATE)) ?
               reinterpret_cast<const cache_key*>(key): // may be nil
               nullptr;
    }
 
    void setPrivateKey(const bool shareable, const bool permanent);
 
    void expireNow();
    void releaseRequest(const bool shareable = false);
    void negativeCache();
    bool cacheNegatively();     // TODO: why both negativeCache() and cacheNegatively() ?
    void invokeHandlers();
    void cacheInMemory(); 
    void swapOut();
    bool swappingOut() const { return swap_status == SWAPOUT_WRITING; }
    bool swappedOut() const { return swap_status == SWAPOUT_DONE; }
    bool swapoutFailed() const { return swap_status == SWAPOUT_FAILED; }
    void swapOutFileClose(int how);
    const char *url() const;
    bool checkCachable();
    int checkNegativeHit() const;
    int locked() const { return lock_count; }
    int validToSend() const;
    bool memoryCachable(); 
 
    void createMemObject();
 
    void createMemObject(const char *storeId, const char *logUri, const HttpRequestMethod &aMethod);
 
    void ensureMemObject(const char *storeId, const char *logUri, const HttpRequestMethod &aMethod);
 
    void dump(int debug_lvl) const;
    void hashDelete();
    void hashInsert(const cache_key *);
    void registerAbortCallback(const AsyncCall::Pointer &);
    void reset();
    void setMemStatus(mem_status_t);
    bool timestampsSet();
    void unregisterAbortCallback(const char *reason);
    void destroyMemObject();
    int checkTooSmall();
 
    void setNoDelay (bool const);
    void lastModified(const time_t when) { lastModified_ = when; }
    time_t lastModified() const {
        // may still return -1 if timestamp is not set
        return lastModified_ < 0 ? timestamp : lastModified_;
    }
    const char *describeTimestamps() const;
    // TODO: consider removing currently unsupported imslen parameter
    bool modifiedSince(const time_t ims, const int imslen = -1) const;
    bool hasIfMatchEtag(const HttpRequest &request) const;
    bool hasIfNoneMatchEtag(const HttpRequest &request) const;
    bool hasEtag(ETag &etag) const;
 
    bool updateOnNotModified(const StoreEntry &e304);
 
    Store::Disk &disk() const;
    bool hasDisk(const sdirno dirn = -1, const sfileno filen = -1) const;
    void attachToDisk(const sdirno, const sfileno, const swap_status_t);
    void detachFromDisk();
 
    bool hasTransients() const { return mem_obj && mem_obj->xitTable.index >= 0; }
    bool hasMemStore() const { return mem_obj && mem_obj->memCache.index >= 0; }
 
    bool hittingRequiresCollapsing() const { return EBIT_TEST(flags, ENTRY_REQUIRES_COLLAPSING); }
 
    void setCollapsingRequirement(const bool required);
 
    MemObject *mem_obj;
    RemovalPolicyNode repl;
    /* START OF ON-DISK STORE_META_STD TLV field */
    time_t timestamp;
    time_t lastref;
    time_t expires;
private:
    time_t lastModified_; 
public:
    uint64_t swap_file_sz;
    uint16_t refcount;
    uint16_t flags;
    /* END OF ON-DISK STORE_META_STD */
 
    sfileno swap_filen:25; // keep in sync with SwapFilenMax
 
    sdirno swap_dirn:7;
 
    mem_status_t mem_status:3;
 
    ping_status_t ping_status:3;
 
    store_status_t store_status:3;
 
    swap_status_t swap_status:3;
 
public:
    static size_t inUseCount();
 
    void *operator new(size_t byteCount);
    void operator delete(void *address);
 
    int64_t objectLen() const { return mem().object_sz; }
    int64_t contentLen() const { return objectLen() - mem().baseReply().hdr_sz; }
 
    void lock(const char *context);
 
    int unlock(const char *context);
 
    int locks() const { return static_cast<int>(lock_count); }
 
    void touch();
 
    void release(const bool shareable = false);
 
    void abandon(const char *context) { if (!locked()) doAbandon(context); }
 
    bool mayStartHitting() const {
        return !EBIT_TEST(flags, KEY_PRIVATE) || shareableWhenPrivate;
    }
 
#if USE_ADAPTATION
    void deferProducer(const AsyncCall::Pointer &producer);
    void kickProducer();
#endif
 
    /* Packable API */
    void append(char const *, int) override;
    void vappendf(const char *, va_list) override;
    void buffer() override;
    void flush() override;
 
protected:
    typedef Store::EntryGuard EntryGuard;
 
    void storeWritingCheckpoint();
    void checkDisk() const;
 
private:
    void doAbandon(const char *context);
    bool checkTooBig() const;
    void forcePublicKey(const cache_key *newkey);
    StoreEntry *adjustVary();
    const cache_key *calcPublicKey(const KeyScope keyScope);
 
    void lengthWentBad(const char *reason);
 
    static Mem::Allocator *pool;
 
    unsigned short lock_count;      /* Assume < 65536! */
 
    bool shareableWhenPrivate;
 
#if USE_ADAPTATION
    AsyncCall::Pointer deferredProducer;
#endif
 
    bool validLength() const;
    bool hasOneOfEtags(const String &reqETags, const bool allowWeakMatch) const;
 
    friend std::ostream &operator <<(std::ostream &os, const StoreEntry &e);
};
 
std::ostream &operator <<(std::ostream &os, const StoreEntry &e);
 
typedef void (*STOREGETCLIENT) (StoreEntry *, void *cbdata);
 
namespace Store {
 
class EntryGuard {
public:
    EntryGuard(Entry *entry, const char *context):
        entry_(entry), context_(context) {
        assert(!entry_ || entry_->locked());
    }
 
    ~EntryGuard() {
        if (entry_) {
            // something went wrong -- the caller did not unlockAndReset() us
            onException();
        }
    }
 
    EntryGuard(EntryGuard &&) = delete; // no copying or moving (for now)
 
    Entry *get() {
        return entry_;
    }
 
    void unlockAndReset(const char *resetContext = nullptr) {
        if (entry_) {
            entry_->unlock(resetContext ? resetContext : context_);
            entry_ = nullptr;
        }
    }
 
private:
    void onException() noexcept;
 
    Entry *entry_; 
    const char *context_; 
};
 
void Stats(StoreEntry *output);
void Maintain(void *unused);
}; // namespace Store
 
size_t storeEntryInUse();
 
const char *storeEntryFlags(const StoreEntry *);
 
void storeEntryReplaceObject(StoreEntry *, HttpReply *);
 
StoreEntry *storeGetPublic(const char *uri, const HttpRequestMethod& method);
 
StoreEntry *storeGetPublicByRequest(HttpRequest * request, const KeyScope keyScope = ksDefault);
 
StoreEntry *storeGetPublicByRequestMethod(HttpRequest * request, const HttpRequestMethod& method, const KeyScope keyScope = ksDefault);
 
StoreEntry *storeCreateEntry(const char *, const char *, const RequestFlags &, const HttpRequestMethod&);
 
StoreEntry *storeCreatePureEntry(const char *storeId, const char *logUrl, const HttpRequestMethod&);
 
void storeInit(void);
 
void storeConfigure(void);
 
int expiresMoreThan(time_t, time_t);
 
void storeAppendPrintf(StoreEntry *, const char *,...) PRINTF_FORMAT_ARG2;
 
void storeAppendVPrintf(StoreEntry *, const char *, va_list ap);
 
int storeTooManyDiskFilesOpen(void);
 
void storeHeapPositionUpdate(StoreEntry *, SwapDir *);
 
void storeSwapFileNumberSet(StoreEntry * e, sfileno filn);
 
void storeFsInit(void);
 
void storeFsDone(void);
 
void storeReplAdd(const char *, REMOVALPOLICYCREATE *);
 
extern FREE destroyStoreEntry;
 
void storeGetMemSpace(int size);
 
#endif /* SQUID_SRC_STORE_H */