diff options
author | Yuheng Long <yuhenglong@google.com> | 2013-08-08 21:07:24 -0700 |
---|---|---|
committer | ChromeBot <chrome-bot@google.com> | 2013-08-10 20:26:39 -0700 |
commit | 2b514c28dd26aa02c2ea0f9924be91fb2394c8a0 (patch) | |
tree | e2a9532a20096b0f22b0ee838dbccd364e09027f | |
parent | bbbd8645405a7058b8e6d17dc1fdec14cbff4f08 (diff) | |
download | toolchain-utils-2b514c28dd26aa02c2ea0f9924be91fb2394c8a0.tar.gz |
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>
-rw-r--r-- | bestflags/flags.py | 24 | ||||
-rw-r--r-- | bestflags/flags_util.py | 35 | ||||
-rw-r--r-- | bestflags/generation.py | 4 | ||||
-rw-r--r-- | bestflags/genetic_algorithm.py | 4 | ||||
-rw-r--r-- | bestflags/hill_climb_best_neighbor.py | 6 | ||||
-rw-r--r-- | bestflags/steering.py | 2 | ||||
-rw-r--r-- | bestflags/steering_test.py | 2 | ||||
-rw-r--r-- | bestflags/task.py | 4 |
8 files changed, 57 insertions, 24 deletions
diff --git a/bestflags/flags.py b/bestflags/flags.py index a89f6301..37c21226 100644 --- a/bestflags/flags.py +++ b/bestflags/flags.py @@ -44,6 +44,11 @@ def Search(spec): 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 @@ def ReadConf(file_name): 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 01cc8d66..23decafd 100644 --- a/bestflags/flags_util.py +++ b/bestflags/flags_util.py @@ -17,24 +17,37 @@ from flags import Flag 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 @@ def ClimbNext(flags_dict, climb_spec): 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 @@ def ClimbNext(flags_dict, climb_spec): 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 8e1358ad..6fe851a8 100644 --- a/bestflags/generation.py +++ b/bestflags/generation.py @@ -28,7 +28,7 @@ class Generation(object): """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 @@ class Generation(object): 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 56b1dcc1..0e7de07f 100644 --- a/bestflags/genetic_algorithm.py +++ b/bestflags/genetic_algorithm.py @@ -200,7 +200,7 @@ class GAGeneration(Generation): 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 @@ class GAGeneration(Generation): 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 5bc3f7ed..aec420f9 100644 --- a/bestflags/hill_climb_best_neighbor.py +++ b/bestflags/hill_climb_best_neighbor.py @@ -41,7 +41,7 @@ class HillClimbingBestBranch(Generation): 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 @@ class HillClimbingBestBranch(Generation): # 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 @@ class HillClimbingBestBranch(Generation): 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 2f889ca1..5cdf8aed 100644 --- a/bestflags/steering.py +++ b/bestflags/steering.py @@ -99,7 +99,7 @@ def Steering(cache, generations, input_queue, result_queue): # 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 b3ce686d..5063079c 100644 --- a/bestflags/steering_test.py +++ b/bestflags/steering_test.py @@ -53,7 +53,7 @@ class MockGeneration(Generation): 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 77901602..b20493fd 100644 --- a/bestflags/task.py +++ b/bestflags/task.py @@ -31,7 +31,7 @@ ERROR_STRING = 'error' # 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 @@ class Task(object): # 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: |