This commit was manufactured by cvs2git to create branch 'v9_4'.

lib/dns/include/dns/acache.h

@@ -0,0 +1,441 @@
+/*
+ * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
+ * Copyright (C) 2003  Internet Software Consortium.
+ *
+ * Permission to use, copy, modify, and distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
+ * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
+ * INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
+ * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
+ * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+ * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
+ * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+
+/* $Id: acache.h,v 1.3 2004/12/21 10:54:12 jinmei Exp $ */
+
+#ifndef DNS_ACACHE_H
+#define DNS_ACACHE_H 1
+
+/*****
+ ***** Module Info
+ *****/
+
+/*
+ * Acache
+ * 
+ * The Additional Cache Object
+ *
+ *	This module manages internal caching entries that correspond to
+ *	the additional section data of a DNS DB node (an RRset header, more
+ *	accurately).  An additional cache entry is expected to be (somehow)
+ *	attached to a particular RR in a particular DB node, and contains a set
+ *	of information of an additional data for the DB node.
+ *
+ *	An additional cache object is intended to be created as a per-view
+ *	object, and manages all cache entries within the view.
+ *
+ *	The intended usage of the additional caching is to provide a short cut
+ *	to additional glue RRs of an NS RR.  For each NS RR, it is often
+ *	necessary to look for glue RRs to make a proper response.  Once the
+ *	glue RRs are known, the additional caching allows the client to
+ *	associate the information to the original NS RR so that further
+ *	expensive lookups can be avoided for the NS RR.
+ *
+ *	Each additional cache entry contains information to identify a
+ *	particular DB node and (optionally) an associated RRset.  The
+ *	information consists of its zone, database, the version of the
+ *	database, database node, and RRset.
+ *
+ *	A "negative" information can also be cached.  For example, if a glue
+ *	RR does not exist as an authoritative data in the same zone as that
+ *	of the NS RR, this fact can be cached by specifying a NULL pointer
+ *	for the database, version, and node.  (See the description for
+ *	dns_acache_getentry() below for more details.)
+ *
+ *	Since each member stored in an additional cache entry holds a reference
+ *	to a corresponding object, a stale cache entry may cause unnecessary
+ *	memory consumption.  For instance, when a zone is reloaded, additional
+ *	cache entries that have a reference to the zone (and its DB and/or
+ *	DB nodes) can delay the cleanup of the referred objects.  In order to
+ *	minimize such a bad effect, this module provides several cleanup
+ *	mechanisms.
+ *
+ *	The first one is a shutdown procedure called when the associated view
+ *	is shut down.  In this case, dns_acache_shutdown() will be called and
+ *	all cache entries will be purged.  This mechanism will help the
+ *	situation when the configuration is reloaded or the main server is
+ *	stopped.
+ *
+ *	Per-DB cleanup mechanism is also provided.  Each additional cache entry
+ *	is associated with related DB, which is expected to have been
+ *	registered when the DB was created by dns_acache_setdb().  If a
+ *	particular DB is going to be destroyed, the primary holder of the DB,
+ *	a typical example of which is a zone, will call dns_acache_putdb().
+ *	Then this module will clean-up all cache entries associated with the
+ *	DB.  This mechanism is effective when a secondary zone DB is going to
+ *	be stale after a zone transfer.
+ *
+ *	Finally, this module supports for periodic clean-up of stale entries.
+ *	Each cache entry has a timestamp field, which is updated every time
+ *	the entry is referred.  A periodically invoked cleaner checks the
+ *	timestamp of each entry, and purge entries that have not been referred
+ *	for a certain period.  The cleaner interval can be specified by
+ *	dns_acache_setcleaninginterval().  If the periodic clean-up is not
+ *	enough, it is also possible to specify the upper limit of entries
+ *	in terms of the memory consumption.  If the maximum value is
+ *	specified, the cleaner is invoked when the memory consumption reaches
+ *	the high watermark inferred from the maximum value.  In this case,
+ *	the cleaner will use more aggressive algorithm to decide the "victim"
+ *	entries.  The maximum value can be specified by
+ *	dns_acache_setcachesize().
+ *
+ *	When a cache entry is going to be purged within this module, the
+ *	callback function specified at the creation time will be called.
+ *	The callback function is expected to release all internal resources
+ *	related to the entry, which will typically be specific to DB
+ *	implementation, and to call dns_acache_detachentry().  The callback
+ *	mechanism is very important, since the holder of an additional cache
+ *	entry may not be able to initiate the clean-up of the entry, due to
+ *	the reference ordering.  For example, as long as an additional cache
+ *	entry has a reference to a DB object, the DB cannot be freed, in which
+ *	a DB node may have a reference to the cache entry.
+ *
+ *	Credits:
+ *	The basic idea of this kind of short-cut for frequently used
+ *	information is similar to the "pre-compiled answer" approach adopted
+ *	in nsd by NLnet LABS with RIPE NCC.  Our work here is an independent
+ *	effort, but the success of nsd encouraged us to pursue this path.
+ *
+ *	The design and implementation of the periodic memory management and
+ *	the upper limitation of memory consumption was derived from the cache
+ *	DB implementation of BIND9.
+ *
+ * MP:
+ *	There are two main locks in this module.  One is for each entry, and
+ *	the other is for the additional cache object.
+ *
+ * Reliability:
+ *	The callback function for a cache entry is called with holding the
+ *	entry lock.  Thus, it implicitly assumes the callback function does not
+ *	call a function that can require the lock.  Typically, the only
+ *	function that can be called from the callback function safely is
+ *	dns_acache_detachentry().  The breakage of this implicit assumption
+ *	may cause a deadlock.
+ *
+ * Resources:
+ *	In a 32-bit architecture (such as i386), the following additional
+ *	memory is required comparing to the case that disables this module.
+ *	- 76 bytes for each additional cache entry
+ *	- if the entry has a DNS name and associated RRset,
+ *	  * 44 bytes + size of the name (1-255 bytes)
+ *	  * 52 bytes x number_of_RRs 
+ *	- 28 bytes for each DB related to this module
+ *
+ *	Using the additional cache also requires extra memory consumption in
+ *	the DB implementation.  In the current implementation for rbtdb, we
+ *	need:
+ *	- two additional pointers for each DB node (8 bytes for a 32-bit
+ *	  architecture
+ *	- for each RR associated to an RR in a DB node, we also need
+ *	  a pointer and management objects to support the additional cache
+ *	  function.  These are allocated on-demand.  The total size is
+ *	  32 bytes for a 32-bit architecture.
+ *
+ * Security:
+ *	Since this module does not handle any low-level data directly,
+ *	no security issue specific to this module is anticipated.
+ *
+ * Standards:
+ *	None.
+ */
+
+/***
+ *** Imports
+ ***/
+
+#include <isc/mutex.h>
+#include <isc/lang.h>
+#include <isc/refcount.h>
+#include <isc/stdtime.h>
+
+#include <dns/types.h>
+
+/***
+ *** Functions
+ ***/
+ISC_LANG_BEGINDECLS
+
+isc_result_t
+dns_acache_create(dns_acache_t **acachep, isc_mem_t *mctx,
+		  isc_taskmgr_t *taskmgr, isc_timermgr_t *timermgr);
+/*
+ * Create a new DNS additional cache object.
+ *
+ * Requires:
+ *
+ *	'mctx' is a valid memory context
+ *
+ *	'taskmgr' is a valid task manager
+ *
+ *	'timermgr' is a valid timer or NULL.  If NULL, no periodic cleaning of
+ *	the cache will take place.
+ *
+ *	'acachep' is a valid pointer, and *acachep == NULL
+ *
+ * Ensures:
+ *
+ *	'*acachep' is attached to the newly created cache
+ *
+ * Returns:
+ *
+ *	ISC_R_SUCCESS
+ *	ISC_R_NOMEMORY
+ *	ISC_R_UNEXPECTED
+ */
+
+void
+dns_acache_attach(dns_acache_t *source, dns_acache_t **targetp);
+/*
+ * Attach *targetp to cache.
+ *
+ * Requires:
+ *
+ *	'acache' is a valid additional cache.
+ *
+ *	'targetp' points to a NULL dns_acache_t *.
+ *
+ * Ensures:
+ *
+ *	*targetp is attached to the 'source' additional cache.
+ */
+
+void
+dns_acache_detach(dns_acache_t **acachep);
+/*
+ * Detach *acachep from its cache.
+ *
+ * Requires:
+ *
+ *	'*acachep' points to a valid additional cache.
+ *
+ * Ensures:
+ *
+ *	*acachep is NULL.
+ *
+ *	If '*acachep' is the last reference to the cache and the additional
+ *	cache does not have an outstanding task, all resources used by the
+ *	cache will be freed.
+ */
+
+void
+dns_acache_setcleaninginterval(dns_acache_t *acache, unsigned int t);
+/*
+ * Set the periodic cleaning interval of an additional cache to 'interval'
+ * seconds.
+ */
+
+void
+dns_acache_setcachesize(dns_acache_t *acache, isc_uint32_t size);
+/*
+ * Set the maximum additional cache size.  0 means unlimited.
+ */
+
+isc_result_t
+dns_acache_setdb(dns_acache_t *acache, dns_db_t *db);
+/*
+ * Set 'db' in 'acache' when the db can be referred from acache, in order
+ * to provide a hint for resolving the back reference.
+ *
+ * Requires:
+ *	'acache' is a valid acache pointer.
+ *	'db' is a valid DNS DB pointer.
+ *
+ * Ensures:
+ *	'acache' will have a reference to 'db'.
+ *
+ * Returns:
+ *	ISC_R_SUCCESS
+ *	ISC_R_EXISTS	(which means the specified 'db' is already set)
+ *	ISC_R_NOMEMORY
+ */
+
+isc_result_t
+dns_acache_putdb(dns_acache_t *acache, dns_db_t *db);
+/*
+ * Release 'db' from 'acache' if it has been set by dns_acache_setdb().
+ *
+ * Requires:
+ *	'acache' is a valid acache pointer.
+ *	'db' is a valid DNS DB pointer.
+ *
+ * Ensures:
+ *	'acache' will release the reference to 'db'.  Additionally, the content
+ *	of each cache entry that is related to the 'db' will be released via
+ *	the callback function.
+ *
+ * Returns:
+ *	ISC_R_SUCCESS
+ *	ISC_R_NOTFOUND	(which means the specified 'db' is not set in 'acache')
+ *	ISC_R_NOMEMORY
+ */
+
+void
+dns_acache_shutdown(dns_acache_t *acache);
+/*
+ * Shutdown 'acache'.
+ *
+ * Requires:
+ *
+ * 	'*acache' is a valid additional cache.
+ */
+
+isc_result_t
+dns_acache_createentry(dns_acache_t *acache, dns_db_t *origdb,
+		       void (*callback)(dns_acacheentry_t *, void **),
+		       void *cbarg, dns_acacheentry_t **entryp);
+/*
+ * Create an additional cache entry.  A new entry is created and attached to
+ * the given additional cache object.  A callback function is also associated
+ * with the created entry, which will be called when the cache entry is purged
+ * for some reason.
+ *
+ * Requires:
+ *
+ * 	'acache' is a valid additional cache.
+ *	'entryp' is a valid pointer, and *entryp == NULL
+ *	'origdb' is a valid DNS DB pointer.
+ *	'callback' and 'cbarg' can be NULL.  In this case, however, the entry
+ *	is meaningless (and will be cleaned-up in the next periodical
+ *	cleaning).
+ *
+ * Ensures:
+ *	'*entryp' will point to a new additional cache entry.
+ *
+ * Returns:
+ *	ISC_R_SUCCESS
+ *	ISC_R_NOMEMORY
+ */
+
+isc_result_t
+dns_acache_getentry(dns_acacheentry_t *entry, dns_zone_t **zonep,
+		    dns_db_t **dbp, dns_dbversion_t **versionp,
+		    dns_dbnode_t **nodep, dns_name_t *fname,
+		    dns_message_t *msg, isc_stdtime_t now);
+/*
+ * Get content from a particular additional cache entry.
+ *
+ * Requires:
+ *
+ * 	'entry' is a valid additional cache entry.
+ *	'zonep' is a NULL pointer or '*zonep' == NULL (this is the only
+ *	optional parameter.)
+ *	'dbp' is a valid pointer, and '*dbp' == NULL
+ *	'versionp' is a valid pointer, and '*versionp' == NULL
+ *	'nodep' is a valid pointer, and '*nodep' == NULL
+ *	'fname' is a valid DNS name.
+ *	'msg' is a valid DNS message.
+ *
+ * Ensures:
+ *	Several possible cases can happen according to the content.
+ *	1. For a positive cache entry,
+ *	'*zonep' will point to the corresponding zone (if zonep is a valid
+ *	pointer),
+ *	'*dbp' will point to a DB for the zone,
+ *	'*versionp' will point to its version, and
+ *	'*nodep' will point to the corresponding DB node.
+ *	'fname' will have the DNS name of the DB node and contain a list of
+ *	rdataset for the node (which can be an empty list).
+ *
+ * 	2. For a negative cache entry that means no corresponding zone exists,
+ *	'*zonep' == NULL (if zonep is a valid pointer)
+ *	'*dbp', '*versionp', and '*nodep' will be NULL.
+ *
+ *	3. For a negative cache entry that means no corresponding DB node
+ *	exists, '*zonep' will point to the corresponding zone (if zonep is a
+ *	valid pointer),
+ *	'*dbp' will point to a corresponding DB for zone,
+ *	'*versionp' will point to its version.
+ *	'*nodep' will be kept as NULL.
+ *	'fname' will not change.
+ *
+ *	On failure, no new references will be created.
+ *
+ * Returns:
+ *	ISC_R_SUCCESS
+ *	ISC_R_NOMEMORY
+ */
+
+isc_result_t
+dns_acache_setentry(dns_acache_t *acache, dns_acacheentry_t *entry,
+		    dns_zone_t *zone, dns_db_t *db, dns_dbversion_t *version,
+		    dns_dbnode_t *node, dns_name_t *fname);
+/*
+ * Set content to a particular additional cache entry.
+ *
+ * Requires:
+ *	'acache' is a valid additional cache.
+ *	'entry' is a valid additional cache entry.
+ *	All the others pointers are NULL or a valid pointer of the
+ *	corresponding type.
+ *
+ * Returns:
+ *	ISC_R_SUCCESS
+ *	ISC_R_NOMEMORY
+ *	ISC_R_NOTFOUND
+ */
+
+void
+dns_acache_cancelentry(dns_acacheentry_t *entry);
+/*
+ * Cancel the use of the cache entry 'entry'.  This function is supposed to
+ * be called when the node that holds the entry finds the content is not
+ * correct any more.  This function will try to release as much dependency as
+ * possible, and will be ready to be cleaned-up.  The registered callback
+ * function will be canceled and will never called.
+ *
+ * Requires:
+ *	'entry' is a valid additional cache entry.
+ */
+
+void
+dns_acache_attachentry(dns_acacheentry_t *source, dns_acacheentry_t **targetp);
+/*
+ * Attach *targetp to the cache entry 'source'.
+ *
+ * Requires:
+ *
+ *	'source' is a valid additional cache entry.
+ *
+ *	'targetp' points to a NULL dns_acacheentry_t *.
+ *
+ * Ensures:
+ *
+ *	*targetp is attached to 'source'.
+ */
+		       
+void
+dns_acache_detachentry(dns_acacheentry_t **entryp);
+/*
+ * Detach *entryp from its cache.
+ *
+ * Requires:
+ *
+ *	'*entryp' points to a valid additional cache entry.
+ *
+ * Ensures:
+ *
+ *	*entryp is NULL.
+ *
+ *	If '*entryp' is the last reference to the entry, 
+ *	cache does not have an outstanding task, all resources used by the
+ *	entry (including the entry object itself) will be freed.
+ */
+
+ISC_LANG_ENDDECLS
+
+#endif /* DNS_ACACHE_H */