src/StoreFileSystem.h

   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_STOREFILESYSTEM_H
  10 #define SQUID_STOREFILESYSTEM_H
  11
  12 #include "base/TypeTraits.h"
  13 #include "store/forward.h"
  14 #include <vector>
  15
  16 /* ****** DOCUMENTATION ***** */
  17
  18 /**
  19  \defgroup FileSystems  Storage Filesystems
  20  *
  21  \section FileSystemsIntroduction Introduction
  22  \par
  23  * Traditionally, Squid has always used the Unix filesystem (\link UFS UFS\endlink)
  24  * to store cache objects on disk.  Over the years, the
  25  * poor performance of \link UFS UFS\endlink has become very obvious.  In most
  26  * cases, \link UFS UFS\endlink limits Squid to about 30-50 requests per second.
  27  * Our work indicates that the poor performance is mostly
  28  * due to the synchronous nature of open() and unlink()
  29  * system calls, and perhaps thrashing of inode/buffer caches.
  30  *
  31  \par
  32  * We want to try out our own, customized filesystems with Squid.
  33  * In order to do that, we need a well-defined interface
  34  * for the bits of Squid that access the permanent storage
  35  * devices. We also require tighter control of the replacement
  36  * policy by each storage module, rather than a single global
  37  * replacement policy.
  38  *
  39  \section BuildStructure Build structure
  40  \par
  41  * The storage types live in \em src/fs/. Each subdirectory corresponds
  42  * to the name of the storage type. When a new storage type is implemented
  43  * configure.ac must be updated to autogenerate a Makefile in
  44  * \em src/fs/foo/ from a Makefile.in file.
  45  *
  46  * TODO: DOCS: add template addition to configure.ac for storage module addition.
  47  * TODO: DOCS: add template Makefile.am for storage module addition.
  48  *
  49  \par
  50  * configure will take a list of storage types through the
  51  * --enable-store-io parameter. This parameter takes a list of
  52  * space separated storage types. For example,
  53  * --enable-store-io="ufs aufs" .
  54  *
  55  \par
  56  * Each storage type must create an archive file
  57  * in \em src/fs/foo/.a . This file is automatically linked into
  58  * squid at compile time.
  59  *
  60  \par
  61  * Each storage filesystem must inherit from StoreFileSystem and provide
  62  * all virtual function hooks for squid to operate with.
  63  *
  64  \section OperationOfStorageModules Operation of a Storage Module
  65  \par
  66  *    Squid understands the concept of multiple diverse storage directories.
  67  *    Each storage directory provides a caching object store, with object
  68  *    storage, retrieval, indexing and replacement.
  69  *
  70  \par
  71  *    Each open object has associated with it a storeIOState object. The
  72  *    storeIOState object is used to record the state of the current
  73  *    object. Each storeIOState can have a storage module specific data
  74  *    structure containing information private to the storage module.
  75  *
  76  \par
  77  *    Each SwapDir has the concept of a maximum object size. This is used
  78  *    as a basic hint to the storage layer in first choosing a suitable
  79  *    SwapDir. The checkobj function is then called for suitable
  80  *    candidate SwapDirs to find out whether it wants to store a
  81  *    given StoreEntry. A maxobjsize of -1 means 'any size'.
  82  */
  83
  84 /**
  85  \ingroup FileSystems
  86  *
  87  * The core API for storage modules this class provides all the hooks
  88  * squid uses to interact with a filesystem IO module.
  89  */
  90 class StoreFileSystem: public Interface
  91 {
  92
  93 public:
  94     static void FsAdd(StoreFileSystem &);
  95     static StoreFileSystem *FindByType(const char *type);
  96     static std::vector<StoreFileSystem*> const &FileSystems();
  97     typedef std::vector<StoreFileSystem*>::iterator iterator;
  98     typedef std::vector<StoreFileSystem*>::const_iterator const_iterator;
  99
 100     StoreFileSystem() = default;
 101     StoreFileSystem(StoreFileSystem &&) = delete; // no copying/moving of any kind
 102
 103     virtual char const *type () const = 0;
 104     virtual SwapDir *createSwapDir() = 0;
 105
 106 private:
 107     static std::vector<StoreFileSystem*> &GetFileSystems();
 108     static std::vector<StoreFileSystem*> *_FileSystems;
 109 };
 110
 111 // TODO: Kill this typedef!
 112 typedef StoreFileSystem storefs_entry_t;
 113
 114 #endif /* SQUID_STOREFILESYSTEM_H */
 115