[2040] All benchmark classes are now documented.

tests/tools/dhcp-ubench/memfile_ubench.cc

@@ -20,26 +20,81 @@
 using namespace std;
 
 
+/// @brief In-memory + lease file database implementation
+///
+/// This is a simplified in-memory database that mimics ISC DHCP4 implementation.
+/// It uses STL and boost: std::map for storage, boost::shared ptr for memory
+/// management. It does use C file operations (fopen, fwrite, etc.), because
+/// C++ streams does not offer any easy way to flush their contents, like
+/// fflush() and fsync() does.
+///
+/// IPv4 address is used as a key in the hash.
 class memfile_LeaseMgr {
 public:
-typedef std::map<uint32_t /* addr */, Lease4Ptr /* lease info */> IPv4Hash;
-typedef std::map<uint32_t, Lease4Ptr>::iterator leaseIt;
+
+    /// A hash table for Lease4 leases.
+    typedef std::map<uint32_t /* addr */, Lease4Ptr /* lease info */> IPv4Hash;
+
+    /// An iterator for Lease4 hash table.
+    typedef std::map<uint32_t, Lease4Ptr>::iterator leaseIt;
+
+    /// @brief The sole memfile lease manager constructor
+    ///
+    /// @param filename name of the lease file (will be overwritten)
+    /// @param sync should operations be
     memfile_LeaseMgr(const std::string& filename, bool sync);
+
+    /// @brief Destructor (closes file)
     ~memfile_LeaseMgr();
+
+    /// @brief adds a lease to the hash
+    ///
+    /// @param lease lease to be added
     bool addLease(Lease4Ptr lease);
+
+    /// @brief returns existing lease
+    ///
+    /// @param addr address of the searched lease
+    ///
+    /// @return smart pointer to the lease (or NULL if lease is not found)
     Lease4Ptr getLease(uint32_t addr);
+
+    /// @brief Simplified lease update.
+    ///
+    /// Searches for a lease and then updates its client last transmission
+    /// time. Writes new lease content to lease file (and calls fflush()/fsync(),
+    /// if synchronous operation is enabled).
+    ///
+    /// @param addr IPv4 address
+    /// @param new_cltt New client last transmission time
+    ///
+    /// @return pointer to the updated lease (or NULL)
     Lease4Ptr updateLease(uint32_t addr, uint32_t new_cltt);
+
+    /// @brief Deletes a lease.
+    ///
+    /// @param addr IPv4 address of the lease to be deleted.
+    ///
+    /// @return true if deletion was successful, false if no such lease exists
     bool deleteLease(uint32_t addr);
 
 protected:
 
+    /// @brief Writes updated lease to a file.
+    ///
+    /// @param lease lease to be written
     void writeLease(Lease4Ptr lease);
 
+    /// Name of the lease file.
     std::string Filename_;
-    bool Sync_; // should we do flush after each operation?
 
-    // we have to use fe
+    /// should we do flush after each operation?
+    bool Sync_;
+
+    /// File handle to the open lease file.
     FILE * File_;
+
+    /// Hash table for IPv4 leases
     IPv4Hash ip4Hash_;
 };
 
@@ -132,10 +187,6 @@ memfile_uBenchmark::memfile_uBenchmark(const string& filename,
 
 }
 
-void memfile_uBenchmark::failure(const char* operation) {
-    throw string(operation);
-}
-
 void memfile_uBenchmark::connect() {
     try {
         LeaseMgr_ = new memfile_LeaseMgr(Filename_, Sync_);

tests/tools/dhcp-ubench/memfile_ubench.h

@@ -18,43 +18,89 @@
 #include <boost/shared_ptr.hpp>
 #include "benchmark.h"
 
+/// @brief Structure of the Lease4 that is kept in memory
 struct Lease4 {
-    uint32_t addr;
-    std::vector<uint8_t> hwaddr;
-    std::vector<uint8_t> client_id;
-    uint32_t valid_lft;
-    uint32_t recycle_time;
-    time_t cltt;
-    uint32_t pool_id;
-    bool fixed;
-    std::string hostname;
-    bool fqdn_fwd;
-    bool fqdn_rev;
-    std::string options;
-    std::string comments;
+    uint32_t addr; /// IPv4 address
+    std::vector<uint8_t> hwaddr; /// hardware address
+    std::vector<uint8_t> client_id; /// client-identifier
+    uint32_t valid_lft; /// valid lifetime timestamp
+    uint32_t recycle_time; /// timer for keeping lease after expiration/release
+                           /// (currently not used)
+    time_t cltt; /// client last transmission time
+    uint32_t pool_id; /// ID of the pool the lease belongs to
+    bool fixed; /// is this lease fixed?
+    std::string hostname; /// client hostname (may be empty)
+    bool fqdn_fwd; /// did we do AAAA update for this lease?
+    bool fqdn_rev; /// did we do PTR update for this lease?
+    std::string options; /// additional options stored with this lease
+                         /// (currently not used)
+    std::string comments; /// comments on that lease
+                          /// (currently not used)
 };
 
+/// Pointer to a Lease4 structure
 typedef boost::shared_ptr<Lease4> Lease4Ptr;
 
+/// an implementation of in-memory+file database
+/// The actual implementation is in memfile_ubench.cc
 class memfile_LeaseMgr;
 
+/// @brief In-memory + file micro-benchmark.
+///
+/// That is a specific backend implementation. See \ref uBenchmark class for
+/// detailed explanation of its operations. This class uses custom in-memory
+/// pseudo-database and external write-only lease file. That approach simulates
+/// modernized model of ISC DHCP4. It uses standard STL maps together with
+/// shared_ptr from boost library. The "database" is implemented in the Lease
+/// Manager (see \ref LeaseMgr in memfile_ubench.cc). All lease changes are
+/// appended to the end of the file, speeding up the process.
 class memfile_uBenchmark: public uBenchmark {
 public:
+
+    /// @brief The sole memfile benchmark constructor.
+    ///
+    /// @param filename name of the write-only lease file
+    /// @param num_iterations number of iterations
+    /// @param sync should fsync() be called after every file write?
+    /// @param verbose would you like extra logging?
     memfile_uBenchmark(const std::string& filename,
                        uint32_t num_iterations, bool sync, bool verbose);
 
+    /// @brief Prints backend info.
     virtual void printInfo();
+
+    /// @brief Spawns lease manager that create empty lease file, initializes
+    ///        empty STL maps.
     virtual void connect();
+
+    /// @brief Delete lease manager that closes lease file.
     virtual void disconnect();
+
+    /// @brief Creates new leases.
+    ///
+    /// See uBenchmark::createLease4Test() for detailed explanation.
     virtual void createLease4Test();
+
+    /// @brief Searches for existing leases.
+    ///
+    /// See uBenchmark::searchLease4Test() for detailed explanation.
     virtual void searchLease4Test();
+
+    /// @brief Updates existing leases.
+    ///
+    /// See uBenchmark::updateLease4Test() for detailed explanation.
     virtual void updateLease4Test();
+
+    /// @brief Deletes existing leases.
+    ///
+    /// See uBenchmark::deleteLease4Test() for detailed explanation.
     virtual void deleteLease4Test();
 
 protected:
-    void failure(const char* operation);
 
+    /// Lease Manager (concrete backend implementation, based on STL maps)
     memfile_LeaseMgr * LeaseMgr_;
 
+    /// Name of the lease file.
     std::string Filename_;
 };

tests/tools/dhcp-ubench/mysql_ubench.h

@@ -15,23 +15,73 @@
 #include <string>
 #include "benchmark.h"
 
+/// @brief MySQL micro-benchmark.
+///
+/// That is a specific backend implementation. See \ref uBenchmark class for
+/// detailed explanation of its operations. This class uses MySQL as database
+/// backend.
 class MySQL_uBenchmark: public uBenchmark {
 public:
+
+    /// @brief The sole MySQL micro-benchmark constructor
+    ///
+    /// To avoid influence of network performance, it is highly recommended
+    /// to run MySQL engine on the same host as benchmark. Thus hostname
+    /// is likely to be "localhost". Make sure that the selected database
+    /// is already created and that it follows expected schema. See mysql.schema
+    /// and isc-dhcp-perf-guide.html for details.
+    ///
+    /// Synchronous operation means using InnDB, async is MyISAM.
+    ///
+    /// @param hostname Name of the hostname to connect to
+    /// @param user usename used during MySQL connection
+    /// @param pass password used during MySQL connection
+    /// @param db name of the database to connect to
+    /// @param num_iterations number of iterations for basic operations
+    /// @param sync synchronous or asynchronous database writes
+    /// @param verbose should extra information be logged?
     MySQL_uBenchmark(const std::string& hostname, const std::string& user,
                      const std::string& pass, const std::string& db,
                      uint32_t num_iterations, bool sync,
                      bool verbose);
 
+    /// @brief Prints MySQL version info.
     virtual void printInfo();
+
+    /// @brief Opens connection to the MySQL database.
     virtual void connect();
+
+    /// @brief Closes connection to the MySQL database.
     virtual void disconnect();
+
+    /// @brief Creates new leases.
+    ///
+    /// See uBenchmark::createLease4Test() for detailed explanation.
     virtual void createLease4Test();
+
+    /// @brief Searches for existing leases.
+    ///
+    /// See uBenchmark::searchLease4Test() for detailed explanation.
     virtual void searchLease4Test();
+
+    /// @brief Updates existing leases.
+    ///
+    /// See uBenchmark::updateLease4Test() for detailed explanation.
     virtual void updateLease4Test();
+
+    /// @brief Deletes existing leases.
+    ///
+    /// See uBenchmark::deleteLease4Test() for detailed explanation.
     virtual void deleteLease4Test();
 
 protected:
+    /// @brief Used to report any database failures.
+    ///
+    /// Compared to its base version in uBenchmark class, this one logs additional
+    /// MySQL specific information using mysql_errno() and mysql_error() functions.
+    /// The outcome is the same: exception is thrown.
     void failure(const char* operation);
 
+    /// Handle to MySQL database connection.
     MYSQL* Conn_;
 };

tests/tools/dhcp-ubench/sqlite_ubench.cc

@@ -31,10 +31,6 @@ SQLite_uBenchmark::SQLite_uBenchmark(const string& filename,
 
 }
 
-void SQLite_uBenchmark::failure(const char* operation) {
-    throw string(operation);
-}
-
 void SQLite_uBenchmark::connect() {
     int result = sqlite3_open(DBName_.c_str(), &DB_);
     if (result) {

tests/tools/dhcp-ubench/sqlite_ubench.h

@@ -15,22 +15,60 @@
 #include <string>
 #include "benchmark.h"
 
+/// @brief SQLite benchmark
+///
+/// That is a specific backend implementation. See \ref uBenchmark class for
+/// detailed explanation of its operations. This class uses SQLite as DB backend.
 class SQLite_uBenchmark: public uBenchmark {
 public:
+
+    /// @brief The sole SQL benchmark constructor
+    ///
+    /// DB file must be present and appropriate database schema must
+    /// be used. See sqlite.schema script and isc-dhcp-perf-guide.html
+    /// for details.
+    ///
+    /// sync flag affects "PRAGMA synchronous" to be ON or OFF.
+    ///
+    /// @param filename name of the SQLite DB file. Must be present.
+    /// @param num_iterations number of iterations of basic lease operations
+    /// @param sync should the operations be synchronous or not?
+    /// @param verbose would you like extra details be logged?
     SQLite_uBenchmark(const std::string& filename,
                       uint32_t num_iterations,
                       bool sync, bool verbose);
 
+    /// @brief Prints SQLite version info.
     virtual void printInfo();
+
+    /// @brief Opens connection to the SQLite database.
     virtual void connect();
+
+    /// @brief Closes connection to the SQLite database.
     virtual void disconnect();
+
+    /// @brief Creates new leases.
+    ///
+    /// See uBenchmark::createLease4Test() for detailed explanation.
     virtual void createLease4Test();
+
+    /// @brief Searches for existing leases.
+    ///
+    /// See uBenchmark::searchLease4Test() for detailed explanation.
     virtual void searchLease4Test();
+
+    /// @brief Updates existing leases.
+    ///
+    /// See uBenchmark::updateLease4Test() for detailed explanation.
     virtual void updateLease4Test();
+
+    /// @brief Deletes existing leases.
+    ///
+    /// See uBenchmark::deleteLease4Test() for detailed explanation.
     virtual void deleteLease4Test();
 
 protected:
-    void failure(const char* operation);
 
+    /// Handle to SQLite database connection.
     sqlite3 *DB_;
 };