perfdhcp objects breakdown

+ The source code of perfdhcp tool has been refactored from C to C++. + There is a bunch of new C++ classes. in the refactored code. + All of them are well documented in Doxygen. This document is + limited to brief overview of major classes to help understand + their purpose. +

Chapter 2. Classes

Table of Contents

CommandOptions (command_options.h .cc)
TestControl (test_control.h .cc)
StatsMgr (stats_mgr.h)
PerfPkt4, PerfPkt6 (perf_pkt4.h .cc, perf_pkt6.h .cc)
LocalizedOption (localized_option.h)
PktTransform (pkt_transform.h .cc)

CommandOptions (command_options.h .cc)

CommandOptions is a singleton class that parses perfdhcp command line parameters and initializes its members accordingly. If parsed parameters are invalid the parser function throws exception.

 main(int argc, char* argv[]) {
-    try {
-        CommandOptions& command_options = CommandOptions::instance();
-        command_options.parse(argc, argv);
-    catch(const Exception& e) {
-        ...
-    }
+try {
+    CommandOptions& command_options = CommandOptions::instance();
+    command_options.parse(argc, argv);
+catch(const Exception& e) {
     ...
+}
+...
 }

If argument parsing is successful than parsed values can be read from CommandOptions singleton from any class or function in the program:

 
-    ...
-    int rate = CommandOptions::instance().getRate();
-    ...
+...
+int rate = CommandOptions::instance().getRate();
+...
+
+

TestControl (test_control.h .cc)

+ TestControl singleton is responsible for test execution coordination. + It relies on CommandOptions object to get all required test parameters. For + this reason CommandOptions has to be initialized and CommandOptions::parse() + has to be called prior to calling TestControl::run(). The latter function + performs initialization of TestControl internals and execues the main program + loop. The TestControl::run() function performs the following major operations: +

check if command line has been parsed,
prints diagnostics if specified from command line,
register DHCP options factory functions,
read packet templates from files,
initialize Statistics Manager object,
set interrupt signal handler (handle ^C),
open and close socket for communication with server,
coordinate sending and receiving packets,
coordinate intermediate reporting,
prints test statistics.

+ TestControl is a singleton object so there is one sole instance of + it throughout the program. In order to allow running performance test + multiple times (using different command line options) with single instance + of the TestControl object it uses TestControl::reset() function internally + to reset state of the class members. Also, functions that initialize + various class members like Statistics Manager will release any objects + existing from previous test runs. +

StatsMgr (stats_mgr.h)

+ StatsMgr is a class that holds all performance statistics gathered throughout + the test execution. Statistics Manager is created in TestControl. The + TestControl class posts all sent and received packets to StatsMgr. + Collected packets are used to match packets received from the server with + corresponding sent packets, calculate round trip time, number of packet + drops etc. Apart from the standard counters implemented in StatsMgr, + custom (named) counters can be specified and incremented by the calling + class. StatsMgr also exposes multiple functions that print gathered + statistics into the console. +

+ The StatsMgr is a template class that takes Pkt4, Pkt6, PerfPkt4 or + PerfPkt6 as a typename. The instance of the StatsMgr can be created + as follows: +

+
+typedef StatsMgr<Pkt4> StatsMgr4;
+StatsMgr4 stats_mgr4 = boost::shared_ptr<StatsMgr4>(new StatsMgr4());
+try {
+    stats_mgr->addExchangeStats(StatsMgr4::XCHG_DO);
+} catch(const Exception& e) {
+    std::cout << e.what() << std::endl;
+}
+
+

+ The StatsMgr instance created in the example above will be used for + DHCPv4 testing (collect DHCPv4 packets) and will be configured to + monitor statistics for DISCOVER-OFFER packet exchanges. +

PerfPkt4, PerfPkt6 (perf_pkt4.h .cc, perf_pkt6.h .cc)

+ The PerfPkt4 and PerfPkt6 classes are derived from dhcp::Pkt4 and + dhcp::Pkt6 (src/lib/dhcp). They extend parent class functionality + by adding support for template files. The instance of these classes + can be created using raw buffer (read from packet template file). + Once packet object is initialized it is possible to replace + parts of the on-wire data by using LocalizedOption mechanism. +

LocalizedOption (localized_option.h)

+ LocalizedOption derives from dhcp::Option class. It represents the + DHCP option (v4 or v6) to be placed at specified position in the + packet buffer (see the section called “PerfPkt4, PerfPkt6 (perf_pkt4.h .cc, perf_pkt6.h .cc)”). Such option is added + to option collection in PerfPkt4 or PerfPkt6 object and when any of + PerfPktX::rawPack() function is called their content is stored in + the packet output buffer at the position pointed to by + LocalizedOption object. The LocalizedOption also allows to read the + on wire data in received packet at the specified position. In this + case LocalizedOption has to be created and added to recived packet. + When PerfPktX::rawUnpack() is called the contents of the buffer + will be read and stored in LocalizedOption object for further + processing. +

+ The following code shows how to create a packet from (template) + buffer and replace option data in the buffer with LocalizedOption. +

+
+OptionBuffer buf;
+// fill buf with data here.
+...
+boost::scoped_ptr<PerfPkt4> pkt(new PerfPkt4(&buf[0], buf.size());
+const size_t offset_hostname = 240;
+OptionBuffer vec_hostname;
+// fill the hostname vector with data
+...
+LocalizedOptionPtr opt_hostname(new LocalizedOption(Option::V4, DHO_HOST_NAME, vec_hostname,
+                                                    offset_hostname));
+pkt->addOption(opt_hostname);
+// by calling rawPack() we replace packet contents with option contents at
+// buffer position 240.
+pkt->rawPack();

PktTransform (pkt_transform.h .cc)

+ This helper class contains the static functions to pack and unpack + DHCP options (specifically LocalizedOption) to and from the packet + buffer. This logic has been moved away from PerfPkt4 and PerfPkt6 + classes to PktTransform because PerfPktX classes share the logic + here.

\ No newline at end of file diff --git a/tests/tools/perfdhcp/perfdhcp-classes.xml b/tests/tools/perfdhcp/perfdhcp-classes.xml index 13da7c6501..8dda8b72a4 100644 --- a/tests/tools/perfdhcp/perfdhcp-classes.xml +++ b/tests/tools/perfdhcp/perfdhcp-classes.xml @@ -2,7 +2,7 @@ - + %version; ]> @@ -22,7 +22,7 @@ - PERFORMANCE OF THIS SOFTWARE. --> - + @@ -47,35 +47,170 @@ + + Introduction + + The source code of perfdhcp tool has been refactored from C to C++. + There is a bunch of new C++ classes. in the refactored code. + All of them are well documented in Doxygen. This document is + limited to brief overview of major classes to help understand + their purpose. + + Classes

- CommandOptions (command_options (.h, cc) + CommandOptions (command_options.h .cc) CommandOptions is a singleton class that parses perfdhcp command line parameters and initializes its members accordingly. If parsed parameters are invalid the parser function throws exception. If argument parsing is successful than parsed values can be read from CommandOptions singleton from any class or function in the program: + + +

+ TestControl (test_control.h .cc) + + TestControl singleton is responsible for test execution coordination. + It relies on CommandOptions object to get all required test parameters. For + this reason CommandOptions has to be initialized and CommandOptions::parse() + has to be called prior to calling TestControl::run(). The latter function + performs initialization of TestControl internals and execues the main program + loop. The TestControl::run() function performs the following major operations: + + check if command line has been parsed, + prints diagnostics if specified from command line, + register DHCP options factory functions, + read packet templates from files, + initialize Statistics Manager object, + set interrupt signal handler (handle ^C), + open and close socket for communication with server, + coordinate sending and receiving packets, + coordinate intermediate reporting, + prints test statistics. + + + + TestControl is a singleton object so there is one sole instance of + it throughout the program. In order to allow running performance test + multiple times (using different command line options) with single instance + of the TestControl object it uses TestControl::reset() function internally + to reset state of the class members. Also, functions that initialize + various class members like Statistics Manager will release any objects + existing from previous test runs. + +

+ StatsMgr (stats_mgr.h) + + StatsMgr is a class that holds all performance statistics gathered throughout + the test execution. Statistics Manager is created in TestControl. The + TestControl class posts all sent and received packets to StatsMgr. + Collected packets are used to match packets received from the server with + corresponding sent packets, calculate round trip time, number of packet + drops etc. Apart from the standard counters implemented in StatsMgr, + custom (named) counters can be specified and incremented by the calling + class. StatsMgr also exposes multiple functions that print gathered + statistics into the console. + + + The StatsMgr is a template class that takes Pkt4, Pkt6, PerfPkt4 or + PerfPkt6 as a typename. The instance of the StatsMgr can be created + as follows: + + StatsMgr4; +StatsMgr4 stats_mgr4 = boost::shared_ptr(new StatsMgr4()); +try { + stats_mgr->addExchangeStats(StatsMgr4::XCHG_DO); +} catch(const Exception& e) { + std::cout << e.what() << std::endl; +} +]]> + + The StatsMgr instance created in the example above will be used for + DHCPv4 testing (collect DHCPv4 packets) and will be configured to + monitor statistics for DISCOVER-OFFER packet exchanges. + +

+ PerfPkt4, PerfPkt6 (perf_pkt4.h .cc, perf_pkt6.h .cc) + + The PerfPkt4 and PerfPkt6 classes are derived from dhcp::Pkt4 and + dhcp::Pkt6 (src/lib/dhcp). They extend parent class functionality + by adding support for template files. The instance of these classes + can be created using raw buffer (read from packet template file). + Once packet object is initialized it is possible to replace + parts of the on-wire data by using LocalizedOption mechanism. + +

+ LocalizedOption (localized_option.h) + + LocalizedOption derives from dhcp::Option class. It represents the + DHCP option (v4 or v6) to be placed at specified position in the + packet buffer (see ). Such option is added + to option collection in PerfPkt4 or PerfPkt6 object and when any of + PerfPktX::rawPack() function is called their content is stored in + the packet output buffer at the position pointed to by + LocalizedOption object. The LocalizedOption also allows to read the + on wire data in received packet at the specified position. In this + case LocalizedOption has to be created and added to recived packet. + When PerfPktX::rawUnpack() is called the contents of the buffer + will be read and stored in LocalizedOption object for further + processing. + + + The following code shows how to create a packet from (template) + buffer and replace option data in the buffer with LocalizedOption. + + pkt(new PerfPkt4(&buf[0], buf.size()); +const size_t offset_hostname = 240; +OptionBuffer vec_hostname; +// fill the hostname vector with data +... +LocalizedOptionPtr opt_hostname(new LocalizedOption(Option::V4, DHO_HOST_NAME, vec_hostname, + offset_hostname)); +pkt->addOption(opt_hostname); +// by calling rawPack() we replace packet contents with option contents at +// buffer position 240. +pkt->rawPack(); ]]>

+ PktTransform (pkt_transform.h .cc) + + This helper class contains the static functions to pack and unpack + DHCP options (specifically LocalizedOption) to and from the packet + buffer. This logic has been moved away from PerfPkt4 and PerfPkt6 + classes to PktTransform because PerfPktX classes share the logic + here. + +