--------------------- PatchSet 5194 Date: 2007/08/08 09:04:09 Author: amosjeffries Branch: docs Tag: (none) Log: Migrate IP/FQDN Cache docs to the FQDN code. Members: doc/Programming-Guide/14_IPCacheAndFQDNCache.dox:1.1.2.1->1.1.2.2(DEAD) src/fqdncache.cc:1.19->1.19.2.1 --- squid3/doc/Programming-Guide/14_IPCacheAndFQDNCache.dox Thu Aug 9 00:19:41 2007 +++ /dev/null Thu Aug 9 00:19:41 2007 @@ -1,78 +0,0 @@ -/** -\page 14_IPCacheAndFQDNCache IP Cache and FQDN Cache - -\section Introduction Introduction - -\par - The IP cache is a built-in component of squid providing - Hostname to IP-Number translation functionality and managing - the involved data-structures. Efficiency concerns require - mechanisms that allow non-blocking access to these mappings. - The IP cache usually doesn't block on a request except for - special cases where this is desired (see below). - -\section DataStructures Data Structures - -\par - The data structure used for storing name-address mappings - is a small hashtable (static hash_table *ip_table), - where structures of type ipcache_entry whose most - interesting members are: -\code - struct _ipcache_entry { - char *name; - time_t lastref; - ipcache_addrs addrs; - struct _ip_pending *pending_head; - char *error_message; - unsigned char locks; - ipcache_status_t status:3; - } -\endcode - -\section ExternalOverview External Overview - -\par - Main functionality is provided through calls to: - -\par ipcache_nbgethostbyname(const char *name, IPH *handler, void *handlerdata) - Where name is the name of the host to resolve, - handler is a pointer to the function to be called when - the reply from the IP cache (or the DNS if the IP cache - misses) and handlerdata is information that is passed - to the handler and does not affect the IP cache. - -\par ipcache_gethostbyname(const char *name,int flags) - is different in that it only checks if an entry exists in - it's data-structures and does not by default contact the - DNS, unless this is requested, by setting the flags - to IP_BLOCKING_LOOKUP or IP_LOOKUP_IF_MISS. - -\par ipcache_init() - is called from mainInitialize() - after disk initialization and prior to the reverse fqdn - cache initialization - -\par ipcache_restart() - is called to clear the IP - cache's data structures, cancel all pending requests. - Currently, it is only called from mainReconfigure. - - -\section InternalOperation Internal Operation - -\par - Internally, the execution flow is as follows: On a miss, - ipcache_getnbhostbyname checks whether a request for - this name is already pending, and if positive, it creates - a new entry using ipcacheAddNew with the IP_PENDING - flag set . Then it calls ipcacheAddPending to add a - request to the queue together with data and handler. Else, - ipcache_dnsDispatch() is called to directly create a - DNS query or to ipcacheEnqueue() if all no DNS port - is free. ipcache_call_pending() is called regularly - to walk down the pending list and call handlers. LRU clean-up - is performed through ipcache_purgelru() according to - the ipcache_high threshold. - - */ Index: squid3/src/fqdncache.cc =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/fqdncache.cc,v retrieving revision 1.19 retrieving revision 1.19.2.1 diff -u -r1.19 -r1.19.2.1 --- squid3/src/fqdncache.cc 28 Apr 2007 22:51:52 -0000 1.19 +++ squid3/src/fqdncache.cc 8 Aug 2007 09:04:10 -0000 1.19.2.1 @@ -1,6 +1,5 @@ - /* - * $Id: fqdncache.cc,v 1.19 2007/04/28 22:51:52 squidadm Exp $ + * $Id: fqdncache.cc,v 1.19.2.1 2007/08/08 09:04:10 amosjeffries Exp $ * * DEBUG: section 35 FQDN Cache * AUTHOR: Harvest Derived @@ -41,11 +40,62 @@ #include "Store.h" #include "wordlist.h" +/** + \defgroup FQDNCache FQDN Cache + \ingroup Components + */ + +/** + \defgroup FQDNCacheAPI FQDN Cache API + \ingroup FQDNCache + \section Introduction Introduction + \par + * The FQDN cache is a built-in component of squid providing + * Hostname to IP-Number translation functionality and managing + * the involved data-structures. Efficiency concerns require + * mechanisms that allow non-blocking access to these mappings. + * The FQDN cache usually doesn't block on a request except for + * special cases where this is desired (see below). + */ + +/** + \defgroup FQDNCacheInternal FQDN Cache Internals + \ingroup FQDNCache + \par + * Internally, the execution flow is as follows: + * On a miss, fqdncache_nbgethostbyaddr() checks whether a request + * for this name is already pending, and if positive, it creates a + * new entry using fqdncacheAddEntry(). Then it calls + * fqdncacheAddPending() to add a request to the queue together + * with data and handler. Else, ifqdncache_dnsDispatch() is called + * to directly create a DNS query or to fqdncacheEnqueue() if all + * no DNS port is free. + * + \par + * fqdncacheCallback() is called regularly to walk down the pending + * list and call handlers. + * + \par + * LRU clean-up is performed through fqdncache_purgelru() according + * to the fqdncache_high threshold. + */ + +/// \ingroup FQDNCacheInternal #define FQDN_LOW_WATER 90 + +/// \ingroup FQDNCacheInternal #define FQDN_HIGH_WATER 95 +/// \ingroup FQDNCacheAPI typedef struct _fqdncache_entry fqdncache_entry; +/** + \ingroup FQDNCacheAPI + * The data structure used for storing name-address mappings + * is a small hashtable (static hash_table *fqdn_table), + * where structures of type fqdncache_entry whose most + * interesting members are: + */ struct _fqdncache_entry { hash_link hash; /* must be first */ @@ -74,7 +124,8 @@ flags; }; -static struct +/// \ingroup FQDNCacheInternal +static struct _fqdn_cache_stats { int requests; int replies; @@ -82,9 +133,9 @@ int misses; int negative_hits; } - FqdncacheStats; +/// \ingroup FQDNCacheInternal static dlink_list lru_list; #if USE_DNSSERVERS @@ -105,12 +156,19 @@ static FREE fqdncacheFreeEntry; static void fqdncacheAddEntry(fqdncache_entry * f); +/// \ingroup FQDNCacheInternal static hash_table *fqdn_table = NULL; +/// \ingroup FQDNCacheInternal static long fqdncache_low = 180; + +/// \ingroup FQDNCacheInternal static long fqdncache_high = 200; -/* removes the given fqdncache entry */ +/** + \ingroup FQDNCacheInternal + * Removes the given fqdncache entry + */ static void fqdncacheRelease(fqdncache_entry * f) { @@ -131,7 +189,11 @@ memFree(f, MEM_FQDNCACHE_ENTRY); } -/* return match for given name */ +/** + \ingroup FQDNCacheInternal + \param name FQDN hash string. + \retval Match for given name + */ static fqdncache_entry * fqdncache_get(const char *name) { @@ -147,6 +209,7 @@ return f; } +/// \ingroup FQDNCacheInternal static int fqdncacheExpiredEntry(const fqdncache_entry * f) { @@ -161,6 +224,7 @@ return 1; } +/// \ingroup FQDNCacheAPI void fqdncache_purgelru(void *notused) { @@ -189,6 +253,7 @@ debugs(35, 9, "fqdncache_purgelru: removed " << removed << " entries"); } +/// \ingroup FQDNCacheAPI static void purge_entries_fromhosts(void) { @@ -214,7 +279,10 @@ fqdncacheRelease(i); } -/* create blank fqdncache_entry */ +/** + * \ingroup FQDNCacheInternal + * Create blank fqdncache_entry + */ static fqdncache_entry * fqdncacheCreateEntry(const char *name) { @@ -225,6 +293,7 @@ return f; } +/// \ingroup FQDNCacheInternal static void fqdncacheAddEntry(fqdncache_entry * f) { @@ -241,7 +310,10 @@ f->lastref = squid_curtime; } -/* walks down the pending list, calling handlers */ +/** + * \ingroup FQDNCacheInternal + * Walks down the pending list, calling handlers + */ static void fqdncacheCallback(fqdncache_entry * f) { @@ -266,6 +338,7 @@ fqdncacheUnlockEntry(f); } +/// \ingroup FQDNCacheInternal #if USE_DNSSERVERS static int fqdncacheParse(fqdncache_entry *f, const char *inbuf) @@ -412,6 +485,10 @@ #endif +/** + * \ingroup FQDNCacheAPI + * Callback for handling DNS results. + */ static void #if USE_DNSSERVERS fqdncacheHandleReply(void *data, char *reply) @@ -439,8 +516,17 @@ fqdncacheCallback(f); } +/** + * \ingroup FQDNCacheAPI + * + * \param addr IP address of domain to resolve. + * \param handler A pointer to the function to be called when + * the reply from the FQDN cache + * (or the DNS if the FQDN cache misses) + * \param handlerdata Information that is passed to the handler + * and does not affect the FQDN cache. + */ void - fqdncache_nbgethostbyaddr(struct IN_ADDR addr, FQDNH * handler, void *handlerData) { fqdncache_entry *f = NULL; @@ -504,7 +590,11 @@ #endif } -/* initialize the fqdncache */ +/** + * \ingroup FQDNCacheAPI + * Initialize the fqdncache. + * Called after IP cache initialization. + */ void fqdncache_init(void) { @@ -533,6 +623,7 @@ sizeof(fqdncache_entry), 0); } +/// \ingroup FQDNCacheAPI void fqdncacheRegisterWithCacheManager(CacheManager & manager) { @@ -542,8 +633,18 @@ } +/** + * \ingroup FQDNCacheAPI + * Is different in that it only checks if an entry exists in + * it's data-structures and does not by default contact the + * DNS, unless this is requested, by setting the flags + * to FQDN_LOOKUP_IF_MISS. + * + * \param addr address of the FQDN being resolved + * \param flags values are NULL or FQDN_LOOKUP_IF_MISS. default is NULL. + * + */ const char * - fqdncache_gethostbyaddr(struct IN_ADDR addr, int flags) { char *name = inet_ntoa(addr); @@ -590,7 +691,10 @@ } -/* process objects list */ +/** + * \ingroup FQDNCacheInternal + * Process objects list + */ void fqdnStats(StoreEntry * sentry) { @@ -641,14 +745,15 @@ } } +/// \ingroup FQDNCacheInternal static void dummy_handler(const char *bufnotused, void *datanotused) { return; } +/// \ingroup FQDNCacheAPI const char * - fqdnFromAddr(struct IN_ADDR addr) { const char *n; @@ -662,6 +767,7 @@ return buf; } +/// \ingroup FQDNCacheInternal static void fqdncacheLockEntry(fqdncache_entry * f) { @@ -671,6 +777,7 @@ } } +/// \ingroup FQDNCacheInternal static void fqdncacheUnlockEntry(fqdncache_entry * f) { @@ -681,6 +788,7 @@ fqdncacheRelease(f); } +/// \ingroup FQDNCacheInternal static void fqdncacheFreeEntry(void *data) { @@ -697,6 +805,7 @@ memFree(f, MEM_FQDNCACHE_ENTRY); } +/// \ingroup FQDNCacheAPI void fqdncacheFreeMemory(void) { @@ -705,7 +814,12 @@ fqdn_table = NULL; } -/* Recalculate FQDN cache size upon reconfigure */ +/** + * \ingroup FQDNCacheAPI + * Recalculate FQDN cache size upon reconfigure. + * Is called to clear the FQDN cache's data structures, + * cancel all pending requests. + */ void fqdncache_restart(void) { @@ -716,7 +830,8 @@ purge_entries_fromhosts(); } -/* +/** + * \ingroup FQDNCacheAPI * adds a "static" entry from /etc/hosts. the worldist is to be * managed by the caller, including pointed-to strings */ @@ -757,10 +872,10 @@ #ifdef SQUID_SNMP -/* - * The function to return the fqdn statistics via SNMP +/** + * \ingroup FQDNCacheAPI + * The function to return the FQDN statistics via SNMP */ - variable_list * snmp_netFqdnFn(variable_list * Var, snint * ErrP) {