[thirdparty/squid.git] / src / StoreFileSystem.h

/*
 * 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_STOREFILESYSTEM_H
#define SQUID_SRC_STOREFILESYSTEM_H

#include "base/TypeTraits.h"
#include "store/forward.h"
#include <vector>

/* ****** DOCUMENTATION ***** */

/**
 \defgroup FileSystems  Storage Filesystems
 *
 \section FileSystemsIntroduction Introduction
 \par
 * Traditionally, Squid has always used the Unix filesystem (\link UFS UFS\endlink)
 * to store cache objects on disk.  Over the years, the
 * poor performance of \link UFS UFS\endlink has become very obvious.  In most
 * cases, \link UFS UFS\endlink limits Squid to about 30-50 requests per second.
 * Our work indicates that the poor performance is mostly
 * due to the synchronous nature of open() and unlink()
 * system calls, and perhaps thrashing of inode/buffer caches.
 *
 \par
 * We want to try out our own, customized filesystems with Squid.
 * In order to do that, we need a well-defined interface
 * for the bits of Squid that access the permanent storage
 * devices. We also require tighter control of the replacement
 * policy by each storage module, rather than a single global
 * replacement policy.
 *
 \section BuildStructure Build structure
 \par
 * The storage types live in \em src/fs/. Each subdirectory corresponds
 * to the name of the storage type. When a new storage type is implemented
 * configure.ac must be updated to autogenerate a Makefile in
 * \em src/fs/foo/ from a Makefile.in file.
 *
 * TODO: DOCS: add template addition to configure.ac for storage module addition.
 * TODO: DOCS: add template Makefile.am for storage module addition.
 *
 \par
 * configure will take a list of storage types through the
 * --enable-store-io parameter. This parameter takes a list of
 * space separated storage types. For example,
 * --enable-store-io="ufs aufs" .
 *
 \par
 * Each storage type must create an archive file
 * in \em src/fs/foo/.a . This file is automatically linked into
 * squid at compile time.
 *
 \par
 * Each storage filesystem must inherit from StoreFileSystem and provide
 * all virtual function hooks for squid to operate with.
 *
 \section OperationOfStorageModules Operation of a Storage Module
 \par
 *    Squid understands the concept of multiple diverse storage directories.
 *    Each storage directory provides a caching object store, with object
 *    storage, retrieval, indexing and replacement.
 *
 \par
 *    Each open object has associated with it a storeIOState object. The
 *    storeIOState object is used to record the state of the current
 *    object. Each storeIOState can have a storage module specific data
 *    structure containing information private to the storage module.
 *
 \par
 *    Each SwapDir has the concept of a maximum object size. This is used
 *    as a basic hint to the storage layer in first choosing a suitable
 *    SwapDir. The checkobj function is then called for suitable
 *    candidate SwapDirs to find out whether it wants to store a
 *    given StoreEntry. A maxobjsize of -1 means 'any size'.
 */

/**
 \ingroup FileSystems
 *
 * The core API for storage modules this class provides all the hooks
 * squid uses to interact with a filesystem IO module.
 */
class StoreFileSystem: public Interface
{

public:
    static void FsAdd(StoreFileSystem &);
    static StoreFileSystem *FindByType(const char *type);
    static std::vector<StoreFileSystem*> const &FileSystems();
    typedef std::vector<StoreFileSystem*>::iterator iterator;
    typedef std::vector<StoreFileSystem*>::const_iterator const_iterator;

    StoreFileSystem() = default;
    StoreFileSystem(StoreFileSystem &&) = delete; // no copying/moving of any kind

    virtual char const *type () const = 0;
    virtual SwapDir *createSwapDir() = 0;

private:
    static std::vector<StoreFileSystem*> &GetFileSystems();
    static std::vector<StoreFileSystem*> *_FileSystems;
};

// TODO: Kill this typedef!
typedef StoreFileSystem storefs_entry_t;

#endif /* SQUID_SRC_STOREFILESYSTEM_H */
Commit	Line	Data
	1	/*
	2	* Copyright (C) 1996-2025 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_SRC_STOREFILESYSTEM_H
	10	#define SQUID_SRC_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_SRC_STOREFILESYSTEM_H */
	115