Changes between Version 15 and Version 16 of DataSourceClasses


Ignore:
Timestamp:
Jun 13, 2013, 8:48:31 PM (4 years ago)
Author:
pselkirk
Comment:

add whitespace between bullet points for readability

Legend:

Unmodified
Added
Removed
Modified
  • DataSourceClasses

    v15 v16  
    2222
    2323Major design decisions of this architecture are:
     24
    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.
     29
    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.
     34
    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.
     41
    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.
     62
    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.
     68
    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.
     74
    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).
     83
    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.
     91
    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`).
     104
    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.
     110
    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).
     124
    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.
     129
    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.
     136
    123137- `ZoneData`: representing the in-memory content of a single zone.
    124138  `ZoneTable` contains (zero, one or) multiple `ZoneData` objects.
     139
    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.
     144
    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.
     154
    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.
     180
    1631812. For each data source, `ConfigurableClientList` creates a
    164182   `CacheConfig` object with the corresponding cache related
    165183   configuration.
     184
    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.
     190
    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.
     197
    1771985. If the auth module receives a "reload" command for a cached zone
    178199   from other module (xfrin, an end user, etc), it calls
     
    191212
    1922131. The sequence is the same to the point of creating `CacheConfig`.
     214
    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").
     219
    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.
     224
    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)
     230
    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.
     237
    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).
     247
    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.
     255
    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.
     287
    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).
     297
    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).
     304
    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.
     309
    2783105. The memmgr module loads the zone data for each such zone.  This
    279311   sequence is the same as shown in Section 2.
     312
    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.
     316
    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.
     323
    2893248. The memmgr loads the zone data into the newly mapped memory region
    290325   by repeating the sequence shown in step 5.
     326
    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`.
     345
    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.
     348
    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.
     352
    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.
     357
    3183585. The memmgr updates this segment, too, so the two files will contain
    319359   the same version of data.