[3668] Better documentation for timers in LeaseMgrs.

src/lib/dhcpsrv/dhcpsrv_messages.mes

@@ -302,6 +302,10 @@ memory.
 A debug message issued when DHCPv6 lease is being loaded from the file to
 memory.
 
+% DHCPSRV_MEMFILE_LFC_START starting Lease File Cleanup
+An info message issued when the Memfile lease database backend starts the
+periodic Lease File Cleanup.
+
 % DHCPSRV_MEMFILE_NO_STORAGE running in non-persistent mode, leases will be lost after restart
 A warning message issued when writes of leases to disk have been disabled
 in the configuration. This mode is useful for some kinds of performance

src/lib/dhcpsrv/lease_mgr.h

@@ -118,9 +118,19 @@ public:
 /// be used directly, but rather specialized derived class should be used
 /// instead.
 ///
-/// As all methods are virtual, this class throws no exceptions.  However,
+/// This class creates an instance of the @c asiolink::IOService in the
-/// methods in concrete implementations of this class may throw exceptions:
+/// constructor. This object is required to execute the
-/// see the documentation of those classes for details.
+/// @c asiolink::IntervalTimer for the operations triggered periodically
+/// by the lease database backends which implement @c LeaseMgr interface.
+/// In order to execute the timers installed by the particular backend,
+/// the owner of the backend (e.g. DHCP server) should retrieve the pointer
+/// to the @c asiolink::IOService object by calling @c LeaseMgr::getIOService
+/// and call the appropriate functions, e.g. @c poll_one or @c run_one in a
+/// main loop.
+///
+/// This class throws no exceptions.  However, methods in concrete
+/// implementations of this class may throw exceptions: see the documentation
+/// of those classes for details.
 class LeaseMgr {
 public:
     /// @brief Defines maximum value for time that can be reliably stored.

src/lib/dhcpsrv/memfile_lease_mgr.cc

@@ -484,7 +484,7 @@ Memfile_LeaseMgr::initTimers(const Universe& universe) {
     try {
         lfc_interval = boost::lexical_cast<uint32_t>(lfc_interval_str);
     } catch (boost::bad_lexical_cast& ex) {
-        isc_throw(isc::BadValue, "invalid value of the LFC interval "
+        isc_throw(isc::BadValue, "invalid value of the lfc-interval "
                   << lfc_interval_str << " specified");
     }
 
@@ -497,6 +497,9 @@ Memfile_LeaseMgr::initTimers(const Universe& universe) {
 
 void
 Memfile_LeaseMgr::lfcCallback() {
+    /// @todo Extend this method to spawn the new process which will
+    /// perform the Lease File Cleanup in background.
+    LOG_INFO(dhcpsrv_logger, DHCPSRV_MEMFILE_LFC_START);
 }
 
 void

src/lib/dhcpsrv/memfile_lease_mgr.h

@@ -16,7 +16,6 @@
 #define MEMFILE_LEASE_MGR_H
 
 #include <asiolink/interval_timer.h>
-#include <asiolink/io_service.h>
 #include <dhcp/hwaddr.h>
 #include <dhcpsrv/csv_lease_file4.h>
 #include <dhcpsrv/csv_lease_file6.h>
@@ -37,9 +36,24 @@ namespace dhcp {
 /// DHCPv4 and DHCPv6 leases on disk. The format of the files is determined
 /// by the @c CSVLeaseFile4 and @c CSVLeaseFile6 classes.
 ///
-/// The backend stores leases incrementally, i.e. updates to leases are appended
+/// In order to obtain good performance, the backend stores leases
-/// at the end of the lease file. To record the deletion of a lease, the lease
+/// incrementally, i.e. updates to leases are appended at the end of the lease
-/// record is appended to the lease file with the valid lifetime set to 0.
+/// file. To record the deletion of a lease, the lease record is appended to
+/// the lease file with the valid lifetime set to 0. However, this may result
+/// in a significant growth of the lease file size over time, because the lease
+/// file will contain many entries for each lease. In order to mitigate this
+/// problem, the backend implements the Lease File Cleanup mechanism which is
+/// described on the Kea wiki: http://kea.isc.org/wiki/LFCDesign.
+///
+/// The backend installs an @c asiolink::IntervalTimer to periodically execute
+/// the @c Memfile_LeaseMgr::lfcCallback. This callback function controls
+/// the startup of the background process which removes redundant information
+/// from the lease file(s). Note that the @c asiolink::IntervalTimer uses
+/// @c asiolink::IOService to execute the callback. The @c LeaseMgr class
+/// creates this object, which can be obtained by the caller using the
+/// @c LeaseMgr::getIOService. The caller should later call an appropriate
+/// method, @c asio::io_service::poll_one to execute the callback when
+/// the timer is ready.
 ///
 /// When the backend is starting up, it reads leases from the lease file (one
 /// by one) and adds them to the in-memory container as follows:
@@ -343,6 +357,10 @@ protected:
     /// the unit tests. In particular, the unit test which checks that the
     /// callback function has been executed would override this function
     /// to increase the execution counter each time it is executed.
+    ///
+    /// @todo Once the callback is implemented, there is a need to
+    /// extend the documentation of this method. Currently, it simply
+    /// logs that it has been called.
     virtual void lfcCallback();
 
 private: