* - @subpage libdhcp
* - @subpage libdhcpIntro
* - @subpage libdhcpIfaceMgr
+ * - @subpage perfdhcpInternals
*
* @section misc Miscellaneous topics
* - @subpage LoggingApi
* @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
- */
\ No newline at end of file
+ */
pkglibexec_PROGRAMS = perfdhcp
perfdhcp_SOURCES = perfdhcp.c
+
+# ... and the documentation
+EXTRA_DIST = perfdhcp_internals.dox
+++ /dev/null
-<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 © 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 1. Introduction"><div class="titlepage"><div><div><h2 class="title"><a name="perfdhcp-refactoring"></a>Chapter 1. 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 2. Classes"><div class="titlepage"><div><div><h2 class="title"><a name="perfdhcp-classes"></a>Chapter 2. 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& command_options = CommandOptions::instance();
- command_options.parse(argc, argv);
-catch(const Exception& 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<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;
-}
-
- </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 “PerfPkt4, PerfPkt6 (perf_pkt4.h .cc, perf_pkt6.h .cc)”</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<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();
-
- </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>
\ No newline at end of file
+++ /dev/null
-<?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 "—" >
-<!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>
--- /dev/null
+// 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.
projects / thirdparty / kea.git / commitdiff
