contrib/unbound/services/cache/rrset.h

   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_type hash, rrset_id_type 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  * Update or add an rrset in the rrset cache using a wildcard dname.
 138  * Generates wildcard dname by prepending the wildcard label to the closest
 139  * encloser. Will lookup if the rrset is in the cache and perform an update if
 140  * necessary.
 141  *
 142  * @param rrset_cache: the rrset cache.
 143  * @param rrset: which rrset to cache as wildcard. This rrset is left
 144  *      untouched.
 145  * @param ce: the closest encloser, will be uses to generate the wildcard dname.
 146  * @param ce_len: the closest encloser lenght.
 147  * @param alloc: how to allocate (and deallocate) the special rrset key.
 148  * @param timenow: current time (to see if ttl in cache is expired).
 149  */
 150 void rrset_cache_update_wildcard(struct rrset_cache* rrset_cache,
 151         struct ub_packed_rrset_key* rrset, uint8_t* ce, size_t ce_len,
 152         struct alloc_cache* alloc, time_t timenow);
 153
 154 /**
 155  * Lookup rrset. You obtain read/write lock. You must unlock before lookup
 156  * anything of else.
 157  * @param r: the rrset cache.
 158  * @param qname: name of rrset to lookup.
 159  * @param qnamelen: length of name of rrset to lookup.
 160  * @param qtype: type of rrset to lookup (host order).
 161  * @param qclass: class of rrset to lookup (host order).
 162  * @param flags: rrset flags, or 0.
 163  * @param timenow: used to compare with TTL.
 164  * @param wr: set true to get writelock.
 165  * @return packed rrset key pointer. Remember to unlock the key.entry.lock.
 166  *      or NULL if could not be found or it was timed out.
 167  */
 168 struct ub_packed_rrset_key* rrset_cache_lookup(struct rrset_cache* r,
 169         uint8_t* qname, size_t qnamelen, uint16_t qtype, uint16_t qclass,
 170         uint32_t flags, time_t timenow, int wr);
 171
 172 /**
 173  * Obtain readlock on a (sorted) list of rrset references.
 174  * Checks TTLs and IDs of the rrsets and rollbacks locking if not Ok.
 175  * @param ref: array of rrset references (key pointer and ID value).
 176  *      duplicate references are allowed and handled.
 177  * @param count: size of array.
 178  * @param timenow: used to compare with TTL.
 179  * @return true on success, false on a failure, which can be that some
 180  *      RRsets have timed out, or that they do not exist any more, the
 181  *      RRsets have been purged from the cache.
 182  *      If true, you hold readlocks on all the ref items.
 183  */
 184 int rrset_array_lock(struct rrset_ref* ref, size_t count, time_t timenow);
 185
 186 /**
 187  * Unlock array (sorted) of rrset references.
 188  * @param ref: array of rrset references (key pointer and ID value).
 189  *      duplicate references are allowed and handled.
 190  * @param count: size of array.
 191  */
 192 void rrset_array_unlock(struct rrset_ref* ref, size_t count);
 193
 194 /**
 195  * Unlock array (sorted) of rrset references and at the same time
 196  * touch LRU on the rrsets. It needs the scratch region for temporary
 197  * storage as it uses the initial locks to obtain hash values.
 198  * @param r: the rrset cache. In this cache LRU is updated.
 199  * @param scratch: region for temporary storage of hash values.
 200  *      if memory allocation fails, the lru touch fails silently,
 201  *      but locks are released. memory errors are logged.
 202  * @param ref: array of rrset references (key pointer and ID value).
 203  *      duplicate references are allowed and handled.
 204  * @param count: size of array.
 205  */
 206 void rrset_array_unlock_touch(struct rrset_cache* r, struct regional* scratch,
 207         struct rrset_ref* ref, size_t count);
 208
 209 /**
 210  * Update security status of an rrset. Looks up the rrset.
 211  * If found, checks if rdata is equal.
 212  * If so, it will update the security, trust and rrset-ttl values.
 213  * The values are only updated if security is increased (towards secure).
 214  * @param r: the rrset cache.
 215  * @param rrset: which rrset to attempt to update. This rrset is left
 216  *      untouched. The rrset in the cache is updated in-place.
 217  * @param now: current time.
 218  */
 219 void rrset_update_sec_status(struct rrset_cache* r,
 220         struct ub_packed_rrset_key* rrset, time_t now);
 221
 222 /**
 223  * Looks up security status of an rrset. Looks up the rrset.
 224  * If found, checks if rdata is equal, and entry did not expire.
 225  * If so, it will update the security, trust and rrset-ttl values.
 226  * @param r: the rrset cache.
 227  * @param rrset: This rrset may change security status due to the cache.
 228  *      But its status will only improve, towards secure.
 229  * @param now: current time.
 230  */
 231 void rrset_check_sec_status(struct rrset_cache* r,
 232         struct ub_packed_rrset_key* rrset, time_t now);
 233
 234 /**
 235  * Remove an rrset from the cache, by name and type and flags
 236  * @param r: rrset cache
 237  * @param nm: name of rrset
 238  * @param nmlen: length of name
 239  * @param type: type of rrset
 240  * @param dclass: class of rrset, host order
 241  * @param flags: flags of rrset, host order
 242  */
 243 void rrset_cache_remove(struct rrset_cache* r, uint8_t* nm, size_t nmlen,
 244         uint16_t type, uint16_t dclass, uint32_t flags);
 245
 246 /** mark rrset to be deleted, set id=0 */
 247 void rrset_markdel(void* key);
 248
 249 #endif /* SERVICES_CACHE_RRSET_H */