Add more examples for better documentation.
BUG=None
TEST=unit testings for the pipeline stage, pipeline workers, generation,
steering, task, flag and hill climbing.
Change-Id: I1f8f361388d3c3171a7135d1d0ef38ee5f695829
Reviewed-on: https://gerrit-int.chromium.org/42584
Reviewed-by: Luis Lozano <llozano@chromium.org>
Commit-Queue: Yuheng Long <yuhenglong@google.com>
Tested-by: Yuheng Long <yuhenglong@google.com>
diff --git a/bestflags/flags.py b/bestflags/flags.py
index a89f630..37c2122 100644
--- a/bestflags/flags.py
+++ b/bestflags/flags.py
@@ -44,6 +44,11 @@
return rx.search(spec)
+class NoSuchFileError(Exception):
+ """Define an Exception class for user providing invalid input file."""
+ pass
+
+
def ReadConf(file_name):
"""Parse the configuration file.
@@ -54,24 +59,35 @@
Returns:
A list of specs in the configuration file.
+
+ Raises:
+ NoSuchFileError: The caller should provide a valid configuration file.
"""
with open(file_name, 'r') as input_file:
lines = input_file.readlines()
return sorted([line.strip() for line in lines if line.strip()])
- return []
+
+ raise NoSuchFileError()
class Flag(object):
"""A class representing a particular command line flag argument.
The Flag consists of two parts: The spec and the value.
- The spec is a definition in the little language, a string of the form
- [<start>-<end>] where start and end is an positive integer for a fillable
- value.
+ The spec is a definition of the following form: a string with escaped
+ sequences of the form [<start>-<end>] where start and end is an positive
+ integer for a fillable value.
An example of a spec is "foo[0-9]".
+ There are two kinds of flags, boolean flag and numeric flags. Boolean flags
+ can either be turned on or off, which numeric flags can have different
+ positive integer values. For example, -finline-limit=[1-1000] is a numeric
+ flag and -ftree-vectorize is a boolean flag.
+
+ A (boolean/numeric) flag is not turned on if it is not selected in the
+ FlagSet.
"""
def __init__(self, spec, value=-1):
diff --git a/bestflags/flags_util.py b/bestflags/flags_util.py
index 01cc8d6..23decaf 100644
--- a/bestflags/flags_util.py
+++ b/bestflags/flags_util.py
@@ -17,24 +17,37 @@
def ClimbNext(flags_dict, climb_spec):
"""Get the flags who are different from flags_dict by climb_spec.
+ An example flags_dict is {foo=[1-9]:foo=5, bar=[1-5]:bar=2} and climb_spec is
+ bar=[1-5]. This method changes the flag that contains the spec bar=[1-5]. The
+ results are its neighbors dictionaries, i.e., {foo=[1-9]:foo=5,
+ bar=[1-5]:bar=1} and {foo=[1-9]:foo=5, bar=[1-5]:bar=3}.
+
Args:
flags_dict: The dictionary containing the original flags whose neighbors are
to be explored.
- climb_spec: The spec in the flags_dict is to be changed.
+ climb_spec: The spec in the flags_dict is to be changed. The spec is a
+ definition in the little language, a string with escaped sequences of the
+ form [<start>-<end>] where start and end is an positive integer for a
+ fillable value. An example of a spec is "foo[0-9]".
Returns:
- A dictionary of neighbor flags.
+ Dictionaries of neighbor flags.
"""
- result = flags.Search(climb_spec)
+ # This method searches for a pattern [start-end] in the spec. If the spec
+ # contains this pattern, it is a numeric flag. Otherwise it is a boolean flag.
+ # For example, -finline-limit=[1-1000] is a numeric flag and -falign-jumps is
+ # a boolean flag.
+ numeric_flag_match = flags.Search(climb_spec)
# If the flags do not contain the spec.
if climb_spec not in flags_dict:
results = flags_dict.copy()
- if result:
+ if numeric_flag_match:
# Numeric flags.
- results[climb_spec] = Flag(climb_spec, int(result.group('start')))
+ results[climb_spec] = Flag(climb_spec,
+ int(numeric_flag_match.group('start')))
else:
# Boolean flags.
results[climb_spec] = Flag(climb_spec)
@@ -42,9 +55,12 @@
return [results]
# The flags contain the spec.
- if not result:
+ if not numeric_flag_match:
# Boolean flags.
results = flags_dict.copy()
+
+ # Turn off the flag. A flag is turned off if it is not presented in the
+ # flags_dict.
del results[climb_spec]
return [results]
@@ -55,21 +71,22 @@
value = flag.GetValue()
results = []
- if value + 1 < int(result.group('end')):
+ if value + 1 < int(numeric_flag_match.group('end')):
# If the value is not the end value, explore the value that is 1 larger than
# the current value.
neighbor = flags_dict.copy()
neighbor[climb_spec] = Flag(climb_spec, value + 1)
results.append(neighbor)
- if value > int(result.group('start')):
+ if value > int(numeric_flag_match.group('start')):
# If the value is not the start value, explore the value that is 1 lesser
# than the current value.
neighbor = flags_dict.copy()
neighbor[climb_spec] = Flag(climb_spec, value - 1)
results.append(neighbor)
else:
- # Delete the value.
+ # Delete the value, i.e., turn off the flag. A flag is turned off if it is
+ # not presented in the flags_dict.
neighbor = flags_dict.copy()
del neighbor[climb_spec]
results.append(neighbor)
diff --git a/bestflags/generation.py b/bestflags/generation.py
index 8e1358a..6fe851a 100644
--- a/bestflags/generation.py
+++ b/bestflags/generation.py
@@ -28,7 +28,7 @@
"""A generation of a framework run.
The base class of generation. Concrete subclasses, e.g., GAGeneration should
- override the Next and Improve method to implement algorithm specific
+ override the Next and Improved method to implement algorithm specific
applications.
"""
@@ -111,7 +111,7 @@
return True
- def Improve(self):
+ def Improved(self):
"""True if this generation has improvement upon its parent generation.
Raises:
diff --git a/bestflags/genetic_algorithm.py b/bestflags/genetic_algorithm.py
index 56b1dcc..0e7de07 100644
--- a/bestflags/genetic_algorithm.py
+++ b/bestflags/genetic_algorithm.py
@@ -200,7 +200,7 @@
Generation.__init__(self, tasks, parents)
self._total_stucks = total_stucks
- def Improve(self):
+ def Improved(self):
"""True if this generation has improvement upon its parent generation."""
tasks = self.Pool()
@@ -216,7 +216,7 @@
best_current = sorted(tasks, key=lambda task: task.GetTestResult())[0]
# At least one task has improvement.
- if best_current.Improve(best_parent):
+ if best_current.Improved(best_parent):
self._total_stucks = 0
return True
diff --git a/bestflags/hill_climb_best_neighbor.py b/bestflags/hill_climb_best_neighbor.py
index 5bc3f7e..aec420f 100644
--- a/bestflags/hill_climb_best_neighbor.py
+++ b/bestflags/hill_climb_best_neighbor.py
@@ -41,7 +41,7 @@
Generation.__init__(self, exe_pool, parents)
self._specs = specs
- def Improve(self):
+ def Improved(self):
"""True if this generation has improvement over its parent generation.
Returns:
@@ -51,7 +51,7 @@
# Find the best neighbor.
best_task = None
for task in self._exe_pool:
- if not best_task or task.Improve(best_task):
+ if not best_task or task.Improved(best_task):
best_task = task
if not best_task:
@@ -63,7 +63,7 @@
assert len(parents) == 1
self._next_task = best_task
# If the best neighbor improves upon the parent task.
- return best_task.Improve(parents[0])
+ return best_task.Improved(parents[0])
self._next_task = best_task
return True
diff --git a/bestflags/steering.py b/bestflags/steering.py
index 2f889ca..5cdf8ae 100644
--- a/bestflags/steering.py
+++ b/bestflags/steering.py
@@ -99,7 +99,7 @@
# A generation may not generate the next generation, e.g., because a
# fixpoint has been reached, there has not been any improvement for a few
# generations or a local maxima is reached.
- if not generation.Improve():
+ if not generation.Improved():
continue
for new_generation in generation.Next(cache):
diff --git a/bestflags/steering_test.py b/bestflags/steering_test.py
index b3ce686..5063079 100644
--- a/bestflags/steering_test.py
+++ b/bestflags/steering_test.py
@@ -53,7 +53,7 @@
def Next(self, _):
return self._next_generations
- def Improve(self):
+ def Improved(self):
if self._next_generations:
return True
return False
diff --git a/bestflags/task.py b/bestflags/task.py
index 7790160..b20493f 100644
--- a/bestflags/task.py
+++ b/bestflags/task.py
@@ -31,7 +31,7 @@
# the build should attempt before giving up.
BUILD_TRIES = 3
-# The maximum number of tries a build can have. Some tests may fail due to
+# The maximum number of tries a test can have. Some tests may fail due to
# unexpected environment circumstance. This variable defines how many tries the
# test should attempt before giving up.
TEST_TRIES = 3
@@ -391,7 +391,7 @@
# Write out the result in the comma-separated format (CSV).
out_file.write('%s,%s,%s\n' % test_result)
- def Improve(self, other):
+ def Improved(self, other):
"""Compare the current task with another task.
Args:
