src/StoreFileSystem.h

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