From: Michal 'vorner' Vaner <michal.vaner@nic.cz>
Date: Wed, 10 Oct 2012 11:12:21 +0000 (+0200)
Subject: [2207] Documentation of the base ZoneUpdater
X-Git-Tag: trac2402_base~12^2~35
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=b59e1eb450e7f4630ee4ee8e67b7dbb3cf6092de;p=thirdparty%2Fkea.git

[2207] Documentation of the base ZoneUpdater
---

diff --git a/src/lib/datasrc/memory/zone_updater.h b/src/lib/datasrc/memory/zone_updater.h
index e21018c777..7bf33e6911 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;
 };