From: Tomek Mrugalski Date: Mon, 20 Aug 2012 13:40:37 +0000 (+0200) Subject: [2040] All benchmark classes are now documented. X-Git-Tag: trac2351_base~117^2~10 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=2ebd8cf46447c014945cbc5059671ee72c316b30;p=thirdparty%2Fkea.git [2040] All benchmark classes are now documented. --- diff --git a/tests/tools/dhcp-ubench/memfile_ubench.cc b/tests/tools/dhcp-ubench/memfile_ubench.cc index 7bb47ae73a..39f952afd3 100644 --- a/tests/tools/dhcp-ubench/memfile_ubench.cc +++ b/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 IPv4Hash; -typedef std::map::iterator leaseIt; + + /// A hash table for Lease4 leases. + typedef std::map IPv4Hash; + + /// An iterator for Lease4 hash table. + typedef std::map::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_); diff --git a/tests/tools/dhcp-ubench/memfile_ubench.h b/tests/tools/dhcp-ubench/memfile_ubench.h index 45d93ac088..250949f5c4 100644 --- a/tests/tools/dhcp-ubench/memfile_ubench.h +++ b/tests/tools/dhcp-ubench/memfile_ubench.h @@ -18,43 +18,89 @@ #include #include "benchmark.h" +/// @brief Structure of the Lease4 that is kept in memory struct Lease4 { - uint32_t addr; - std::vector hwaddr; - std::vector 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 hwaddr; /// hardware address + std::vector 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 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_; }; diff --git a/tests/tools/dhcp-ubench/mysql_ubench.h b/tests/tools/dhcp-ubench/mysql_ubench.h index c2c33d4ae8..9bba8085f1 100644 --- a/tests/tools/dhcp-ubench/mysql_ubench.h +++ b/tests/tools/dhcp-ubench/mysql_ubench.h @@ -15,23 +15,73 @@ #include #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_; }; diff --git a/tests/tools/dhcp-ubench/sqlite_ubench.cc b/tests/tools/dhcp-ubench/sqlite_ubench.cc index 9974a3c845..001762ae92 100644 --- a/tests/tools/dhcp-ubench/sqlite_ubench.cc +++ b/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) { diff --git a/tests/tools/dhcp-ubench/sqlite_ubench.h b/tests/tools/dhcp-ubench/sqlite_ubench.h index 8ef08608ff..a066ec907f 100644 --- a/tests/tools/dhcp-ubench/sqlite_ubench.h +++ b/tests/tools/dhcp-ubench/sqlite_ubench.h @@ -15,22 +15,60 @@ #include #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_; };