StoreMap.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_IPC_STOREMAP_H
#define SQUID_SRC_IPC_STOREMAP_H
 
#include "ipc/mem/FlexibleArray.h"
#include "ipc/mem/Pointer.h"
#include "ipc/ReadWriteLock.h"
#include "sbuf/SBuf.h"
#include "store/forward.h"
#include "store_key_md5.h"
 
#include <functional>
 
namespace Ipc
{
 
typedef int32_t StoreMapSliceId;
 
class StoreMapSlice
{
public:
    typedef uint32_t Size;
 
    StoreMapSlice(): size(0), next(-1) {}
    StoreMapSlice(const StoreMapSlice &o) {
        size.exchange(o.size);
        next.exchange(o.next);
    }
 
    StoreMapSlice &operator =(const StoreMapSlice &o) {
        size.store(o.size);
        next.store(o.next);
        return *this;
    }
 
    void clear() { size = 0; next = -1; }
 
    std::atomic<Size> size; 
    std::atomic<StoreMapSliceId> next; 
};
 
class StoreMapAnchor
{
public:
    StoreMapAnchor();
 
    void set(const StoreEntry &anEntry, const cache_key *aKey = nullptr);
    void exportInto(StoreEntry &) const;
 
    void setKey(const cache_key *const aKey);
    bool sameKey(const cache_key *const aKey) const;
 
    void rewind();
 
    /* entry state may change immediately after calling these methods unless
     * the caller holds an appropriate lock */
    bool empty() const { return !key[0] && !key[1]; }
    bool reading() const { return lock.readers; }
    bool writing() const { return lock.writing; }
    bool complete() const { return !empty() && !writing(); }
 
public:
    mutable ReadWriteLock lock; 
    std::atomic<uint8_t> waitingToBeFreed; 
    std::atomic<uint8_t> writerHalted;
 
    // fields marked with [app] can be modified when appending-while-reading
    // fields marked with [update] can be modified when updating-while-reading
 
    uint64_t key[2] = {0, 0}; 
 
    // STORE_META_STD TLV field from StoreEntry
    struct Basics {
        void clear() {
            timestamp = 0;
            lastref = 0;
            expires = 0;
            lastmod = 0;
            swap_file_sz.store(0);
            refcount = 0;
            flags = 0;
        }
        time_t timestamp = 0;
        time_t lastref = 0;
        time_t expires = 0;
        time_t lastmod = 0;
        std::atomic<uint64_t> swap_file_sz; // [app]
        uint16_t refcount = 0;
        uint16_t flags = 0;
    } basics;
 
    std::atomic<StoreMapSliceId> start;
 
    std::atomic<StoreMapSliceId> splicingPoint;
};
 
template <class C>
class StoreMapItems
{
public:
    typedef C Item;
    typedef Ipc::Mem::Owner< StoreMapItems<Item> > Owner;
 
    explicit StoreMapItems(const int aCapacity): capacity(aCapacity), items(aCapacity) {}
 
    size_t sharedMemorySize() const { return SharedMemorySize(capacity); }
    static size_t SharedMemorySize(const int aCapacity) { return sizeof(StoreMapItems<Item>) + aCapacity*sizeof(Item); }
 
    Item &at(const int index)
    {
        assert(index >= 0);
        assert(index < capacity);
        return items[index];
    }
 
    const Item &at(const int index) const
    {
        return const_cast<StoreMapItems<C>&>(*this).at(index);
    }
 
    void fill(const Item &value)
    {
        for (int index = 0; index < capacity; ++index)
            items[index] = value;
    }
 
    const int capacity; 
    Ipc::Mem::FlexibleArray<Item> items; 
};
 
typedef StoreMapItems<StoreMapSlice> StoreMapSlices;
 
class StoreMapAnchors
{
public:
    typedef Ipc::Mem::Owner< StoreMapAnchors > Owner;
 
    explicit StoreMapAnchors(const int aCapacity);
 
    size_t sharedMemorySize() const;
    static size_t SharedMemorySize(const int anAnchorLimit);
 
    std::atomic<int32_t> count; 
    std::atomic<uint32_t> victim; 
    const int capacity; 
    Ipc::Mem::FlexibleArray<StoreMapAnchor> items; 
};
// TODO: Find an elegant way to use StoreMapItems in StoreMapAnchors
 
typedef StoreMapItems< std::atomic<sfileno> > StoreMapFileNos;
 
class StoreMapUpdate
{
public:
    class Edition
    {
    public:
        Edition(): anchor(nullptr), fileNo(-1), name(-1), splicingPoint(-1) {}
 
        explicit operator bool() const { return anchor; }
 
        StoreMapAnchor *anchor; 
        sfileno fileNo; 
        sfileno name; 
 
        StoreMapSliceId splicingPoint;
    };
 
    explicit StoreMapUpdate(StoreEntry *anEntry);
    StoreMapUpdate(const StoreMapUpdate &other);
    ~StoreMapUpdate();
 
    StoreMapUpdate &operator =(const StoreMapUpdate &other) = delete;
 
    StoreEntry *entry; 
    Edition stale; 
    Edition fresh; 
};
 
class StoreMapCleaner;
 
class StoreMap
{
public:
    typedef StoreMapFileNos FileNos;
    typedef StoreMapAnchor Anchor;
    typedef StoreMapAnchors Anchors;
    typedef sfileno AnchorId;
    typedef StoreMapSlice Slice;
    typedef StoreMapSlices Slices;
    typedef StoreMapSliceId SliceId;
    typedef StoreMapUpdate Update;
 
public:
    class Owner
    {
    public:
        Owner();
        ~Owner();
        FileNos::Owner *fileNos;
        Anchors::Owner *anchors;
        Slices::Owner *slices;
    private:
        Owner(const Owner &); // not implemented
        Owner &operator =(const Owner &); // not implemented
    };
 
    static Owner *Init(const SBuf &path, const int slotLimit);
 
    StoreMap(const SBuf &aPath);
 
    sfileno fileNoByKey(const cache_key *const key) const;
 
    int compareVersions(const sfileno oldFileno, time_t newVersion) const;
 
    Anchor *openForWriting(const cache_key *const key, sfileno &fileno);
    Anchor *openForWritingAt(sfileno fileno, bool overwriteExisting = true);
    void startAppending(const sfileno fileno);
    void closeForWriting(const sfileno fileno);
    void switchWritingToReading(const sfileno fileno);
    void forgetWritingEntry(const sfileno fileno);
 
    bool openForUpdating(Update &update, sfileno fileNoHint);
    void closeForUpdating(Update &update);
    void abortUpdating(Update &update);
 
    const Anchor *peekAtReader(const sfileno fileno) const;
 
    const Anchor *peekAtWriter(const sfileno fileno) const;
 
    const Anchor &peekAtEntry(const sfileno fileno) const;
 
    bool freeEntry(const sfileno);
    void freeEntryByKey(const cache_key *const key);
 
    bool markedForDeletion(const cache_key *const);
 
    bool hasReadableEntry(const cache_key *const);
 
    const Anchor *openForReading(const cache_key *const key, sfileno &fileno);
    const Anchor *openForReadingAt(const sfileno, const cache_key *const);
    void closeForReading(const sfileno fileno);
    void closeForReadingAndFreeIdle(const sfileno fileno);
 
    const Anchor *openOrCreateForReading(const cache_key *, sfileno &);
 
    Slice &writeableSlice(const AnchorId anchorId, const SliceId sliceId);
    const Slice &readableSlice(const AnchorId anchorId, const SliceId sliceId) const;
    Anchor &writeableEntry(const AnchorId anchorId);
    const Anchor &readableEntry(const AnchorId anchorId) const;
 
    void prepFreeSlice(const SliceId sliceId);
 
    SliceId sliceContaining(const sfileno fileno, const uint64_t nth) const;
 
    void abortWriting(const sfileno fileno);
 
    bool purgeOne();
 
    bool validateHit(const sfileno);
 
    void disableHitValidation() { hitValidation = false; }
 
    void importSlice(const SliceId sliceId, const Slice &slice);
 
    /* SwapFilenMax limits the number of entries, but not slices or slots */
    bool validEntry(const int n) const; 
    bool validSlice(const int n) const; 
    int entryCount() const; 
    int entryLimit() const; 
    int sliceLimit() const; 
 
    void updateStats(ReadWriteLockStats &stats) const;
 
    StoreMapCleaner *cleaner; 
 
protected:
    const SBuf path; 
    Mem::Pointer<StoreMapFileNos> fileNos; 
    Mem::Pointer<StoreMapAnchors> anchors; 
    Mem::Pointer<StoreMapSlices> slices; 
 
private:
    sfileno nameByKey(const cache_key *const key) const;
    sfileno fileNoByName(const sfileno name) const;
    void relocate(const sfileno name, const sfileno fileno);
 
    Anchor &anchorAt(const sfileno fileno);
    const Anchor &anchorAt(const sfileno fileno) const;
    Anchor &anchorByKey(const cache_key *const key);
 
    Slice &sliceAt(const SliceId sliceId);
    const Slice &sliceAt(const SliceId sliceId) const;
    Anchor *openForReading(Slice &s);
    bool openKeyless(Update::Edition &edition);
    void closeForUpdateFinal(Update &update);
 
    typedef std::function<bool (const sfileno name)> NameFilter; // a "name"-based test
    bool visitVictims(const NameFilter filter);
 
    void freeChain(const sfileno fileno, Anchor &inode, const bool keepLock);
    void freeChainAt(SliceId sliceId, const SliceId splicingPoint);
 
    bool hitValidation;
};
 
class StoreMapCleaner
{
public:
    virtual ~StoreMapCleaner() {}
 
    virtual void noteFreeMapSlice(const StoreMapSliceId sliceId) = 0;
};
 
} // namespace Ipc
 
// We do not reuse FileMap because we cannot control its size,
// resulting in sfilenos that are pointing beyond the database.
 
#endif /* SQUID_SRC_IPC_STOREMAP_H */