BIND 10 trac2207, updated. b59e1eb450e7f4630ee4ee8e67b7dbb3cf6092de [2207] Documentation of the base ZoneUpdater

[BIND 10 source code commits]

The branch, trac2207 has been updated
       via  b59e1eb450e7f4630ee4ee8e67b7dbb3cf6092de (commit)
      from  98127986d0baa2f87e455035d778c823bbe59397 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit b59e1eb450e7f4630ee4ee8e67b7dbb3cf6092de
Author: Michal 'vorner' Vaner <michal.vaner at nic.cz>
Date:   Wed Oct 10 13:12:21 2012 +0200

    [2207] Documentation of the base ZoneUpdater

-----------------------------------------------------------------------

Summary of changes:
 src/lib/datasrc/memory/zone_updater.h |   47 +++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

-----------------------------------------------------------------------
diff --git a/src/lib/datasrc/memory/zone_updater.h b/src/lib/datasrc/memory/zone_updater.h
index e21018c..7bf33e6 100644
--- a/src/lib/datasrc/memory/zone_updater.h
+++ b/src/lib/datasrc/memory/zone_updater.h
@@ -16,10 +16,57 @@ namespace isc {
 namespace datasrc {
 namespace memory {
 
+/// \brief Does an update to a zone.
+///
+/// This abstract base class represents the work of a reload of a zone.
+/// The work is divided into three stages -- load(), install() and cleanup().
+/// They should be called in this order for the effect to take place.
+///
+/// We divide them so the update of zone data can be done asynchronously,
+/// in a different thread. The install() operation is the only one that needs
+/// to be done in a critical section.
 class ZoneUpdater {
 public:
+    /// \brief Get the zone data into memory.
+    ///
+    /// This is the part that does the time-consuming loading into the memory.
+    /// This can be run in a separate thread, for example. It has no effect on
+    /// the data actually served, it only prepares them for future use.
+    ///
+    /// This is the first method you should call on the object. Never call it
+    /// multiple times.
+    ///
+    /// \note As this contains reading of files or other data sources, or with
+    ///     some other source of the data to load, it may throw quite anything.
+    ///     If it throws, do not call any other methods on the object and
+    ///     discard it.
+    /// \note After successful load(), you have to call cleanup() some time
+    ///     later.
+    /// \throw isc::Unexpected if called second time.
     virtual void load() = 0;
+    /// \brief Put the changes to effect.
+    ///
+    /// This replaces the old version of zone with the one previously prepared
+    /// by load(). It takes ownership of the old zone data, if any.
+    ///
+    /// You may call it only after successful load() and at most once.
+    ///
+    /// The operation is expected to be fast and is meant to be used inside
+    /// a critical section.
+    ///
+    /// This may throw in rare cases, depending on the concrete implementation.
+    /// If it throws, you still need to call cleanup().
+    ///
+    /// \throw isc::Unexpected if called without previous load() or for the
+    ///     second time.
     virtual void install() = 0;
+    /// \brief Clean up resources.
+    ///
+    /// This releases all resources held by owned zone data. That means the
+    /// one loaded by load() in case install() was not called or was not
+    /// successful, or the one replaced in install().
+    ///
+    /// Generally, this should never throw.
     virtual void cleanup() = 0;
 };