[apple/network_cmds.git] / unbound / services / cache / rrset.h

/*
 * services/cache/rrset.h - Resource record set cache.
 *
 * Copyright (c) 2007, NLnet Labs. All rights reserved.
 *
 * This software is open source.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 
 * Redistributions of source code must retain the above copyright notice,
 * this list of conditions and the following disclaimer.
 * 
 * Redistributions in binary form must reproduce the above copyright notice,
 * this list of conditions and the following disclaimer in the documentation
 * and/or other materials provided with the distribution.
 * 
 * Neither the name of the NLNET LABS nor the names of its contributors may
 * be used to endorse or promote products derived from this software without
 * specific prior written permission.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/**
 * \file
 *
 * This file contains the rrset cache.
 */

#ifndef SERVICES_CACHE_RRSET_H
#define SERVICES_CACHE_RRSET_H
#include "util/storage/lruhash.h"
#include "util/storage/slabhash.h"
#include "util/data/packed_rrset.h"
struct config_file;
struct alloc_cache;
struct rrset_ref;
struct regional;

/**
 * The rrset cache
 * Thin wrapper around hashtable, like a typedef.
 */
struct rrset_cache {
	/** uses partitioned hash table */
	struct slabhash table;
};

/**
 * Create rrset cache
 * @param cfg: config settings or NULL for defaults.
 * @param alloc: initial default rrset key allocation.
 * @return: NULL on error.
 */
struct rrset_cache* rrset_cache_create(struct config_file* cfg, 
	struct alloc_cache* alloc);

/**
 * Delete rrset cache
 * @param r: rrset cache to delete.
 */
void rrset_cache_delete(struct rrset_cache* r);

/**
 * Adjust settings of the cache to settings from the config file.
 * May purge the cache. May recreate the cache.
 * There may be no threading or use by other threads.
 * @param r: rrset cache to adjust (like realloc).
 * @param cfg: config settings or NULL for defaults.
 * @param alloc: initial default rrset key allocation.
 * @return 0 on error, or new rrset cache pointer on success.
 */
struct rrset_cache* rrset_cache_adjust(struct rrset_cache* r, 
	struct config_file* cfg, struct alloc_cache* alloc);

/**
 * Touch rrset, with given pointer and id.
 * Caller may not hold a lock on ANY rrset, this could give deadlock.
 *
 * This routine is faster than a hashtable lookup:
 *	o no bin_lock is acquired.
 *	o no walk through the bin-overflow-list. 
 *	o no comparison of the entry key to find it.
 *
 * @param r: rrset cache.
 * @param key: rrset key. Marked recently used (if it was not deleted
 *	before the lock is acquired, in that case nothing happens).
 * @param hash: hash value of the item. Please read it from the key when
 *	you have it locked. Used to find slab from slabhash.
 * @param id: used to check that the item is unchanged and not deleted.
 */
void rrset_cache_touch(struct rrset_cache* r, struct ub_packed_rrset_key* key,
	hashvalue_t hash, rrset_id_t id);

/**
 * Update an rrset in the rrset cache. Stores the information for later use.
 * Will lookup if the rrset is in the cache and perform an update if necessary.
 * If the item was present, and superior, references are returned to that.
 * The passed item is then deallocated with rrset_parsedelete.
 *
 * A superior rrset is:
 *	o rrset with better trust value.
 *	o same trust value, different rdata, newly passed rrset is inserted.
 * If rdata is the same, TTL in the cache is updated.
 *
 * @param r: the rrset cache.
 * @param ref: reference (ptr and id) to the rrset. Pass reference setup for
 *	the new rrset. The reference may be changed if the cached rrset is
 *	superior.
 *	Before calling the rrset is presumed newly allocated and changeable.
 *	Afer calling you do not hold a lock, and the rrset is inserted in
 *	the hashtable so you need a lock to change it.
 * @param alloc: how to allocate (and deallocate) the special rrset key.
 * @param timenow: current time (to see if ttl in cache is expired).
 * @return: true if the passed reference is updated, false if it is unchanged.
 * 	0: reference unchanged, inserted in cache.
 * 	1: reference updated, item is inserted in cache.
 * 	2: reference updated, item in cache is considered superior.
 *	   also the rdata is equal (but other parameters in cache are superior).
 */
int rrset_cache_update(struct rrset_cache* r, struct rrset_ref* ref, 
	struct alloc_cache* alloc, time_t timenow);

/**
 * Lookup rrset. You obtain read/write lock. You must unlock before lookup
 * anything of else.
 * @param r: the rrset cache.
 * @param qname: name of rrset to lookup.
 * @param qnamelen: length of name of rrset to lookup.
 * @param qtype: type of rrset to lookup (host order).
 * @param qclass: class of rrset to lookup (host order).
 * @param flags: rrset flags, or 0.
 * @param timenow: used to compare with TTL.
 * @param wr: set true to get writelock.
 * @return packed rrset key pointer. Remember to unlock the key.entry.lock.
 * 	or NULL if could not be found or it was timed out.
 */
struct ub_packed_rrset_key* rrset_cache_lookup(struct rrset_cache* r,
	uint8_t* qname, size_t qnamelen, uint16_t qtype, uint16_t qclass,
	uint32_t flags, time_t timenow, int wr);

/**
 * Obtain readlock on a (sorted) list of rrset references.
 * Checks TTLs and IDs of the rrsets and rollbacks locking if not Ok.
 * @param ref: array of rrset references (key pointer and ID value).
 *	duplicate references are allowed and handled.
 * @param count: size of array.
 * @param timenow: used to compare with TTL.
 * @return true on success, false on a failure, which can be that some
 * 	RRsets have timed out, or that they do not exist any more, the
 *	RRsets have been purged from the cache.
 *	If true, you hold readlocks on all the ref items. 
 */
int rrset_array_lock(struct rrset_ref* ref, size_t count, time_t timenow);

/**
 * Unlock array (sorted) of rrset references.
 * @param ref: array of rrset references (key pointer and ID value).
 *	duplicate references are allowed and handled.
 * @param count: size of array.
 */
void rrset_array_unlock(struct rrset_ref* ref, size_t count);

/**
 * Unlock array (sorted) of rrset references and at the same time
 * touch LRU on the rrsets. It needs the scratch region for temporary
 * storage as it uses the initial locks to obtain hash values.
 * @param r: the rrset cache. In this cache LRU is updated.
 * @param scratch: region for temporary storage of hash values.
 *	if memory allocation fails, the lru touch fails silently,
 *	but locks are released. memory errors are logged.
 * @param ref: array of rrset references (key pointer and ID value).
 *	duplicate references are allowed and handled.
 * @param count: size of array.
 */
void rrset_array_unlock_touch(struct rrset_cache* r, struct regional* scratch,
	struct rrset_ref* ref, size_t count);

/**
 * Update security status of an rrset. Looks up the rrset.
 * If found, checks if rdata is equal.
 * If so, it will update the security, trust and rrset-ttl values.
 * The values are only updated if security is increased (towards secure).
 * @param r: the rrset cache. 
 * @param rrset: which rrset to attempt to update. This rrset is left 
 * 	untouched. The rrset in the cache is updated in-place.
 * @param now: current time.
 */
void rrset_update_sec_status(struct rrset_cache* r, 
	struct ub_packed_rrset_key* rrset, time_t now);

/**
 * Looks up security status of an rrset. Looks up the rrset.
 * If found, checks if rdata is equal, and entry did not expire.
 * If so, it will update the security, trust and rrset-ttl values.
 * @param r: the rrset cache. 
 * @param rrset: This rrset may change security status due to the cache.
 * 	But its status will only improve, towards secure.
 * @param now: current time.
 */
void rrset_check_sec_status(struct rrset_cache* r, 
	struct ub_packed_rrset_key* rrset, time_t now);

/**
 * Remove an rrset from the cache, by name and type and flags
 * @param r: rrset cache
 * @param nm: name of rrset
 * @param nmlen: length of name
 * @param type: type of rrset
 * @param dclass: class of rrset, host order
 * @param flags: flags of rrset, host order
 */
void rrset_cache_remove(struct rrset_cache* r, uint8_t* nm, size_t nmlen,
	uint16_t type, uint16_t dclass, uint32_t flags);

/** mark rrset to be deleted, set id=0 */
void rrset_markdel(void* key);

#endif /* SERVICES_CACHE_RRSET_H */
Commit	Line	Data
89c4ed63 A	1	/*
	2	* services/cache/rrset.h - Resource record set cache.
	3	*
	4	* Copyright (c) 2007, NLnet Labs. All rights reserved.
	5	*
	6	* This software is open source.
	7	*
	8	* Redistribution and use in source and binary forms, with or without
	9	* modification, are permitted provided that the following conditions
	10	* are met:
	11	*
	12	* Redistributions of source code must retain the above copyright notice,
	13	* this list of conditions and the following disclaimer.
	14	*
	15	* Redistributions in binary form must reproduce the above copyright notice,
	16	* this list of conditions and the following disclaimer in the documentation
	17	* and/or other materials provided with the distribution.
	18	*
	19	* Neither the name of the NLNET LABS nor the names of its contributors may
	20	* be used to endorse or promote products derived from this software without
	21	* specific prior written permission.
	22	*
	23	* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
	24	* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
	25	* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
	26	* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
	27	* HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
	28	* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
	29	* TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
	30	* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
	31	* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
	32	* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
	33	* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	34	*/
	35
	36	/**
	37	* \file
	38	*
	39	* This file contains the rrset cache.
	40	*/
	41
	42	#ifndef SERVICES_CACHE_RRSET_H
	43	#define SERVICES_CACHE_RRSET_H
	44	#include "util/storage/lruhash.h"
	45	#include "util/storage/slabhash.h"
	46	#include "util/data/packed_rrset.h"
	47	struct config_file;
	48	struct alloc_cache;
	49	struct rrset_ref;
	50	struct regional;
	51
	52	/**
	53	* The rrset cache
	54	* Thin wrapper around hashtable, like a typedef.
	55	*/
	56	struct rrset_cache {
	57	/** uses partitioned hash table */
	58	struct slabhash table;
	59	};
	60
	61	/**
	62	* Create rrset cache
	63	* @param cfg: config settings or NULL for defaults.
	64	* @param alloc: initial default rrset key allocation.
65	* @return: NULL on error.
66	*/
67	struct rrset_cache* rrset_cache_create(struct config_file* cfg,
68	struct alloc_cache* alloc);
69
70	/**
71	* Delete rrset cache
72	* @param r: rrset cache to delete.
73	*/
74	void rrset_cache_delete(struct rrset_cache* r);
75
76	/**
77	* Adjust settings of the cache to settings from the config file.
78	* May purge the cache. May recreate the cache.
79	* There may be no threading or use by other threads.
80	* @param r: rrset cache to adjust (like realloc).
81	* @param cfg: config settings or NULL for defaults.
82	* @param alloc: initial default rrset key allocation.
83	* @return 0 on error, or new rrset cache pointer on success.
84	*/
85	struct rrset_cache* rrset_cache_adjust(struct rrset_cache* r,
86	struct config_file* cfg, struct alloc_cache* alloc);
87
88	/**
89	* Touch rrset, with given pointer and id.
90	* Caller may not hold a lock on ANY rrset, this could give deadlock.
91	*
92	* This routine is faster than a hashtable lookup:
93	* o no bin_lock is acquired.
94	* o no walk through the bin-overflow-list.
95	* o no comparison of the entry key to find it.
96	*
97	* @param r: rrset cache.
98	* @param key: rrset key. Marked recently used (if it was not deleted
99	* before the lock is acquired, in that case nothing happens).
100	* @param hash: hash value of the item. Please read it from the key when
101	* you have it locked. Used to find slab from slabhash.
102	* @param id: used to check that the item is unchanged and not deleted.
103	*/
104	void rrset_cache_touch(struct rrset_cache* r, struct ub_packed_rrset_key* key,
105	hashvalue_t hash, rrset_id_t id);
106
107	/**
108	* Update an rrset in the rrset cache. Stores the information for later use.
109	* Will lookup if the rrset is in the cache and perform an update if necessary.
110	* If the item was present, and superior, references are returned to that.
111	* The passed item is then deallocated with rrset_parsedelete.
112	*
113	* A superior rrset is:
114	* o rrset with better trust value.
115	* o same trust value, different rdata, newly passed rrset is inserted.
116	* If rdata is the same, TTL in the cache is updated.
117	*
118	* @param r: the rrset cache.
119	* @param ref: reference (ptr and id) to the rrset. Pass reference setup for
120	* the new rrset. The reference may be changed if the cached rrset is
121	* superior.
122	* Before calling the rrset is presumed newly allocated and changeable.
123	* Afer calling you do not hold a lock, and the rrset is inserted in
124	* the hashtable so you need a lock to change it.
125	* @param alloc: how to allocate (and deallocate) the special rrset key.
126	* @param timenow: current time (to see if ttl in cache is expired).
127	* @return: true if the passed reference is updated, false if it is unchanged.
128	* 0: reference unchanged, inserted in cache.
129	* 1: reference updated, item is inserted in cache.
130	* 2: reference updated, item in cache is considered superior.
131	* also the rdata is equal (but other parameters in cache are superior).
132	*/
133	int rrset_cache_update(struct rrset_cache* r, struct rrset_ref* ref,
134	struct alloc_cache* alloc, time_t timenow);
135
136	/**
137	* Lookup rrset. You obtain read/write lock. You must unlock before lookup
138	* anything of else.
139	* @param r: the rrset cache.
140	* @param qname: name of rrset to lookup.
141	* @param qnamelen: length of name of rrset to lookup.
142	* @param qtype: type of rrset to lookup (host order).
143	* @param qclass: class of rrset to lookup (host order).
144	* @param flags: rrset flags, or 0.
145	* @param timenow: used to compare with TTL.
146	* @param wr: set true to get writelock.
147	* @return packed rrset key pointer. Remember to unlock the key.entry.lock.
148	* or NULL if could not be found or it was timed out.
149	*/
150	struct ub_packed_rrset_key* rrset_cache_lookup(struct rrset_cache* r,
151	uint8_t* qname, size_t qnamelen, uint16_t qtype, uint16_t qclass,
152	uint32_t flags, time_t timenow, int wr);
153
154	/**
155	* Obtain readlock on a (sorted) list of rrset references.
156	* Checks TTLs and IDs of the rrsets and rollbacks locking if not Ok.
157	* @param ref: array of rrset references (key pointer and ID value).
158	* duplicate references are allowed and handled.
159	* @param count: size of array.
160	* @param timenow: used to compare with TTL.
161	* @return true on success, false on a failure, which can be that some
162	* RRsets have timed out, or that they do not exist any more, the
163	* RRsets have been purged from the cache.
164	* If true, you hold readlocks on all the ref items.
165	*/
166	int rrset_array_lock(struct rrset_ref* ref, size_t count, time_t timenow);
167
168	/**
169	* Unlock array (sorted) of rrset references.
170	* @param ref: array of rrset references (key pointer and ID value).
171	* duplicate references are allowed and handled.
172	* @param count: size of array.
173	*/
174	void rrset_array_unlock(struct rrset_ref* ref, size_t count);
175
176	/**
177	* Unlock array (sorted) of rrset references and at the same time
178	* touch LRU on the rrsets. It needs the scratch region for temporary
179	* storage as it uses the initial locks to obtain hash values.
180	* @param r: the rrset cache. In this cache LRU is updated.
181	* @param scratch: region for temporary storage of hash values.
182	* if memory allocation fails, the lru touch fails silently,
183	* but locks are released. memory errors are logged.
184	* @param ref: array of rrset references (key pointer and ID value).
185	* duplicate references are allowed and handled.
186	* @param count: size of array.
187	*/
188	void rrset_array_unlock_touch(struct rrset_cache* r, struct regional* scratch,
189	struct rrset_ref* ref, size_t count);
190
191	/**
192	* Update security status of an rrset. Looks up the rrset.
193	* If found, checks if rdata is equal.
194	* If so, it will update the security, trust and rrset-ttl values.
195	* The values are only updated if security is increased (towards secure).
196	* @param r: the rrset cache.
197	* @param rrset: which rrset to attempt to update. This rrset is left
198	* untouched. The rrset in the cache is updated in-place.
199	* @param now: current time.
200	*/
201	void rrset_update_sec_status(struct rrset_cache* r,
202	struct ub_packed_rrset_key* rrset, time_t now);
203
204	/**
205	* Looks up security status of an rrset. Looks up the rrset.
206	* If found, checks if rdata is equal, and entry did not expire.
207	* If so, it will update the security, trust and rrset-ttl values.
208	* @param r: the rrset cache.
209	* @param rrset: This rrset may change security status due to the cache.
210	* But its status will only improve, towards secure.
211	* @param now: current time.
212	*/
213	void rrset_check_sec_status(struct rrset_cache* r,
214	struct ub_packed_rrset_key* rrset, time_t now);
215
216	/**
217	* Remove an rrset from the cache, by name and type and flags
218	* @param r: rrset cache
219	* @param nm: name of rrset
220	* @param nmlen: length of name
221	* @param type: type of rrset
222	* @param dclass: class of rrset, host order
223	* @param flags: flags of rrset, host order
224	*/
225	void rrset_cache_remove(struct rrset_cache* r, uint8_t* nm, size_t nmlen,
226	uint16_t type, uint16_t dclass, uint32_t flags);
227
228	/** mark rrset to be deleted, set id=0 */
229	void rrset_markdel(void* key);
230
231	#endif /* SERVICES_CACHE_RRSET_H */