documented loadQueryData.

git-svn-id: svn://bind10.isc.org/svn/bind10/branches/trac241@2499 e5f2f494-b856-4b98-b285-d166d9295462

src/lib/bench/benchmark_util.h

@@ -28,18 +28,104 @@ class RRClass;
 }
 
 namespace bench {
+/// \brief An exception that is thrown if an error occurs within the benchmark
+/// module.
 class BenchMarkError : public Exception {
 public:
     BenchMarkError(const char* file, size_t line, const char* what) :
         isc::Exception(file, line, what) {}
 };
 
+/// \brief A convenient shortcut type to represent a sequence of query %data
+/// in wire format.
 typedef std::vector<std::vector<unsigned char> > BenchQueries; 
 
-/// Describe exception guarantee.  This function only offers the basic
-/// exception guarantee.
+/// \brief Load query %data from a file into a vector.
+///
+/// The format of the %data file is a sequence of tuples of query name and
+/// query type.  Each line specifies a single tuple.  Empty lines and
+/// lines beginning with a pound sign (#) are considered comments and will
+/// be ignored.  Example:
+/// \code
+/// # This is a comment line, will be ignored.  same for the next line.
+///
+/// www.example.com AAAA
+/// ftp.example.org NS
+/// text.dot.example TXT \endcode
+///
+/// For those who are familiar with BIND 9's queryperf tool, this is the
+/// same as the simplest form of the input file for queryperf.
+///
+/// For each tuple, this function builds a wire-format non recursive DNS
+/// query message, and appends it to the given vector in a form of
+/// a vector of <code>unsigned char</code>.
+///
+/// The resulting vector can be used, e.g., for benchmarking query processing
+/// code without involving disk access or network I/O.
+/// It would be handier than existing tool such as queryperf and can help
+/// measure the "bare" (or the best possible) performance of the query
+/// processing itself.
+///
+/// If this function fails to open the specified file to read the %data,
+/// an exception of class \c BenchMarkError will be thrown.
+/// If it fails to recognize an input line either as a comment or as
+/// a tuple of strings, an exception of class \c BenchMarkError will be
+/// thrown.
+///
+/// By default, this function does not require the strings be a valid
+/// domain name or a valid textual representation of an RR type.
+/// This is because the input %data may be built from a packet dump of
+/// real query samples without validation, which may contain bogus values.
+/// It would make more sense to just ignore the bogus %data than filter
+/// the sample beforehand.
+/// This behavior can be changed by setting the \c strict argument to
+/// \c true, in which case if this function fails to parse the query name
+/// or the type, it will throw an exception of class \c BenchMarkError.
+///
+/// If memory allocation fails during the processing, a corresponding standard
+/// exception will be thrown.
+///
+/// This function only offers the basic exception guarantee.  That is, if
+/// exception is thrown from this function, it is not guaranteed that
+/// \c queries keeps the content before this function is called.
+/// It is not so difficult to offer a stronger exception guarantee, but
+/// since this function is used in a limited usage, mainly for testing
+/// purposes, its benefit wouldn't outweigh the implementation complexity.
+///
+/// \param input_file A character string specifying the %data file name.
+/// \param queries A vector wherein the query %data is to be stored.
+/// \param qclass The RR class of the resulting queries.  The same RR class
+/// is used for all queries.
+/// \param strict If \c true, apply stricter validation on the query name and
+/// query RR types; otherwise invalid inputs will be ignored.
 void loadQueryData(const char* input_file, BenchQueries& queries,
                    const isc::dns::RRClass& qclass, const bool strict = false);
+
+/// \brief Load query %data from an input stream into a vector.
+///
+/// This version of function is same as
+/// loadQueryData(const char*,  BenchQueries&, const isc::dns::RRClass&, const bool)
+/// except it reads the input query sequence from a specified input stream.
+///
+/// This version will be used for a smaller scale test where query %data is
+///  hardcoded in the benchmark source code.  For example, we could build
+/// a sequence of wire-format queries via the following code:
+/// \code
+///    vector<QueryParam> queries;
+///    stringstream qstream;
+///    qstream << "www.example.com AAAA" << endl
+///            << "ftp.example.org NS" << endl
+///            << "text.dot.example TXT" << endl;
+///    loadQueryData(qstream, queries, RRClass::IN()); \endcode
+/// This will result in the same sequence of queries as the example using
+/// a %data file shown in the other version of the function.
+///
+/// \param input An input stream object that is to emit the query sequence.
+/// \param queries A vector wherein the query %data is to be stored.
+/// \param qclass The RR class of the resulting queries.  The same RR class
+/// is used for all queries.
+/// \param strict If \c true, apply stricter validation on the query name and
+/// query RR types; otherwise invalid inputs will be ignored.
 void loadQueryData(std::istream& input, BenchQueries& queries,
                    const isc::dns::RRClass& qclass, const bool strict = false);
 }