Data Source Library Classes =========================== About this document ------------------- This memo describes major classes used in the data source library, mainly focusing on handling in-memory cache with consideration of the shared memory support. It will give an overview of the entire design architecture and some specific details of how these classes are expected to be used. Before reading, the higher level inter-module protocol should be understood: http://bind10.isc.org/wiki/SharedMemoryIPC Overall relationships between classes ------------------------------------- The following diagram shows major classes in the data source library related to in-memory caches and their relationship. image::overview.png[Class diagram showing overview of relationships] Major design decisions of this architecture are: * Keep each class as concise as possible, each focusing on one or small set of responsibilities. Smaller classes are generally easier to understand (at the cost of understanding how they work in the "big picture" of course) and easier to test. * On a related point, minimize dependency to any single class. A monolithic class on which many others are dependent is generally difficult to maintain because you'll need to ensure a change to the monolithic class doesn't break anything on any other classes. * Use polymorphism for any "fluid" behavior, and hide specific details under abstract interfaces so implementation details won't be directly referenced from any other part of the library. Specifically, the underlying memory segment type (local, mapped, and possibly others) and the source of in-memory data (master file or other data source) are hidden via a kind of polymorphism. * Separate classes directly used by applications from classes that implement details. Make the former classes as generic as possible, agnostic about implementation specific details such as the memory segment type (or, ideally and where possible, whether it's for in-memory cache or the underlying data source). The following give a summarized description of these classes. * `ConfigurableClientList`: The front end to application classes. An application that uses the data source library generally maintains one or more `ConfigurableClientList` object (usually one per RR class, or when we support views, probably one per view). This class is a container of sets of data source related classes, providing accessor to these classes and also acting as a factory of other related class objects. Note: Due to internal implementation reasons, there is a base class for `ConfigurableClientList` named `ClientList` in the C++ version, and applications are expected to use the latter. But conceptually `ConfigurableClientList` is an independent value class; the inheritance is not for polymorphism. Note also that the Python version doesn't have the base class. * `DataSourceInfo`: this is a straightforward tuple of set of class objects corresponding to a single data source, including `DataSourceClient`, `CacheConfig`, and `ZoneTableSegment`. `ConfigurableClientList` maintains a list of `DataSourceInfo`, one for each data source specified in its configuration. * `DataSourceClient`: The front end class to applications for a single data source. Applications will get a specific `DataSourceClient` object by `ConfigurableClientList::find()`. `DataSourceClient` itself is a set of factories for various operations on the data source such as lookup or update. * `CacheConfig`: library internal representation of in-memory cache configuration for a data source. It knows which zones are to be cached and where the zone data (RRs) should come from, either from a master file or other data source. With this knowledge it will create an appropriate `LoadAction` object. Note that `CacheConfig` isn't aware of the underlying memory segment type for the in-memory data. It's intentionally separated from this class (see the conciseness and minimal-dependency design decisions above). * `ZoneTableSegment`: when in-memory cache is enabled, it provides memory-segment-type independent interface to the in-memory data. This is an abstract base class (see polymorphism in the design decisions) and inherited by segment-type specific subclasses: `ZoneTableSegmentLocal` and `ZoneTableSegmentMapped` (and possibly others). Any subclass of `ZoneTableSegment` is expected to maintain the specific type of `MemorySegment` object. * `ZoneWriter`: a frontend utility class for applications to update in-memory zone data (currently it can only load a whole zone and replace any existing zone content with a new one, but this should be extended so it can handle partial updates). Applications will get a specific `ZoneWriter` object by `ConfigurableClientList::getCachedZoneWriter()`. `ZoneWriter` is constructed with `ZoneableSegment` and `LoadAction`. Since these are abstract classes, `ZoneWriter` doesn't have to be aware of "fluid" details. It's only responsible for "somehow" preparing `ZoneData` for a new version of a specified zone using `LoadAction`, and installing it in the `ZoneTable` (which can be accessed via `ZoneTableSegment`). * `DataSourceStatus`: created by `ConfigurableClientList::getStatus()`, a straightforward tuple that represents some status information of a specific data source managed in the `ConfigurableClientList`. `getStatus()` generates `DataSourceStatus` for all data sources managed in it, and returns them as a vector. * `ZoneTableAccessor`, `ZoneTableIterator`: frontend classes to get access to the conceptual "zone table" (a set of zones) stored in a specific data source. In particular, `ZoneTableIterator` allows applications to iterate over all zones (by name) stored in the specific data source. Applications will get a specific `ZoneTableAccessor` object by `ConfigurableClientList::getZoneTableAccessor()`, and get an iterator object by calling `getIterator` on the accessor. These are abstract classes and provide unified interfaces independent from whether it's for in-memory cached zones or "real" underlying data source. But the initial implementation only provides the in-memory cache version of subclass (see the next item). * `ZoneTableAccessorCache`, `ZoneTableIteratorCache`: implementation classes of `ZoneTableAccessor` and `ZoneTableIterator` for in-memory cache. They refer to `CacheConfig` to get a list of zones to be cached. * `ZoneTableHeader`, `ZoneTable`: top-level interface to actual in-memory data. These were separated based on a prior version of the design (http://bind10.isc.org/wiki/ScalableZoneLoadDesign) where `ZoneTableHeader` may contain multiple `ZoneTable`s. It's one-to-one relationship in the latest version (of implementation), so we could probably unify them as a cleanup. * `ZoneData`: representing the in-memory content of a single zone. `ZoneTable` contains (zero, one or) multiple `ZoneData` objects. * `RdataSet`: representing the in-memory content of (data of) a single RRset. `ZoneData` contains `RdataSet`s corresponding to the RRsets stored in the zone. * `LoadAction`: a "polymorphic" functor that implements loading zone data into memory. It hides from its user (i.e., `ZoneWriter`) details about the source of the data: master file or other data source (and perhaps some others). The "polymorphism" is actually realized as different implementations of the functor interface, not class inheritance (but conceptually the effect and goal is the same). Note: there's a proposal to replace `LoadAction` with a revised `ZoneDataLoader`, although the overall concept doesn't change. See Trac ticket #2912. * `ZoneDataLoader` and `ZoneDataUpdater`: helper classes for the `LoadAction` functor(s). These work independently from the source of data, taking a sequence of RRsets objects, converting them into the in-memory data structures (`RdataSet`), and installing them into a newly created `ZoneData` object. Sequence for auth module using local memory segment --------------------------------------------------- In the remaining sections, we explain how the classes shown in the previous section work together through their methods for commonly intended operations. The following sequence diagram shows the case for the authoritative DNS server module to maintain "local" in-memory data. Note that "auth" is a conceptual "class" (not actually implemented as a C++ class) to represent the server application behavior. For the purpose of this document that should be sufficient. The same note applies to all examples below. image::auth-local.png[Sequence diagram for auth server using local memory segment] 1. On startup, the auth module creates a `ConfigurableClientList` for each RR class specified in the configuration for "data_sources" module. It then calls `ConfigurableClientList::configure()` for the given configuration of that RR class. 2. For each data source, `ConfigurableClientList` creates a `CacheConfig` object with the corresponding cache related configuration. 3. If in-memory cache is enabled for the data source, `ZoneTableSegment` is also created. In this scenario the cache type is specified as "local" in the configuration, so a functor creates `ZoneTableSegmentLocal` as the actual instance. In this case its `ZoneTable` is immediately created, too. 4. `ConfigurableClientList` checks if the created `ZoneTableSegment` is writable. It is always so for "local" type of segments. So `ConfigurableClientList` immediately loads zones to be cached into memory. For each such zone, it first gets the appropriate `LoadAction` through `CacheConfig`, then creates `ZoneWriter` with the `LoadAction`, and loads the data using the writer. 5. If the auth module receives a "reload" command for a cached zone from other module (xfrin, an end user, etc), it calls `ConfigurableClientList::getCachedZoneWriter` to load and install the new version of the zone. The same loading sequence takes place except that the user of the writer is the auth module. Also, the old version of the zone data is destroyed at the end of the process. Sequence for auth module using mapped memory segment ---------------------------------------------------- This is an example for the authoritative server module that uses mapped type memory segment for in-memory data. image::auth-mapped.png[Sequence diagram for auth server using mapped memory segment] 1. The sequence is the same to the point of creating `CacheConfig`. 2. But in this case a `ZoneTableSegmentMapped` object is created based on the configuration of the cache type. This type of `ZoneTableSegment` is initially empty and isn't even associated with a `MemorySegment` (and therefore considered non-writable). 3. `ConfigurableClientList` checks if the zone table segment is writable to know whether to load zones into memory by itself, but as `ZoneTableSegment::isWritable()` returns false, it skips the loading. 4. The auth module gets the status of each data source, and notices there's a `WAITING` state of segment. So it subscribes to the "Memmgr" group on a command session and waits for an update from the memory manager (memmgr) module. (See also the note at the end of the section) 5. When the auth module receives an update command from memmgr, it calls `ConfigurableClientList::resetMemorySegment()` with the command argument and the segment mode of `READ_ONLY`. Note that the auth module handles the command argument as mostly opaque data; it's not expected to deal with details of segment type-specific behavior. If the reset fails, auth aborts (as there's no clear way to handle the failure). 6. `ConfigurableClientList::resetMemorySegment()` subsequently calls `reset()` method on the corresponding `ZoneTableSegment` with the given parameters. In the case of `ZoneTableSegmentMapped`, it creates a new `MemorySegment` object for the mapped type, which internally maps the specific file into memory. memmgr is expected to have prepared all necessary data in the file, so all the data are immediately ready for use (i.e., there shouldn't be any explicit load operation). 7. When a change is made in the mapped data, memmgr will send another update command with parameters for new mapping. The auth module calls `ConfigurableClientList::resetMemorySegment()`, and the underlying memory segment is swapped with a new one. The old memory segment object is destroyed. Note that this "destroy" just means unmapping the memory region; the data stored in the file are intact. Again, if mapping fails, auth aborts. 8. If the auth module happens to receive a reload command from other module, it could call `ConfigurableClientList::getCachedZoneWriter()` to reload the data by itself, just like in the previous section. In this case, however, the writability check of `getCachedZoneWriter()` fails (the segment was created as `READ_ONLY` and is non-writable), so loading won't happen. NOTE: While less likely in practice, it's possible that the same auth module uses both "local" and "mapped" (and even others) type of segments for different data sources. In such cases the sequence is either the one in this or previous section depending on the specified segment type in the configuration. The auth module itself isn't aware of per segment-type details, but changes the behavior depending on the segment state of each data source at step 4 above: if it's `WAITING`, it means the auth module needs help from memmgr (that's all the auth module should know; it shouldn't be bothered with further details such as mapped file names); if it's something else, the auth module doesn't have to do anything further. Sequence for memmgr module initialization using mapped memory segment --------------------------------------------------------------------- This sequence shows the common initialization sequence for the memory manager (memmgr) module using a mapped type memory segment. This is a mixture of the sequences shown in Sections 2 and 3. image::memmgr-mapped-init.png[] 1. Initial sequence is the same until the application module (memmgr) calls `ConfigurableClientList::getStatus()` as that for the previous section. 2. The memmgr module identifies the data sources whose in-memory cache type is "mapped". (Unlike other application modules, the memmgr should know what such types means due to its exact responsibility). For each such data source, it calls `ConfigurableClientList::resetMemorySegment` with the READ_WRITE mode and other mapped-type specific parameters. memmgr should be able to generate the parameters from its own configuration and other data source specific information (such as the RR class and data source name). 3. The `ConfigurableClientList` class calls `ZoneTableSegment::reset()` on the corresponding zone table segment with the given parameters. In this case, since the mode is READ_WRITE, a new `ZoneTable` will be created (assuming this is a very first time initialization; if there's already a zone table in the segment, it will be used). 4. The memmgr module then calls `ConfigurableClientList::getZoneTableAccessor()`, and calls the `getItertor()` method on it to get a list of zones for which zone data are to be loaded into the memory segment. 5. The memmgr module loads the zone data for each such zone. This sequence is the same as shown in Section 2. 6. On loading all zone data, the memmgr module sends an update command to all interested modules (such as auth) in the segment, and waits for acknowledgment from all of them. 7. Then it calls `ConfigurableClientList::resetMemorySegment()` for this data source with almost the same parameter as step 2 above, but with a different mapped file name. This will make a swap of the underlying memory segment with a new mapping. The old `MemorySegment` object will be destroyed, but as explained in the previous section, it simply means unmapping the file. 8. The memmgr loads the zone data into the newly mapped memory region by repeating the sequence shown in step 5. 9. The memmgr repeats all this sequence for data sources that use "mapped" segment for in-memory cache. Note: it could handle multiple data sources in parallel, e.g., while waiting for acknowledgment from other modules. Sequence for memmgr module to reload a zone using mapped memory segment ----------------------------------------------------------------------- This example is a continuation of the previous section, describing how the memory manager reloads a zone in mapped memory segment. image::memmgr-mapped-reload.png[] 1. When the memmgr module receives a reload command from other module, it calls `ConfigurableClientList::getCachedZoneWriter()` for the specified zone name. This method checks the writability of the segment, and since it's writable (as memmgr created it in the READ_WRITE mode), `getCachedZoneWriter()` succeeds and returns a `ZoneWriter`. 2. The memmgr module uses the writer to load the new version of zone data. There is nothing specific to mapped-type segment here. 3. The memmgr module then sends an update command to other modules that would share this version, and waits for acknowledgment from all of them. 4. On getting acknowledgments, the memmgr module calls `ConfigurableClientList::resetMemorySegment()` with the parameter specifying the other mapped file. This will swap the underlying `MemorySegment` with a newly created one, mapping the other file. 5. The memmgr updates this segment, too, so the two files will contain the same version of data.