doc/design/addressdb

   1 Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   2 Copyright (C) 2000, 2001  Internet Software Consortium.
   3 See COPYRIGHT in the source root or http://isc.org/copyright.html for terms.
   4
   5 $Id: addressdb,v 1.6 2004/03/05 05:04:45 marka Exp $
   6
   7 You are lost in a maze of twisty little pointers, all alike...
   8
   9 ADB                          |-> 0         |-> handle ---> handle ---> 0
  10  |                           |             |
  11  |-lists of names --------> name -------> name -------> 0
  12  |                           |             |
  13  |                           namehook      namehook
  14  |                             |  |          |  |
  15  |                             |  0          0  -> fetch
  16  |                             |
  17  |                             V
  18  |-lists of elements -----> element ----> element ----> element ---> 0
  19  |                            |             |             |
  20  |                            |-> zoneinfo  |-> 0         |-> zoneinfo
  21  |-lists of dead handles
  22  ...
  23
  24 A handle contains a task, taskaction, and event argument, and is linkable
  25 in two ways.  One, for the list returned to the caller, and two to be
  26 attached to either a name (so events can be generated) or to the dead handle
  27 list, where no events are generated.
  28
  29 HANDLE
  30  |
  31  |--- addrinfo ---> addrinfo ---> 0
  32  |      |-> entry     |-> entry
  33  |--- task, action, arg
  34  |
  35  V
  36 HANDLE
  37  |
  38  V
  39  0
  40
  41
  42 Notes and questions:
  43
  44         o If a handle is on the dead handle list, it is only waiting for
  45           the caller to dns_adb_done() it.
  46
  47         o If a handle is on a name list, it will generate at most one
  48           event, and then be moved to the dead handle list.
  49
  50         o If events are not requested, it is NEVER placed on the name's
  51           list, even though fetches for that name may be started.
  52
  53         o Names will have to have a reference count for each fetch
  54           in progress.  They will also have a bit that says some
  55           previous fetches failed.  XXX How in the world would I
  56           "refresh" the data?  If I only got 2 of 9 A6 chains to converge,
  57           when and how do I restart them later?
  58
  59         o The caller will give us a name, and we will return two items:
  60           a handle and a list of addresses.  If the list was non-empty when
  61           it was given to us, we will append (unique) addrinfo's to the list.
  62
  63         o How in the world do you shut this thing down?
  64                 If you cancel the fetches first:
  65                         1.  The handles are sent an event saying "no more
  66                             names are coming."
  67                         2.  The handles are moved to the dead handle list.
  68
  69                 If you cancel the handles first:
  70                         1.  The handles are moved to the dead handle list.
  71
  72           It would therefore seem simpler to cancel/done all handles first,
  73           then all fetches.
  74
  75         o If a fetch returns a CNAME, what do we do?
  76
  77         o If a fetch returns a DNAME, what do we do?
  78
  79         o If a fetch returns 4 ipv4 addresses, we will have to allocate
  80           3 more (total of 4) namehooks, 4 entries, and fill them in.
  81           What happens if only some of these can be allocated?
  82
  83         o ipv6 raises the memory problem to a new level.  What if we
  84           have to fork into multiple chains, but we run out of memory?
  85
  86
  87 ----------------------------------------------------------------------
  88
  89 Looking up entries via names:
  90
  91         Look for the name in the database.
  92
  93         FOUND:
  94                 For each complete address, allocate an addrinfo structure
  95                 and add it to the handle.
  96
  97                 If any fetches are in progress for this name, attach this
  98                 handle to this name so events can be posted to the handle,
  99                 if the handle wants events.
 100
 101                 If no fetches are in progress and the name is incomplete,
 102                 see if we can start a fetch for this name.
 103
 104         NOT FOUND:
 105                 Create a new adbname structure.
 106
 107                 Create a new namehook structure.
 108
 109                 Start a fetch on this name.
 110
 111         If more data is coming (fetches are in progress) attach
 112         the handle to the name, so it can get notification of
 113         new data.
 114
 115         If the name is incomplete (due to fetches in progress,
 116         recently failed fetches, or the inability to start new
 117         fetches) copy the incomplete flag to the handle, so the
 118         caller can know this.
 119