Commit 40a3b30d authored by Marcin Siodelski's avatar Marcin Siodelski
Browse files

[3668] Better documentation for timers in LeaseMgrs.

parent b3bbea1b
......@@ -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
......
......@@ -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,
/// methods in concrete implementations of this class may throw exceptions:
/// see the documentation of those classes for details.
/// This class creates an instance of the @c asiolink::IOService in the
/// constructor. This object is required to execute the
/// @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.
......
......@@ -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
......
......@@ -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
/// at the end of the lease file. To record the deletion of a lease, the lease
/// record is appended to the lease file with the valid lifetime set to 0.
/// In order to obtain good performance, the backend stores leases
/// incrementally, i.e. updates to leases are appended at the end of the lease
/// 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:
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment