From: Amos Jeffries <squid3@treenet.co.nz>
Date: Mon, 21 Apr 2008 12:52:20 +0000 (+1200)
Subject: Import FileSystem component API documentation. (really)
X-Git-Tag: SQUID_3_1_0_1~49^2~279
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=4d95a996b50e41d891064a0b55e05fa0cf0d0813;p=thirdparty%2Fsquid.git

Import FileSystem component API documentation. (really)
---

diff --git a/src/StoreFileSystem.h b/src/StoreFileSystem.h
index 39602dcc11..ddd87a0928 100644
--- a/src/StoreFileSystem.h
+++ b/src/StoreFileSystem.h
@@ -38,13 +38,81 @@
 
 /* ****** DOCUMENTATION ***** */
 
-
-/* forward decls */
+/**
+ \defgroup FileSystems	Storage Filesystems
+ * 
+ \section Introduction 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.in must be updated to autogenerate a Makefile in
+ * \em src/fs/foo/ from a Makefile.in file.
+ *
+ \todo DOCS: add template addition to configure.in 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 seperated storage types. For example,
+ * --enable-store-io="ufs coss" .
+ * 
+ \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'.
+ */
 
 class CacheManager;
-
 class SwapDir;
 
+/**
+ \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
 {
 
@@ -77,6 +145,7 @@ private:
     static Vector<StoreFileSystem*> *_FileSystems;
 };
 
+// TODO: Kill this typedef!
 typedef StoreFileSystem storefs_entry_t;