--------------------- PatchSet 5391 Date: 2007/08/20 01:11:41 Author: amosjeffries Branch: docs Tag: (none) Log: Move docs for swap.state format into source. Members: doc/Programming-Guide/27_MiscOther.dox:1.1.2.5->1.1.2.6 src/StoreSwapLogData.h:1.3.26.2->1.3.26.3 src/typedefs.h:1.45.2.1->1.45.2.2 Index: squid3/doc/Programming-Guide/27_MiscOther.dox =================================================================== RCS file: /cvsroot/squid-sf//squid3/doc/Programming-Guide/Attic/27_MiscOther.dox,v retrieving revision 1.1.2.5 retrieving revision 1.1.2.6 diff -u -r1.1.2.5 -r1.1.2.6 --- squid3/doc/Programming-Guide/27_MiscOther.dox 20 Aug 2007 00:24:02 -0000 1.1.2.5 +++ squid3/doc/Programming-Guide/27_MiscOther.dox 20 Aug 2007 01:11:41 -0000 1.1.2.6 @@ -3,86 +3,6 @@ \section FileFormats File Formats -\subsection swap.state swap.state -\note This information is current as of version 2.2.STABLE4. - -\par - A swap.state entry is defined by the storeSwapLogData - structure, and has the following elements: -\code - struct _storeSwapLogData { - char op; - int swap_file_number; - time_t timestamp; - time_t lastref; - time_t expires; - time_t lastmod; - size_t swap_file_sz; - u_short refcount; - u_short flags; - unsigned char key[MD5_DIGEST_CHARS]; - }; -\endcode - - -\par op - Either SWAP_LOG_ADD (1) when an object is added to - the disk storage, or SWAP_LOG_DEL (2) when an object is - deleted. - -\par swap_file_number - The 32-bit file number which maps to a pathname. Only - the low 24-bits are relevant. The high 8-bits are - used as an index to an array of storage directories, and - are set at run time because the order of storage directories - may change over time. - -\par timestamp - A 32-bit Unix time value that represents the time when - the origin server generated this response. If the response - has a valid Date: header, this timestamp corresponds - to that time. Otherwise, it is set to the Squid process time - when the response is read (as soon as the end of headers are - found). - -\par lastref - The last time that a client requested this object. - Strictly speaking, this time is set whenver the StoreEntry - is locked (via storeLockObject()). - -\par expires - The value of the response's Expires: header, if any. - If the response does not have an Expires: header, this - is set to -1. If the response has an invalid (unparseable) - Expires: header, it is also set to -1. There are some cases - where Squid sets expires to -2. This happens for the - internal ``netdb'' object and for FTP URL responses. - -\par lastmod - The value of the response's Last-modified: header, if any. - This is set to -1 if there is no Last-modified: header, - or if it is unparseable. - -\par swap_file_sz - This is the number of bytes that the object occupies on - disk. It includes the Squid "swap file header". - -\par refcount - The number of times that this object has been accessed (referenced). - Since its a 16-bit quantity, it is susceptible to overflow - if a single object is accessed 65,536 times before being replaced. - -\par flags - A copy of the StoreEntry flags field. Used as a sanity - check when rebuilding the cache at startup. Objects that - have the KEY_PRIVATE flag set are not added back to the cache. - -\par key - The 128-bit MD5 hash for this object. - -\note storeSwapLogData entries are written in native machine - byte order. They are not necessarily portable across architectures. - \section StoreSwapMeta Store "swap meta" Description \par "swap meta" refers to a section of meta data stored at the beginning Index: squid3/src/StoreSwapLogData.h =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/StoreSwapLogData.h,v retrieving revision 1.3.26.2 retrieving revision 1.3.26.3 diff -u -r1.3.26.2 -r1.3.26.3 --- squid3/src/StoreSwapLogData.h 15 Aug 2007 01:00:02 -0000 1.3.26.2 +++ squid3/src/StoreSwapLogData.h 20 Aug 2007 01:11:41 -0000 1.3.26.3 @@ -1,6 +1,5 @@ - /* - * $Id: StoreSwapLogData.h,v 1.3.26.2 2007/08/15 01:00:02 amosjeffries Exp $ + * $Id: StoreSwapLogData.h,v 1.3.26.3 2007/08/20 01:11:41 amosjeffries Exp $ * * SQUID Web Proxy Cache http://www.squid-cache.org/ * ---------------------------------------------------------- @@ -34,37 +33,116 @@ #ifndef SQUID_STORESWAPLOGDATA_H #define SQUID_STORESWAPLOGDATA_H +/** + \defgroup SwapStateAPI swap.state file Structure + \ingroup FileSystems + */ + #include "squid.h" /* * Do we need to have the dirn in here? I don't think so, since we already * know the dirn .. */ -/* Binary format on disk. - * DO NOT randomly alter. - * DO NOT add ANY virtual's. +/** + \ingroup SwapStateAPI + \note This information is current as of version 2.2.STABLE4 + * + \li Binary format on disk. + \li DO NOT randomly alter. + \li DO NOT add ANY virtual's. + * + \par + * Defines the structure of a binary swap.state file entry. + * + \note StoreSwapLogData entries are written in native machine byte order + * They are not necessarily portable across architectures. */ - class StoreSwapLogData { public: MEMPROXY_CLASS(StoreSwapLogData); StoreSwapLogData(); + + /** + * Either SWAP_LOG_ADD when an object is added to the disk storage, + * or SWAP_LOG_DEL when an object is deleted. + */ char op; + + /** + * The 32-bit file number which maps to a pathname. + * Only the low 24-bits are relevant. The high 8-bits are + * used as an index to an array of storage directories, and + * are set at run time because the order of storage directories + * may change over time. + */ sfileno swap_filen; + + /** + * A 32-bit Unix time value that represents the time when + * the origin server generated this response. If the response + * has a valid Date: header, this timestamp corresponds + * to that time. Otherwise, it is set to the Squid process time + * when the response is read (as soon as the end of headers are found). + */ time_t timestamp; + + /** + * The last time that a client requested this object. + * Strictly speaking, this time is set whenever the StoreEntry + * is locked (via storeLockObject()). + */ time_t lastref; + + /** + * The value of the response's Expires: header, if any. + * If the response does not have an Expires: header, this + * is set to -1. + * If the response has an invalid (unparseable) + * Expires: header, it is also set to -1. There are some cases + * where Squid sets expires to -2. This happens for the + * internal "netdb" object and for FTP URL responses. + */ time_t expires; + + /** + * The value of the response's Last-modified: header, if any. + * This is set to -1 if there is no Last-modified: header, + * or if it is unparseable. + */ time_t lastmod; + + /** + * This is the number of bytes that the object occupies on + * disk. It includes the Squid "swap file header". + */ uint64_t swap_file_sz; + + /** + * The number of times that this object has been accessed (referenced). + * Since its a 16-bit quantity, it is susceptible to overflow + * if a single object is accessed 65,536 times before being replaced. + */ u_short refcount; + + /** + * A copy of the StoreEntry flags field. Used as a sanity + * check when rebuilding the cache at startup. Objects that + * have the KEY_PRIVATE flag set are not added back to the cache. + */ u_short flags; + + /** + * The 128-bit MD5 hash for this object. + */ unsigned char key[MD5_DIGEST_CHARS]; }; MEMPROXY_CLASS_INLINE(StoreSwapLogData) /**DOCS_NOSEMI*/ +/// \ingroup SwapStateAPI class StoreSwapLogHeader { public: Index: squid3/src/typedefs.h =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/typedefs.h,v retrieving revision 1.45.2.1 retrieving revision 1.45.2.2 diff -u -r1.45.2.1 -r1.45.2.2 --- squid3/src/typedefs.h 10 Aug 2007 03:44:40 -0000 1.45.2.1 +++ squid3/src/typedefs.h 20 Aug 2007 01:11:41 -0000 1.45.2.2 @@ -1,6 +1,6 @@ /* - * $Id: typedefs.h,v 1.45.2.1 2007/08/10 03:44:40 amosjeffries Exp $ + * $Id: typedefs.h,v 1.45.2.2 2007/08/20 01:11:41 amosjeffries Exp $ * * * SQUID Web Proxy Cache http://www.squid-cache.org/ @@ -188,6 +188,7 @@ typedef struct _StatCounters StatCounters; +/// \todo DROP: deprecated and no longer used. typedef struct _storeSwapLogData storeSwapLogData; typedef struct _StatHist StatHist;