mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-31 14:05:33 +00:00
Code Issues Releases Wiki Activity

[2230] Add perfdhcp internals manual as Doxygen file

Browse Source
This commit is contained in:
Marcin Siodelski
2012-09-13 11:02:23 +02:00
parent e7c00e175f
commit 440fdf2334
5 changed files with 177 additions and 343 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
doc/devel/mainpage.dox
View File

@@ -24,6 +24,7 @@
* - @subpage libdhcp
* - @subpage libdhcpIntro
* - @subpage libdhcpIfaceMgr
* - @subpage perfdhcpInternals
*
* @section misc Miscellaneous topics
* - @subpage LoggingApi
@@ -36,4 +37,4 @@
* @todo: Move this logo to the right (and possibly up). Not sure what
* is the best way to do it in Doxygen, without using CSS hacks.
* @image html isc-logo.png
*/
*/

3
tests/tools/perfdhcp/Makefile.am
View File

@@ -40,3 +40,6 @@ libb10_perfdhcp___la_LIBADD += $(top_builddir)/src/lib/asiolink/libb10-asiolink.
pkglibexec_PROGRAMS = perfdhcp
perfdhcp_SOURCES = perfdhcp.c
# ... and the documentation
EXTRA_DIST = perfdhcp_internals.dox

126
tests/tools/perfdhcp/perfdhcp-classes.html
View File

@@ -1,126 +0,0 @@
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>perfdhcp objects breakdown</title><link rel="stylesheet" href="../../../doc/guide/bind10-guide.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><meta name="description" content="This document briefly describes C++ classes being part of the perfdhcp tool."></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" title="perfdhcp objects breakdown"><div class="titlepage"><div><div><h1 class="title"><a name="d0e3"></a>perfdhcp objects breakdown</h1></div><div><div class="author"><h3 class="author"><span class="firstname">Marcin</span> <span class="surname">Siodelski</span></h3></div></div><div><p class="releaseinfo">This is a companion document for BIND 10 version
20120817.</p></div><div><p class="copyright">Copyright &copy; 2012 Internet Systems Consortium, Inc. ("ISC")</p></div><div><div class="abstract" title="Abstract"><p class="title"><b>Abstract</b></p><p>This document briefly describes C++ classes being part of the
perfdhcp tool. </p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#perfdhcp-refactoring">1. Introduction</a></span></dt><dt><span class="chapter"><a href="#perfdhcp-classes">2. Classes</a></span></dt><dd><dl><dt><span class="section"><a href="#command-options">CommandOptions (command_options.h .cc)</a></span></dt><dt><span class="section"><a href="#test-control">TestControl (test_control.h .cc)</a></span></dt><dt><span class="section"><a href="#stats-mgr">StatsMgr (stats_mgr.h)</a></span></dt><dt><span class="section"><a href="#perf-pkt">PerfPkt4, PerfPkt6 (perf_pkt4.h .cc, perf_pkt6.h .cc)</a></span></dt><dt><span class="section"><a href="#localized-option">LocalizedOption (localized_option.h)</a></span></dt><dt><span class="section"><a href="#pkt-transform.h">PktTransform (pkt_transform.h .cc)</a></span></dt></dl></dd></dl></div><div class="chapter" title="Chapter&nbsp;1.&nbsp;Introduction"><div class="titlepage"><div><div><h2 class="title"><a name="perfdhcp-refactoring"></a>Chapter&nbsp;1.&nbsp;Introduction</h2></div></div></div><p>
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.
</p></div><div class="chapter" title="Chapter&nbsp;2.&nbsp;Classes"><div class="titlepage"><div><div><h2 class="title"><a name="perfdhcp-classes"></a>Chapter&nbsp;2.&nbsp;Classes</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#command-options">CommandOptions (command_options.h .cc)</a></span></dt><dt><span class="section"><a href="#test-control">TestControl (test_control.h .cc)</a></span></dt><dt><span class="section"><a href="#stats-mgr">StatsMgr (stats_mgr.h)</a></span></dt><dt><span class="section"><a href="#perf-pkt">PerfPkt4, PerfPkt6 (perf_pkt4.h .cc, perf_pkt6.h .cc)</a></span></dt><dt><span class="section"><a href="#localized-option">LocalizedOption (localized_option.h)</a></span></dt><dt><span class="section"><a href="#pkt-transform.h">PktTransform (pkt_transform.h .cc)</a></span></dt></dl></div><div class="section" title="CommandOptions (command_options.h .cc)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="command-options"></a>CommandOptions (command_options.h .cc)</h2></div></div></div><p>
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.
</p><pre class="screen">
main(int argc, char* argv[]) {
try {
CommandOptions&amp; command_options = CommandOptions::instance();
command_options.parse(argc, argv);
catch(const Exception&amp; e) {
...
}
...
}
</pre><p>
If argument parsing is successful than parsed values can be read from
CommandOptions singleton from any class or function in the program:
</p><pre class="screen">
...
int rate = CommandOptions::instance().getRate();
...
</pre><p>
</p></div><div class="section" title="TestControl (test_control.h .cc)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="test-control"></a>TestControl (test_control.h .cc)</h2></div></div></div><p>
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:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>check if command line has been parsed,</p></li><li class="listitem"><p>prints diagnostics if specified from command line,</p></li><li class="listitem"><p>register DHCP options factory functions,</p></li><li class="listitem"><p>read packet templates from files,</p></li><li class="listitem"><p>initialize Statistics Manager object,</p></li><li class="listitem"><p>set interrupt signal handler (handle ^C),</p></li><li class="listitem"><p>open and close socket for communication with server,</p></li><li class="listitem"><p>coordinate sending and receiving packets,</p></li><li class="listitem"><p>coordinate intermediate reporting,</p></li><li class="listitem"><p>prints test statistics.</p></li></ol></div><p>
</p><p>
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.
</p></div><div class="section" title="StatsMgr (stats_mgr.h)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="stats-mgr"></a>StatsMgr (stats_mgr.h)</h2></div></div></div><p>
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.
</p><p>
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:
</p><pre class="screen">
typedef StatsMgr&lt;Pkt4&gt; StatsMgr4;
StatsMgr4 stats_mgr4 = boost::shared_ptr&lt;StatsMgr4&gt;(new StatsMgr4());
try {
stats_mgr-&gt;addExchangeStats(StatsMgr4::XCHG_DO);
} catch(const Exception&amp; e) {
std::cout &lt;&lt; e.what() &lt;&lt; std::endl;
}
</pre><p>
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.
</p></div><div class="section" title="PerfPkt4, PerfPkt6 (perf_pkt4.h .cc, perf_pkt6.h .cc)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="perf-pkt"></a>PerfPkt4, PerfPkt6 (perf_pkt4.h .cc, perf_pkt6.h .cc)</h2></div></div></div><p>
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.
</p></div><div class="section" title="LocalizedOption (localized_option.h)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="localized-option"></a>LocalizedOption (localized_option.h)</h2></div></div></div><p>
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 <a class="xref" href="#perf-pkt" title="PerfPkt4, PerfPkt6 (perf_pkt4.h .cc, perf_pkt6.h .cc)">the section called &#8220;PerfPkt4, PerfPkt6 (perf_pkt4.h .cc, perf_pkt6.h .cc)&#8221;</a>). 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.
</p><p>
The following code shows how to create a packet from (template)
buffer and replace option data in the buffer with LocalizedOption.
</p><pre class="screen">
OptionBuffer buf;
// fill buf with data here.
...
boost::scoped_ptr&lt;PerfPkt4&gt; pkt(new PerfPkt4(&amp;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-&gt;addOption(opt_hostname);
// by calling rawPack() we replace packet contents with option contents at
// buffer position 240.
pkt-&gt;rawPack();
</pre><p>
</p></div><div class="section" title="PktTransform (pkt_transform.h .cc)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="pkt-transform.h"></a>PktTransform (pkt_transform.h .cc)</h2></div></div></div><p>
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.
</p></div></div></div></body></html>

216
tests/tools/perfdhcp/perfdhcp-classes.xml
View File

@@ -1,216 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY mdash "&#x2014;" >
<!ENTITY % version SYSTEM "../../../doc/version.ent">
%version;
]>
<!--
- Copyright (C) 2012 Internet Systems Consortium, Inc. ("ISC")
-
- Permission to use, copy, modify, and/or distribute this software for any
- purpose with or without fee is hereby granted, provided that the above
- copyright notice and this permission notice appear in all copies.
-
- THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
- REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
- AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
- LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<?xml-stylesheet href="../../../doc/guide/bind10-guide.css" type="text/css"?>
<book>
<bookinfo>
<title>perfdhcp objects breakdown</title>
<!-- <subtitle>perfdhcp objects breakdown</subtitle> -->
<copyright>
<year>2012</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<author>
<firstname>Marcin</firstname>
<surname>Siodelski</surname>
</author>
<abstract>
<para>This document briefly describes C++ classes being part of the
perfdhcp tool. </para>
</abstract>
<releaseinfo>This is a companion document for BIND 10 version
&__VERSION__;.</releaseinfo>
</bookinfo>
<chapter id="perfdhcp-refactoring">
<title>Introduction</title>
<para>
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.
</para>
</chapter>
<chapter id="perfdhcp-classes">
<title>Classes</title>
<section id="command-options">
<title>CommandOptions (command_options.h .cc)</title>
<para>
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.
<screen>
<![CDATA[main(int argc, char* argv[]) {
try {
CommandOptions& command_options = CommandOptions::instance();
command_options.parse(argc, argv);
catch(const Exception& e) {
...
}
...
}]]>
</screen>
If argument parsing is successful than parsed values can be read from
CommandOptions singleton from any class or function in the program:
<screen>
<![CDATA[
...
int rate = CommandOptions::instance().getRate();
...
]]>
</screen>
</para>
</section>
<section id="test-control">
<title>TestControl (test_control.h .cc)</title>
<para>
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:
<orderedlist>
<listitem><para>check if command line has been parsed,</para></listitem>
<listitem><para>prints diagnostics if specified from command line,</para></listitem>
<listitem><para>register DHCP options factory functions,</para></listitem>
<listitem><para>read packet templates from files,</para></listitem>
<listitem><para>initialize Statistics Manager object,</para></listitem>
<listitem><para>set interrupt signal handler (handle ^C),</para></listitem>
<listitem><para>open and close socket for communication with server,</para></listitem>
<listitem><para>coordinate sending and receiving packets,</para></listitem>
<listitem><para>coordinate intermediate reporting,</para></listitem>
<listitem><para>prints test statistics.</para></listitem>
</orderedlist>
</para>
<para>
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.
</para>
</section>
<section id="stats-mgr">
<title>StatsMgr (stats_mgr.h)</title>
<para>
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.
</para>
<para>
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:
<screen>
<![CDATA[
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;
}
]]>
</screen>
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.
</para>
</section>
<section id="perf-pkt">
<title>PerfPkt4, PerfPkt6 (perf_pkt4.h .cc, perf_pkt6.h .cc)</title>
<para>
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.
</para>
</section>
<section id="localized-option">
<title>LocalizedOption (localized_option.h)</title>
<para>
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 <xref linkend="perf-pkt"/>). 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.
</para>
<para>
The following code shows how to create a packet from (template)
buffer and replace option data in the buffer with LocalizedOption.
<screen>
<![CDATA[
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();
]]>
</screen>
</para>
</section>
<section id="pkt-transform.h">
<title>PktTransform (pkt_transform.h .cc)</title>
<para>
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.
</para>
</section>
</chapter>
</book>

172
tests/tools/perfdhcp/perfdhcp_internals.dox Normal file
View File

@@ -0,0 +1,172 @@
// Copyright (C) 2012 Internet Systems Consortium, Inc. ("ISC")
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
// AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.
/// @namespace perfdhcp
/// @page perfdhcpInternals perfdhcp Internals
///
/// The perfdhcp utility provides a way of measuring the performance of
/// DHCP servers by generating large amounts of traffic. Written in C++,
/// its use is described in detail in the DHCP Performance Guide.
///
/// This document is aimed at people wishing to understand the internals
/// of the perfdhcp program. It describes the major components in the
/// utility and their interaction.
///
/// @section perfdhcpClasses perfdhcp Classes
///
/// @subsection perfdhcpCommandOptions CommandOptions (Command Options)
///
/// isc::perfdhcp::CommandOptions is a singleton class that parses
/// the perfdhcp command line parameters and initializes its members
/// accordingly. If the parameters are invalid, the parser method throws
/// an exception. Usage is simple:
///
/// @code int main(int argc, char* argv[]) {
/// try {
/// CommandOptions& command_options = CommandOptions::instance();
/// command_options.parse(argc, argv);
/// } catch(const Exception& e) {
/// ...
/// }
/// @endcode
///
/// If the argument parsing is successful, the parsed values can be read
/// from the isc::perfdhcp::CommandOptions singleton from any class or
/// function in the program, e.g.
///
/// @code
/// int rate = CommandOptions::instance().getRate();
/// @endcode
///
/// @subsection perfdhcpTestControl TestControl (Test Control)
///
/// The isc::perfdhcp::TestControl singleton is responsible
/// for test execution coordination. It relies on the
/// isc::perfdhcp::CommandOptions object to get all required test
/// parameters and for this reason, isc::perfdhcp::CommandOptions has
/// to be initialized and isc::perfdhcp::CommandOptions::parse() called
/// prior to calling isc::perfdhcp::TestControl::run().
///
/// isc::perfdhcp::TestControl::run() performs initialization of
/// isc::perfdhcp::TestControl then executes the main program loop. In
/// detail, isc::perfdhcp::TestControl::run() performs the following
/// major operations:
///
/// -# check if the command line has been parsed,
/// -# print diagnostics if specified from command line,
/// -# register DHCP options factory functions,
/// -# read packet templates from files,
/// -# initialize the isc::perfdhcp::StatisticsManager 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.
///
/// isc::perfdhcp::TestControl is a singleton object, so there is one sole
/// instance of it throughout the program. In order to allow the running
/// of unit tests, where a single instance of isc::perfdhcp::TestControl
/// is used multiple times with different command line options, a
/// isc::perfdhcp::TestControl::reset() function is provided to reset
/// the state of the class members. Also, functions that initialize
/// various class members (such as Statistics Manager) will release
/// any objects from previous test runs.
///
/// @subsection perfStatsMgr StatsMgr (Statistics Manager)
///
/// isc::perfdhcp::StatsMgr is a class that holds all performance
/// statistics gathered throughout the test execution and is created
/// in isc::perfdhcp::TestControl. isc::perfdhcp::TestControl posts all
/// sent and received packets to isc::perfdhcp::StatsMgr: outgoing packets
/// are recorded and incoming packets are matched with the corresponding
/// outgoing packer to calculate calculate round trip time, number of
/// packet drops etc. Apart from the standard counters implemented in
/// isc::perfdhcp::StatsMgr, custom (named) counters can be specified and
/// incremented by the calling class. isc::perfdhcp::StatsMgr also exposes
/// multiple functions that print gathered statistics into the console.
///
/// isc::perfdhcp::StatsMgr is a template class that takes an
/// isc::dhcp::Pkt4, isc::dhcp::Pkt6, isc::perfdhcp::PerfPkt4
/// or isc::perfdhcp::PerfPkt6 as a typename. An instance of
/// isc::perfdhcp::StatsMgr can be created by:
///
/// @code
/// 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;
/// }
/// @endcode
///
/// The isc::perfdhcp::StatsMgr instance created in the example above will be used
/// for DHCPv4 testing (i.e. to collect DHCPv4 packets) and will be
/// configured to monitor statistics for DISCOVER-OFFER packet exchanges.
///
/// @subsection perfdhcpPkt PerfPkt4 and PerfPkt6
///
/// The isc::perfdhcp::PerfPkt4 and isc::perfdhcp::PerfPkt6 classes
/// are derived from isc::dhcp::Pkt4 and isc::dhcp::Pkt6. They extend
/// the parent class functionality by adding support for template
/// files. Instances of these classes can be created using a raw buffer
/// (read from a packet template file). Once the packet object is
/// initialized, it is possible to replace parts of the on-wire data by
/// using the isc::perfdhcp::LocalizedOption mechanism.
///
/// @subsection perfdhcpLocalizedOption LocalizedOption (Localized Option)
///
/// isc::perfdhcp::LocalizedOption derives from the isc::dhcp::Option
/// class. It represents the DHCP option (v4 or v6) to be
/// placed at specified position in the packet buffer (see @ref
/// perfdhcpPkt). Such an option is added to the option collection in
/// a isc::perfdhcp::PerfPkt4 or isc::perfdhcp::PerfPkt6 object; when
/// any of PerfPktX::rawPack() functions are called their content is
/// stored in the packet output buffer at the position pointed to by
/// the isc::perfdhcp::LocalizedOption object.
///
/// isc::perfdhcp::LocalizedOption also allows the reading of the
/// on wire data in received packet at the specified position. In
/// this case, isc::perfdhcp::LocalizedOption has to be created and
/// added to the received packet. When PerfPktX::rawUnpack() is
/// called, the contents of the buffer will be read and stored in a
/// isc::perfdhcp::LocalizedOption object for further processing.
///
/// The following code shows how to create a packet from a
/// (template) buffer and replace option data in the buffer with
/// isc::perfdhcp::LocalizedOption.
///
/// @code
/// 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 the packet contents with option
/// // contents at buffer position 240.
/// pkt->rawPack();
/// @endcode
///
/// @subsection perfdhcpPktTransform PktTransform (Packet Transform)
///
/// The isc::perfdhcp::PktTransform helper class contains the
/// static functions to pack and unpack DHCP options (specifically
/// isc::perfdhcp::LocalizedOption) to and from the packet buffer. This
/// logic has been moved away from isc::perfdhcp::PerfPkt4 and
/// isc::perfdhcp::PerfPkt6 classes to isc::perfdhcp::PktTransform
/// because PerfPktX classes share the logic here.