commit a (slightly out of date) adb document

doc/design/addressdb

@@ -0,0 +1,115 @@
+$Id: addressdb,v 1.1 2000/02/29 20:12:48 explorer Exp $
+
+You are lost in a maze of twisty little pointers, all alike...
+
+ADB                          |-> 0         |-> handle ---> handle ---> 0
+ |                           |             |
+ |-lists of names --------> name -------> name -------> 0
+ |			     |             |
+ |			     namehook      namehook
+ |                             |  |          |  |
+ |                             |  0          0  -> fetch
+ |			       |         
+ |                             V
+ |-lists of elements -----> element ----> element ----> element ---> 0
+ |                            |             |             |
+ |			      |-> zoneinfo  |-> 0         |-> zoneinfo
+ |-lists of dead handles
+ ...
+
+A handle contains a task, taskaction, and event argument, and is linkable
+in two ways.  One, for the list returned to the caller, and two to be
+attached to either a name (so events can be generated) or to the dead handle
+list, where no events are generated.
+
+HANDLE
+ |
+ |--- addrinfo ---> addrinfo ---> 0
+ |      |-> entry     |-> entry
+ |--- task, action, arg
+ |
+ V
+HANDLE
+ |
+ V
+ 0
+
+
+Notes and questions:
+
+	o If a handle is on the dead handle list, it is only waiting for
+	  the caller to dns_adb_done() it.
+
+	o If a handle is on a name list, it will generate at most one
+	  event, and then be moved to the dead handle list.
+
+	o If events are not requested, it is NEVER placed on the name's
+	  list, even though fetches for that name may be started.
+
+	o Names will have to have a reference count for each fetch
+	  in progress.  They will also have a bit that says some
+	  previous fetches failed.  XXX How in the world would I
+	  "refresh" the data?  If I only got 2 of 9 A6 chains to converge,
+	  when and how do I restart them later?
+
+	o The caller will give us a name, and we will return two items:
+	  a handle and a list of addresses.  If the list was non-empty when
+	  it was given to us, we will append (unique) addrinfo's to the list.
+
+	o How in the world do you shut this thing down?
+		If you cancel the fetches first:
+			1.  The handles are sent an event saying "no more
+			    names are coming."
+			2.  The handles are moved to the dead handle list.
+
+		If you cancel the handles first:
+			1.  The handles are moved to the dead handle list.
+
+	  It would therefore seem simpler to cancel/done all handles first,
+	  then all fetches.
+
+	o If a fetch returns a CNAME, what do we do?
+
+	o If a fetch returns a DNAME, what do we do?
+
+	o If a fetch returns 4 ipv4 addresses, we will have to allocate
+	  3 more (total of 4) namehooks, 4 entries, and fill them in.
+	  What happens if only some of these can be allocated?
+
+	o ipv6 raises the memory problem to a new level.  What if we
+	  have to fork into multiple chains, but we run out of memory?
+
+
+----------------------------------------------------------------------
+
+Looking up entries via names:
+
+	Look for the name in the database.
+
+	FOUND:
+		For each complete address, allocate an addrinfo structure
+		and add it to the handle.
+
+		If any fetches are in progress for this name, attach this
+		handle to this name so events can be posted to the handle,
+		if the handle wants events.
+
+		If no fetches are in progress and the name is incomplete,
+		see if we can start a fetch for this name.
+
+	NOT FOUND:
+		Create a new adbname structure.
+
+		Create a new namehook structure.
+
+		Start a fetch on this name.
+
+	If more data is coming (fetches are in progress) attach
+	the handle to the name, so it can get notification of
+	new data.
+
+	If the name is incomplete (due to fetches in progress,
+	recently failed fetches, or the inability to start new
+	fetches) copy the incomplete flag to the handle, so the
+	caller can know this.
+