diff options
Diffstat (limited to 'src/bin/perfdhcp/perfdhcp_internals.dox')
| -rw-r--r-- | src/bin/perfdhcp/perfdhcp_internals.dox | 164 |
1 files changed, 164 insertions, 0 deletions
diff --git a/src/bin/perfdhcp/perfdhcp_internals.dox b/src/bin/perfdhcp/perfdhcp_internals.dox new file mode 100644 index 0000000..078cb57 --- /dev/null +++ b/src/bin/perfdhcp/perfdhcp_internals.dox @@ -0,0 +1,164 @@ +// Copyright (C) 2012-2015 Internet Systems Consortium, Inc. ("ISC") +// +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at http://mozilla.org/MPL/2.0/. + +/// @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. |