cache.h File Reference

Defines dns_cache_t, the cache object. More...

#include <isc/json.h>
#include <isc/lang.h>
#include <isc/stats.h>
#include <isc/stdtime.h>
#include <dns/types.h>

Go to the source code of this file.

Defines

#define DNS_CACHE_H 1

Functions

ISC_LANG_BEGINDECLS isc_result_t dns_cache_create (isc_mem_t *cmctx, isc_taskmgr_t *taskmgr, isc_timermgr_t *timermgr, dns_rdataclass_t rdclass, const char *db_type, unsigned int db_argc, char **db_argv, dns_cache_t **cachep)

isc_result_t dns_cache_create2 (isc_mem_t *cmctx, isc_taskmgr_t *taskmgr, isc_timermgr_t *timermgr, dns_rdataclass_t rdclass, const char *cachename, const char *db_type, unsigned int db_argc, char **db_argv, dns_cache_t **cachep)

isc_result_t dns_cache_create3 (isc_mem_t *cmctx, isc_mem_t *hmctx, isc_taskmgr_t *taskmgr, isc_timermgr_t *timermgr, dns_rdataclass_t rdclass, const char *cachename, const char *db_type, unsigned int db_argc, char **db_argv, dns_cache_t **cachep)

Create a new DNS cache.

void dns_cache_attach (dns_cache_t *cache, dns_cache_t **targetp)

Attach *targetp to cache.

void dns_cache_detach (dns_cache_t **cachep)

Detach *cachep from its cache.

void dns_cache_attachdb (dns_cache_t *cache, dns_db_t **dbp)

Attach *dbp to the cache's database.

isc_result_t dns_cache_setfilename (dns_cache_t *cache, const char *filename)

If 'filename' is non-NULL, make the cache persistent. The cache's data will be stored in the given file. If 'filename' is NULL, make the cache non-persistent. Files that are no longer used are not unlinked automatically.

isc_result_t dns_cache_load (dns_cache_t *cache)

If the cache has a file name, load the cache contents from the file. Previous cache contents are not discarded. If no file name has been set, do nothing and return success.

isc_result_t dns_cache_dump (dns_cache_t *cache)

If the cache has a file name, write the cache contents to disk, overwriting any preexisting file. If no file name has been set, do nothing and return success.

isc_result_t dns_cache_clean (dns_cache_t *cache, isc_stdtime_t now)

Force immediate cleaning of the cache, freeing all rdatasets whose TTL has expired as of 'now' and that have no pending references.

void dns_cache_setcleaninginterval (dns_cache_t *cache, unsigned int interval)

Set the periodic cache cleaning interval to 'interval' seconds.

unsigned int dns_cache_getcleaninginterval (dns_cache_t *cache)

Get the periodic cache cleaning interval to 'interval' seconds.

const char * dns_cache_getname (dns_cache_t *cache)

Get the cache name.

void dns_cache_setcachesize (dns_cache_t *cache, size_t size)

Set the maximum cache size. 0 means unlimited.

size_t dns_cache_getcachesize (dns_cache_t *cache)

Get the maximum cache size.

isc_result_t dns_cache_flush (dns_cache_t *cache)

Flushes all data from the cache.

isc_result_t dns_cache_flushnode (dns_cache_t *cache, dns_name_t *name, isc_boolean_t tree)

isc_result_t dns_cache_flushname (dns_cache_t *cache, dns_name_t *name)

isc_stats_t * dns_cache_getstats (dns_cache_t *cache)

void dns_cache_dumpstats (dns_cache_t *cache, FILE *fp)

void dns_cache_updatestats (dns_cache_t *cache, isc_result_t result)

Detailed Description

Defines dns_cache_t, the cache object.

Notes:

A cache object contains DNS data of a single class. Multiple classes will be handled by creating multiple views, each with a different class and its own cache.

MP:

See notes at the individual functions.

Reliability:

Resources:

Security:

Standards:

Definition in file cache.h.

Define Documentation

#define DNS_CACHE_H 1

Definition at line 21 of file cache.h.

Function Documentation

ISC_LANG_BEGINDECLS isc_result_t dns_cache_create	(	isc_mem_t *	cmctx,
		isc_taskmgr_t *	taskmgr,
		isc_timermgr_t *	timermgr,
		dns_rdataclass_t	rdclass,
		const char *	db_type,
		unsigned int	db_argc,
		char **	db_argv,
		dns_cache_t **	cachep
	)

Definition at line 180 of file cache.c.

References dns_cache_create3().

isc_result_t dns_cache_create2	(	isc_mem_t *	cmctx,
		isc_taskmgr_t *	taskmgr,
		isc_timermgr_t *	timermgr,
		dns_rdataclass_t	rdclass,
		const char *	cachename,
		const char *	db_type,
		unsigned int	db_argc,
		char **	db_argv,
		dns_cache_t **	cachep
	)

Definition at line 190 of file cache.c.

References dns_cache_create3().

isc_result_t dns_cache_create3	(	isc_mem_t *	cmctx,
		isc_mem_t *	hmctx,
		isc_taskmgr_t *	taskmgr,
		isc_timermgr_t *	timermgr,
		dns_rdataclass_t	rdclass,
		const char *	cachename,
		const char *	db_type,
		unsigned int	db_argc,
		char **	db_argv,
		dns_cache_t **	cachep
	)

Create a new DNS cache.

dns_cache_create2() will create a named cache.

dns_cache_create3() will create a named cache using two separate memory contexts, one for cache data which can be cleaned and a separate one for memory allocated for the heap (which can grow without an upper limit and has no mechanism for shrinking).

dns_cache_create() is a backward compatible version that internally specifies an empty cache name and a single memory context.

Requires:

'cmctx' (and 'hmctx' if applicable) is a valid memory context.

'taskmgr' is a valid task manager and 'timermgr' is a valid timer manager, or both are NULL. If NULL, no periodic cleaning of the cache will take place.

'cachename' is a valid string. This must not be NULL.

'cachep' is a valid pointer, and *cachep == NULL

Ensures:

'*cachep' is attached to the newly created cache

Returns:

Definition at line 201 of file cache.c.

References cache_cleaner_init(), cache_create_db(), CACHE_MAGIC, dns_cache::cleaner, dns_cache::db, dns_cache::db_argc, dns_cache::db_argv, dns_cache::db_type, DESTROYLOCK, dns_cachestatscounter_max, dns_db_detach(), dns_db_setcachestats(), dns_db_settask(), dns_cache::filelock, dns_cache::filename, dns_cache::hmctx, isc_mem_attach(), isc_mem_detach(), isc_mem_free, isc_mem_get, isc_mem_put, isc_mem_putanddetach, isc_mem_strdup, isc_mutex_init, ISC_R_NOMEMORY, ISC_R_SUCCESS, isc_stats_create(), isc_stats_detach(), isc_task_create(), isc_task_detach(), isc_task_setname(), dns_cache::live_tasks, dns_cache::lock, dns_cache::magic, dns_cache::mctx, dns_cache::name, dns_cache::rdclass, dns_cache::references, REQUIRE, and dns_cache::stats.

Referenced by configure_view(), dns_cache_create(), and dns_cache_create2().

void dns_cache_attach	(	dns_cache_t *	cache,
		dns_cache_t **	targetp
	)

Attach *targetp to cache.

Requires:

'cache' is a valid cache.

'targetp' points to a NULL dns_cache_t *.

Ensures:

*targetp is attached to cache.

Definition at line 424 of file cache.c.

References dns_cache::lock, LOCK, dns_cache::references, REQUIRE, UNLOCK, and VALID_CACHE.

Referenced by configure_view(), and dns_view_setcache2().

void dns_cache_detach ( dns_cache_t ** cachep )

Detach *cachep from its cache.

Requires:

'cachep' points to a valid cache.

Ensures:

*cachep is NULL.

If '*cachep' is the last reference to the cache, all resources used by the cache will be freed

Definition at line 437 of file cache.c.

References cache_free(), dns_cache::cleaner, dns_cache_dump(), dns_lctx, DNS_LOGCATEGORY_DATABASE, DNS_LOGMODULE_CACHE, ISC_FALSE, ISC_LOG_WARNING, isc_log_write(), ISC_R_SUCCESS, isc_result_totext(), isc_task_shutdown(), ISC_TRUE, dns_cache::live_tasks, dns_cache::lock, LOCK, cache_cleaner::overmem, dns_cache::references, REQUIRE, cache_cleaner::task, UNLOCK, and VALID_CACHE.

Referenced by configure_view(), destroy(), dns_view_setcache2(), load_configuration(), and shutdown_server().

void dns_cache_attachdb	(	dns_cache_t *	cache,
		dns_db_t **	dbp
	)

Attach *dbp to the cache's database.

Notes:

This may be used to get a reference to the database for the purpose of cache lookups (XXX currently it is also the way to add data to the cache, but having a separate dns_cache_add() interface instead would allow more control over memory usage). The caller should call dns_db_detach() on the reference when it is no longer needed.

Requires:

'cache' is a valid cache.

'dbp' points to a NULL dns_db *.

Ensures:

*dbp is attached to the database.

Definition at line 483 of file cache.c.

References dns_cache::db, dns_db_attach(), dns_cache::lock, LOCK, REQUIRE, UNLOCK, and VALID_CACHE.

Referenced by dns_view_flushcache2(), dns_view_setcache2(), and prime_done().

isc_result_t dns_cache_setfilename	(	dns_cache_t *	cache,
		const char *	filename
	)

If 'filename' is non-NULL, make the cache persistent. The cache's data will be stored in the given file. If 'filename' is NULL, make the cache non-persistent. Files that are no longer used are not unlinked automatically.

Returns:

ISC_R_SUCCESS
ISC_R_NOMEMORY
Various file-related failures

Definition at line 495 of file cache.c.

References dns_cache::filelock, dns_cache::filename, isc_mem_free, isc_mem_strdup, ISC_R_NOMEMORY, ISC_R_SUCCESS, LOCK, dns_cache::mctx, REQUIRE, UNLOCK, and VALID_CACHE.

Referenced by configure_view().

isc_result_t dns_cache_load ( dns_cache_t * cache )

If the cache has a file name, load the cache contents from the file. Previous cache contents are not discarded. If no file name has been set, do nothing and return success.

MT:

Multiple simultaneous attempts to load or dump the cache will be serialized with respect to one another, but the cache may be read and updated while the dump is in progress. Updates performed during loading may or may not be preserved, and reads may return either the old or the newly loaded data.

Returns:

ISC_R_SUCCESS
Various failures depending on the database implementation type

Definition at line 515 of file cache.c.

References dns_cache::db, dns_db_load(), dns_cache::filelock, dns_cache::filename, ISC_R_SUCCESS, LOCK, REQUIRE, UNLOCK, and VALID_CACHE.

Referenced by configure_view().

isc_result_t dns_cache_dump ( dns_cache_t * cache )

If the cache has a file name, write the cache contents to disk, overwriting any preexisting file. If no file name has been set, do nothing and return success.

MT:

Multiple simultaneous attempts to load or dump the cache will be serialized with respect to one another, but the cache may be read and updated while the dump is in progress. Updates performed during the dump may or may not be reflected in the dumped file.

Returns:

ISC_R_SUCCESS
Various failures depending on the database implementation type

Definition at line 531 of file cache.c.

References dns_cache::db, dns_master_dump(), dns_master_style_cache, dns_cache::filelock, dns_cache::filename, ISC_R_SUCCESS, LOCK, dns_cache::mctx, REQUIRE, UNLOCK, and VALID_CACHE.

Referenced by dns_cache_detach().

isc_result_t dns_cache_clean	(	dns_cache_t *	cache,
		isc_stdtime_t	now
	)

Force immediate cleaning of the cache, freeing all rdatasets whose TTL has expired as of 'now' and that have no pending references.

Definition at line 975 of file cache.c.

References dns_cache::db, dns_db_createiterator(), dns_db_detachnode(), dns_db_expirenode(), dns_dbiterator_current(), dns_dbiterator_destroy(), dns_dbiterator_first(), dns_dbiterator_next(), dns_result_totext(), ISC_R_NOMORE, ISC_R_SUCCESS, REQUIRE, UNEXPECTED_ERROR, and VALID_CACHE.

void dns_cache_setcleaninginterval	(	dns_cache_t *	cache,
		unsigned int	interval
	)

Set the periodic cache cleaning interval to 'interval' seconds.

Definition at line 548 of file cache.c.

References dns_cache::cleaner, cache_cleaner::cleaning_interval, cache_cleaner::cleaning_timer, dns_lctx, DNS_LOGCATEGORY_DATABASE, DNS_LOGMODULE_CACHE, ISC_FALSE, isc_interval_set(), ISC_LOG_WARNING, isc_log_write(), ISC_R_SUCCESS, isc_result_totext(), isc_timer_reset(), isc_timertype_inactive, isc_timertype_ticker, ISC_TRUE, dns_cache::lock, LOCK, and UNLOCK.

Referenced by configure_view(), and end_cleaning().

unsigned int dns_cache_getcleaninginterval ( dns_cache_t * cache )

Get the periodic cache cleaning interval to 'interval' seconds.

Definition at line 585 of file cache.c.

References dns_cache::cleaner, cache_cleaner::cleaning_interval, dns_cache::lock, LOCK, REQUIRE, UNLOCK, and VALID_CACHE.

Referenced by cache_sharable().

const char* dns_cache_getname ( dns_cache_t * cache )

Get the cache name.

Definition at line 598 of file cache.c.

References dns_cache::name, REQUIRE, and VALID_CACHE.

Referenced by cachelist_find(), dumpdone(), and ns_stats_dump().

void dns_cache_setcachesize	(	dns_cache_t *	cache,
		size_t	size
	)

Set the maximum cache size. 0 means unlimited.

Definition at line 1047 of file cache.c.

References DNS_CACHE_MINSIZE, isc_mem_setwater(), dns_cache::lock, LOCK, dns_cache::mctx, REQUIRE, dns_cache::size, UNLOCK, VALID_CACHE, and water().

Referenced by configure_view().

size_t dns_cache_getcachesize ( dns_cache_t * cache )

Get the maximum cache size.

Definition at line 1087 of file cache.c.

References dns_cache::lock, LOCK, REQUIRE, dns_cache::size, UNLOCK, and VALID_CACHE.

Referenced by cache_sharable().

isc_result_t dns_cache_flush ( dns_cache_t * cache )

Flushes all data from the cache.

Returns:

Definition at line 1143 of file cache.c.

References cache_create_db(), dns_cache::cleaner, cleaner_s_busy, cleaner_s_done, cleaner_s_idle, dns_cache::db, dns_db_createiterator(), dns_db_detach(), dns_db_setcachestats(), dns_dbiterator_destroy(), ISC_FALSE, ISC_R_SUCCESS, ISC_TRUE, cache_cleaner::iterator, cache_cleaner::lock, dns_cache::lock, LOCK, cache_cleaner::replaceiterator, cache_cleaner::state, dns_cache::stats, and UNLOCK.

Referenced by dns_cache_flushnode(), and dns_view_flushcache2().

isc_result_t dns_cache_flushnode	(	dns_cache_t *	cache,
		dns_name_t *	name,
		isc_boolean_t	tree
	)

Definition at line 1263 of file cache.c.

References clearnode(), cleartree(), dns_cache::db, dns_cache_flush(), dns_db_attach(), dns_db_detach(), dns_db_detachnode(), dns_db_findnode(), dns_name_equal(), dns_rootname, ISC_FALSE, ISC_R_NOTFOUND, ISC_R_SUCCESS, dns_cache::lock, LOCK, and UNLOCK.

Referenced by dns_cache_flushname(), and dns_view_flushnode().

isc_result_t dns_cache_flushname	(	dns_cache_t *	cache,
		dns_name_t *	name
	)

Definition at line 1258 of file cache.c.

References dns_cache_flushnode(), and ISC_FALSE.

isc_stats_t* dns_cache_getstats ( dns_cache_t * cache )

Definition at line 1300 of file cache.c.

References REQUIRE, dns_cache::stats, and VALID_CACHE.

void dns_cache_dumpstats	(	dns_cache_t *	cache,
		FILE *	fp
	)

void dns_cache_updatestats	(	dns_cache_t *	cache,
		isc_result_t	result
	)

Definition at line 1306 of file cache.c.

References dns_cachestatscounter_queryhits, dns_cachestatscounter_querymisses, DNS_R_CNAME, DNS_R_DNAME, DNS_R_GLUE, DNS_R_NCACHENXDOMAIN, DNS_R_NCACHENXRRSET, DNS_R_ZONECUT, ISC_R_SUCCESS, isc_stats_increment(), REQUIRE, dns_cache::stats, and VALID_CACHE.

Referenced by query_addadditional(), and query_find().

Generated on Tue Apr 28 17:41:09 2015 by Doxygen 1.5.4 for BIND9 Internals 9.11.0pre-alpha


Defines
#define	DNS_CACHE_H 1
Functions
ISC_LANG_BEGINDECLS isc_result_t	dns_cache_create (isc_mem_t cmctx, isc_taskmgr_t taskmgr, isc_timermgr_t timermgr, dns_rdataclass_t rdclass, const char db_type, unsigned int db_argc, char db_argv, dns_cache_t cachep)
isc_result_t	dns_cache_create2 (isc_mem_t cmctx, isc_taskmgr_t taskmgr, isc_timermgr_t timermgr, dns_rdataclass_t rdclass, const char cachename, const char db_type, unsigned int db_argc, char db_argv, dns_cache_t *cachep)
isc_result_t	dns_cache_create3 (isc_mem_t cmctx, isc_mem_t hmctx, isc_taskmgr_t taskmgr, isc_timermgr_t timermgr, dns_rdataclass_t rdclass, const char cachename, const char db_type, unsigned int db_argc, char db_argv, dns_cache_t cachep)
	Create a new DNS cache.
void	dns_cache_attach (dns_cache_t cache, dns_cache_t *targetp)
	Attach *targetp to cache.
void	dns_cache_detach (dns_cache_t **cachep)
	Detach *cachep from its cache.
void	dns_cache_attachdb (dns_cache_t cache, dns_db_t *dbp)
	Attach *dbp to the cache's database.
isc_result_t	dns_cache_setfilename (dns_cache_t cache, const char filename)
	If 'filename' is non-NULL, make the cache persistent. The cache's data will be stored in the given file. If 'filename' is NULL, make the cache non-persistent. Files that are no longer used are not unlinked automatically.
isc_result_t	dns_cache_load (dns_cache_t *cache)
	If the cache has a file name, load the cache contents from the file. Previous cache contents are not discarded. If no file name has been set, do nothing and return success.
isc_result_t	dns_cache_dump (dns_cache_t *cache)
	If the cache has a file name, write the cache contents to disk, overwriting any preexisting file. If no file name has been set, do nothing and return success.
isc_result_t	dns_cache_clean (dns_cache_t *cache, isc_stdtime_t now)
	Force immediate cleaning of the cache, freeing all rdatasets whose TTL has expired as of 'now' and that have no pending references.
void	dns_cache_setcleaninginterval (dns_cache_t *cache, unsigned int interval)
	Set the periodic cache cleaning interval to 'interval' seconds.
unsigned int	dns_cache_getcleaninginterval (dns_cache_t *cache)
	Get the periodic cache cleaning interval to 'interval' seconds.
const char *	dns_cache_getname (dns_cache_t *cache)
	Get the cache name.
void	dns_cache_setcachesize (dns_cache_t *cache, size_t size)
	Set the maximum cache size. 0 means unlimited.
size_t	dns_cache_getcachesize (dns_cache_t *cache)
	Get the maximum cache size.
isc_result_t	dns_cache_flush (dns_cache_t *cache)
	Flushes all data from the cache.
isc_result_t	dns_cache_flushnode (dns_cache_t cache, dns_name_t name, isc_boolean_t tree)
isc_result_t	dns_cache_flushname (dns_cache_t cache, dns_name_t name)
isc_stats_t *	dns_cache_getstats (dns_cache_t *cache)
void	dns_cache_dumpstats (dns_cache_t cache, FILE fp)
void	dns_cache_updatestats (dns_cache_t *cache, isc_result_t result)