Store.h

Go to the documentation of this file.

/*
 * Copyright (C) 1996-2019 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_STORE_H
#define SQUID_STORE_H

#include "base/Packable.h"
#include "base/Range.h"
#include "base/RefCount.h"
#include "comm/forward.h"
#include "CommRead.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"

#if USE_SQUID_ESI
#include "esi/Element.h"
#endif

#include <ostream>

class AsyncCall;
class HttpRequest;
class RequestFlags;

extern StoreIoStats store_io_stats;

class StoreEntry : public hash_link, public Packable
{

public:
    static DeferredRead::DeferrableRead DeferReader;
    bool checkDeferRead(int fd) const;

    const char *getMD5Text() const;
    StoreEntry();
    virtual ~StoreEntry();

    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; }

    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 lengthWentBad(const char *reason);
    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 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();     
    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 registerAbort(STABH * cb, void *);
    void reset();
    void setMemStatus(mem_status_t);
    bool timestampsSet();
    void unregisterAbort();
    void destroyMemObject();
    int checkTooSmall();

    void delayAwareRead(const Comm::ConnectionPointer &conn, char *buf, int len, AsyncCall::Pointer callback);

    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();
    static void getPublicByRequestMethod(StoreClient * aClient, HttpRequest * request, const HttpRequestMethod& method);
    static void getPublicByRequest(StoreClient * aClient, HttpRequest * request);
    static void getPublic(StoreClient * aClient, const char *uri, const HttpRequestMethod& method);

    void *operator new(size_t byteCount);
    void operator delete(void *address);
#if USE_SQUID_ESI

    ESIElement::Pointer cachedESITree;
#endif
    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 */
    virtual void append(char const *, int);
    virtual void vappendf(const char *, va_list);
    virtual void buffer();
    virtual void flush();

protected:
    typedef Store::EntryGuard EntryGuard;

    void transientsAbandonmentCheck();
    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);

    static MemAllocator *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);

void storeFreeMemory(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_STORE_H */