Changes between Version 15 and Version 16 of DataSourceClasses

Jun 13, 2013, 8:48:31 PM (4 years ago)

add whitespace between bullet points for readability


  • DataSourceClasses

    v15 v16  
    2323Major design decisions of this architecture are:
    2425- Keep each class as concise as possible, each focusing on one or
    2526  small set of responsibilities.  Smaller classes are generally easier
    2627  to understand (at the cost of understanding how they work in the
    2728  "big picture" of course) and easier to test.
    2830- On a related point, minimize dependency to any single class.  A
    2931  monolithic class on which many others are dependent is generally
    3032  difficult to maintain because you'll need to ensure a change to the
    3133  monolithic class doesn't break anything on any other classes.
    3235- Use polymorphism for any "fluid" behavior, and hide specific details
    3336  under abstract interfaces so implementation details won't be
    3639  possibly others) and the source of in-memory data (master file or
    3740  other data source) are hidden via a kind of polymorphism.
    3842- Separate classes directly used by applications from classes that
    3943  implement details.  Make the former classes as generic as possible,
    5660  independent value class; the inheritance is not for polymorphism.
    5761  Note also that the Python version doesn't have the base class.
    5863- `DataSourceInfo`: this is a straightforward tuple of set of class
    5964  objects corresponding to a single data source, including
    6166  `ConfigurableClientList` maintains a list of `DataSourceInfo`, one
    6267  for each data source specified in its configuration.
    6369- `DataSourceClient`: The front end class to applications for a single
    6470  data source.  Applications will get a specific `DataSourceClient`
    6672  `DataSourceClient` itself is a set of factories for various
    6773  operations on the data source such as lookup or update.
    6875- `CacheConfig`: library internal representation of in-memory cache
    6976  configuration for a data source.  It knows which zones are to be
    7481  data.  It's intentionally separated from this class (see the
    7582  conciseness and minimal-dependency design decisions above).
    7684- `ZoneTableSegment`: when in-memory cache is enabled, it provides
    7785  memory-segment-type independent interface to the in-memory data.
    8189  others).  Any subclass of `ZoneTableSegment` is expected to maintain
    8290  the specific type of `MemorySegment` object.
    8392- `ZoneWriter`: a frontend utility class for applications to update
    8493  in-memory zone data (currently it can only load a whole zone and
    93102  and installing it in the `ZoneTable` (which can be accessed via
    94103  `ZoneTableSegment`).
    95105- `DataSourceStatus`: created by `ConfigurableClientList::getStatus()`,
    96106  a straightforward tuple that represents some status information of a
    98108  `getStatus()` generates `DataSourceStatus` for all data sources
    99109  managed in it, and returns them as a vector.
    100111- `ZoneTableAccessor`, `ZoneTableIterator`: frontend classes to get
    101112  access to the conceptual "zone table" (a set of zones) stored in a
    111122  provides the in-memory cache version of subclass (see the next
    112123  item).
    113125- `ZoneTableAccessorCache`, `ZoneTableIteratorCache`: implementation
    114126  classes of `ZoneTableAccessor` and `ZoneTableIterator` for in-memory
    115127  cache.  They refer to `CacheConfig` to get a list of zones to be
    116128  cached.
    117130- `ZoneTableHeader`, `ZoneTable`: top-level interface to actual
    118131  in-memory data.  These were separated based on a prior version of
    121134  one-to-one relationship in the latest version (of implementation),
    122135  so we could probably unify them as a cleanup.
    123137- `ZoneData`: representing the in-memory content of a single zone.
    124138  `ZoneTable` contains (zero, one or) multiple `ZoneData` objects.
    125140- `RdataSet`: representing the in-memory content of (data of) a single
    126141  RRset.
    127142  `ZoneData` contains `RdataSet`s corresponding to the RRsets stored
    128143  in the zone.
    129145- `LoadAction`: a "polymorphic" functor that implements loading zone
    130146  data into memory.  It hides from its user (i.e., `ZoneWriter`)
    136152  a revised `ZoneDataLoader`, although the overall concept doesn't
    137153  change.  See Trac ticket #2912.
    138155- `ZoneDataLoader` and `ZoneDataUpdater`: helper classes for the
    139156  `LoadAction` functor(s).  These work independently from the source
    161178   module.  It then calls `ConfigurableClientList::configure()`
    162179   for the given configuration of that RR class.
    1631812. For each data source, `ConfigurableClientList` creates a
    164182   `CacheConfig` object with the corresponding cache related
    165183   configuration.
    1661853. If in-memory cache is enabled for the data source,
    167186   `ZoneTableSegment` is also created.  In this scenario the cache
    169188   creates `ZoneTableSegmentLocal` as the actual instance.
    170189   In this case its `ZoneTable` is immediately created, too.
    1711914. `ConfigurableClientList` checks if the created `ZoneTableSegment` is
    172192   writable.  It is always so for "local" type of segments.  So
    175195   `LoadAction` through `CacheConfig`, then creates `ZoneWriter` with
    176196   the `LoadAction`, and loads the data using the writer.
    1771985. If the auth module receives a "reload" command for a cached zone
    178199   from other module (xfrin, an end user, etc), it calls
    1922131. The sequence is the same to the point of creating `CacheConfig`.
    1932152. But in this case a `ZoneTableSegmentMapped` object is created based
    194216   on the configuration for the cache type.  This type of
    195217   `ZoneTableSegment` is initially empty, and isn't even associated
    196218   with a `MemorySgement` (and therefore considered "non writable").
    1972203. `ConfigurableClientList` checks if the zone table segment is
    198221   writable to know whether to load zones into memory by itself,
    199222   but since `ZoneTableSegment::isWritable()` returns false, it skips
    200223   the loading.
    2012254. the auth module gets the status of each data source, and notices
    202226   there's a "WAITING" state of segment.  So it subscribes to the
    204228   from the memory manager (memmgr) module. (See also the note at the
    205229   end of the section)
    2062315. when the auth module receives an update command from memmgr, it
    207232   calls `ConfigurableClientList::resetMemorySegment()` with the command
    210235   opaque data; it's not expected to be details of segment
    211236   type-specific behavior.
    2122386. `ConfigurableClientList::resetMemorySegment()` subsequently calls
    213239   `reset()` method on the corresponding `ZoneTableSegment` with the
    219245   so all the data are immediately ready for use (i.e., there
    220246   shouldn't be no explicit load operation).
    2212487. When a change is made in the mapped data, memmgr will send another
    222249   update command with parameters for new mapping.  The auth module
    226253   this "destroy" just means unmapping the memory region; the data
    227254   stored in the file are intact.
    2282568. If the auth module happens to receive a reload command from other
    229257   module, it could call
    257285   calls `ConfigurableClientList::getStatus()` as that for the
    258286   previous section.
    2592882. The memmgr module identifies the data sources whose in-memory cache
    260289   type is "mapped".  (Unlike other application modules, the memmgr
    266295   other data source specific information (such as the RR class and
    267296   data source name).
    2682983. The `ConfigurableClientList` class calls
    269299   `ZoneTableSegment::reset()` on the corresponding zone table
    272302   very first time initialization; if there's already a zone table
    273303   in the segment, it will be used).
    2743054. The memmgr module then calls
    275306   `ConfigurableClientList::getZoneTableAccessor()`, and calls the
    276307   `getItertor()` method on it to get a list of zones for which
    277308   zone data are to be loaded into the memory segment.
    2783105. The memmgr module loads the zone data for each such zone.  This
    279311   sequence is the same as shown in Section 2.
    2803136. On loading all zone data, the memmgr module sends an update command
    281314   to all interested modules (such as auth) in the segment, and waits
    282315   for acknowledgment from all of them.
    2833177. Then it calls `ConfigurableClientList::resetMemorySegment()` for
    284318   this data source with almost the same parameter as step 2 above,
    287321   `MemorySegment` object will be destroyed, but as explained in the
    288322   previous section, it simply means unmapping the file.
    2893248. The memmgr loads the zone data into the newly mapped memory region
    290325   by repeating the sequence shown in step 5.
    2913279. The memmgr repeats all this sequence for data sources that use
    292328   "mapped" segment for in-memory cache.  Note: it could handle
    307343   READ_WRITE mode), `getCachedZoneWriter()` succeeds and returns
    308344   a `ZoneWriter`.
    3093462. The memmgr module uses the writer to load the new version of zone
    310347   data.  There is nothing specific to mapped-type segment here.
    3113493. The memmgr module then sends an update command to other modules
    312350   that would share this version, and waits for acknowledgment from
    313351   all of them.
    3143534. On getting acknowledgments, the memmgr module calls
    315354  `ConfigurableClientList::resetMemorySegment()` with the parameter
    316355   specifying the other mapped file.  This will swap the underlying
    317356   `MemorySegment` with a newly created one, mapping the other file.
    3183585. The memmgr updates this segment, too, so the two files will contain
    319359   the same version of data.