Permalink
Browse files

start on caching

  • Loading branch information...
1 parent b353234 commit 310327df0f1c69b90c642d6aeac7e10cf0c07c62 @linuxwolf committed Jun 15, 2011
Showing with 55 additions and 9 deletions.
  1. +55 −9 doc/dns-design.rst
View
@@ -25,13 +25,14 @@ mechanism to establish socket connections in rough compliance to `Happy
Eyeballs (IPv6)`_ and `Happy Eyeballs (SCTP)`_. The API is intended to be
extensible to adapt to new technologies.
-This API consists of three major objects: policy context, low-level resolver,
-and socket connector. The policy context provides a common configuration
-point for lookup and connection policies, and provide the main point of
-extension for the API; the low-level resolver performs the basic lookup of
-addresses for names, automatically following aliases and service targets; the
-socket connector attempts to establish a socket for a service and/or domain
-name.
+This API consists of four major objects: policy context, caching context,
+low-level resolver, and socket connector. The policy context provides a common
+configuration point for lookup and connection policies, and provide the main
+point of extension for the API; the caching context stores results for a
+lookup request, honoring each result's time-to-live; the low-level resolver
+performs the basic lookup of addresses for names, automatically following
+aliases and service targets; the socket connector attempts to establish a
+socket for a service and/or domain name.
Policy Context
--------------
@@ -126,6 +127,51 @@ connector. Otherwise it returns false and error information.
bz_connector *conn,
bz_errcode *err)
+Caching
+-------
+
+Caching is managed by the cache context, bz_cache. It stores the results for
+queries by type and name, and honors the record's TTL. There is a one-to-one
+relation between a bz_ctx and a bz_cache, with the bz_ctx owning the bz_cache.
+All bz_resolver and bz_connector instances created from a given bz_ctx make use
+of this cache context.
+
+Properties
+~~~~~~~~~~
+
+Each of the following properties has a getter, but no setter. The values are
+determined when the bz_resolver is created, or as its state changes while
+processing lookups:
+
+* context (``bz_ctx``) - The owning context.
+
+Operation
+~~~~~~~~~
+
+The bz_cache provides the following functions:
+
+* retrieve() - Retrieves all results for a given type and name.
+* append() - Appends a new result for a given type and name.
+* clear() - Clears all results for a given type and name.
+* purge() - Purges all cached information from the bz_cache.
+
+retrieve() takes a record type and a name (along with a callback and optional
+callback data), and returns all of the relevant results for that key-pair via
+the callback. If any results for the type/name key-pair have expired, they are
+released and ignored.
+
+append() takes a record type, name, and result, appending the result to any
+existing results stored for that type/name key-pair. If the type/name key-pair
+does not already exist in the cache, it is created.
+
+clear() takes a record type and name, and removes all results for that
+type/name key-pair.
+
+purge() removes all results for all known type/name key-pairs.
+
+Callback
+~~~~~~~~
+
Low-Level Resolver
------------------
@@ -215,8 +261,8 @@ Callback
The lookup() callback is expected to match the following signature::
void (*bz_resolver_lookup_cb)(bz_lookup_handle handle,
- bz_err_code retcode,
- struct bz_lookup_result *result,
+ bz_errcode retcode,
+ bz_lookup_result *result,
void *arg);
This callback is executed for each found record, and when the lookup() is

0 comments on commit 310327d

Please sign in to comment.