CR Updates (#220)

tools/db_bench_tool.cc

@@ -110,9 +110,33 @@ using GFLAGS_NAMESPACE::SetUsageMessage;
 #define IF_ROCKSDB_LITE(Then, Else) Else
 #endif
 
-// This is NOT a gflags flag but is defined as is only so it is displayed in the
-// gflags help (generated automatically)
-DEFINE_string(groups, "", "Run db_bench in benchmark groups mode.");
+// The groups flags is NOT a standard GFLAGS flag. It is a special flag that is
+// used to indicate that the tool is run in a multiple-groups mode (see the help
+// description for the flag for more details). It is defined using GFLAGS
+// definition syntax so it is included in GFLAGS' automatic help generation.
+DEFINE_string(
+    groups, "",
+    "Run db_bench in benchmark groups mode (The default is single-group mode). "
+    "In this mode benchmarks "
+    "are grouped, "
+    "and each group has its own configuration (values for the "
+    "supported flags). "
+    "The first group is the MASTER group. This group sets the "
+    "initial configuration "
+    "for all subsequent groups. Subsequent groups may override the "
+    "initial configuration. \nSyntax: ./db_bench -groups '<group1>' '<group2>' "
+    "'<group3>' ...  \n"
+    "Each group consists of valid db_bench flags, and, most likely, a set of "
+    "benchmarks to run as part of that group. "
+    "\nNotes:\n"
+    "1.DB-s are opened when running the master group. They stay open in "
+    "subsequent groups.\n"
+    "2.Benchmarks that require a fresh db (e.g. fillXXX benchmarks) may only "
+    "be run in the master group.\n"
+    "3.DB options may only be configured during the running of the master "
+    "group. Attempting to override them later is SILENTLY ignored.\n"
+    "4.Some additional flags may only be set for the master group (e.g., "
+    "env-related flags).");
 
 DEFINE_string(
     benchmarks,
@@ -1289,8 +1313,6 @@ DEFINE_string(fs_uri, "",
               " with --env_uri."
               " Creates a default environment with the specified filesystem.");
 #endif  // ROCKSDB_LITE
-// TODO - It seems the following 3 flags need to be inside the '#ifndef
-// ROCKSDB_LITE' macros
 DEFINE_string(simulate_hybrid_fs_file, "",
               "File for Store Metadata for Simulate hybrid FS. Empty means "
               "disable the feature. Now, if it is set, "
@@ -9012,48 +9034,54 @@ int db_bench_tool_run_group(int group_num, int num_groups, int argc,
 //
 // There are 2 modes of operation:
 // 1. Single-group: The tool is run with a set of flags once, running all
-//    specified benchmarks and exiting. This is the default mode.
+//    specified benchmarks and exiting. This is the DEFULT mode.
 // 2. Multiple-groups: Benchmarks are grouped. Each group has its own
-//    configuration. The first group (the master group) sets the initial
-//    configuration
-//     for all subsequent groups. Subsequent groups may override the initial
-//     configuration.
+//    configuration. The first group (the MASTER group) sets the initial
+//    configuration for all subsequent groups. Subsequent groups may override
+//    the initial configuration (some limitations apply, see below).
 //
-//    Important: The DB-s are also opened when the first group runs. When one
-//    group completes and the next starts,
-//     the db-s are retained (they are kept open). However, the DB options are
-//     set when the DB-s are opened. Therefore, attempts to override options in
-//     subsequent groups are silently ignored.
+// The mode is controlled via the 'groups' "flag". When the user sets the 2nd
+// argument to be the string '-groups', the tool will run in mutliple-groups
+// mode. Otherwise (and by default), The tool will run in the single-group mode.
 //
 // The syntax for multiple-configs is as follows:
-//
+// ----------------------------------------------
 // ./db_bench -groups '<group1>' '<group2>' '<group3>' ...
 //
 // Each group consists of valid db_bench flag, and, most likely, a set of
 // benchmarks to run as part of that group. Note however that there are certain
 // flags that are prohibited in non-master groups (e.g., the -db).
 //
 // For example:
+// ------------
 // ./db_bench -groups '-num 100 -benchmarks "fillseq,readrandom"' '-num 200
-// -benchmarks readrandom' '-benchmarks readrandom -reads 10000'
+//    -benchmarks readrandom' '-benchmarks readrandom -reads 10000'
 //
-// group1:
-// The fillseq,readrandom benchmarks will run. FLAGS_num=100 and all
-// other flags have their default values as usual.
+// group1: The fillseq,readrandom benchmarks will run.
+//         FLAGS_num=100
+//         All other flags have their default values as usual.
 //
-// group2:
-// The readrandom benchmark will run. FLAGS_num=200
+// group2: The readrandom benchmark will run.
+//         FLAGS_num=200
 //
-// group3:
-// The readrandom benchmark will run.
-// FLAGS_num=100 (wasn't overridden in this group), FLAGS_reads=10000
+// group3: The readrandom benchmark will run.
+//         FLAGS_num=100 (wasn't overridden in this group)
+//         FLAGS_reads=10000
 //
-// Note that all the groups after the first one assume you are using the same DB
-// (they enforce FLAGS_use_existing_db=true) => the tool will abort execution if
-// the user requests to run a benchmark that requires a fresh db (e.g.,
-// requesting the 'fillseq' benchmark)
+// Notes:
+// 1. The DB-s are opened when the master group runs. When one group completes
+//     and the next starts,
+//     the db-s are retained (they are kept open). However, the DB options are
+//     set only when the DB-s are opened. Therefore, attempts to override
+//     options in subsequent groups are SILENTLY ignored.
+// 2. A consequence of (1) is that an attempt to run benchmarks that require a
+//     fres db in groups > 1
+//     will abort the execution (e.g.,// requesting the 'fillseq' benchmark).
+// 3. Some additional flags may only be set for the master group (e.g.,
+//     env-related flags)
 //
 // Return Value:
+// -------------
 // 0 If all of the groups completed successfully or an error reported by the
 // runner of the failed group (subsequent groups will NOT be run).
 //