Issue #114: add more documentation to the Runner

byexample/executor.py

@@ -66,27 +66,29 @@ def on_failure_shutdown_runners(
 
     @profile
     def initialize_runners(self, runners, options):
-        tmp = []
+        # in case of an error, these are the runners initialized so far
+        # that we must shutdown
+        so_far = []
         for runner in runners:
             with log_with(runner.language) as log:
                 if runner in self.still_alive_runners:
                     log.info("Reusing %s", str(runner))
-                    tmp.append(runner)
+                    so_far.append(runner)
                     continue
 
                 log.info("Initializing %s", str(runner))
                 with self.on_failure_shutdown_runners(
                     should_raise=True,
-                    runners_left=tmp,
+                    runners_left=so_far,
                     err_args=("Initialization of %s failed.", str(runner))
                 ):
                     runner.initialize(options)
                     self.still_alive_runners.add(runner)
-                    tmp.append(runner)
+                    so_far.append(runner)
 
         # or we have all of them or we should not be executing this line
         # because something failed and an exception should be flying around
-        assert len(tmp) == len(runners)
+        assert len(so_far) == len(runners)
 
         # the 'equal or greater than' is needed because some runners may had
         # been initialized in another round and they are not going to be used
@@ -95,6 +97,7 @@ def initialize_runners(self, runners, options):
 
     @profile
     def reset_runners(self, runners, should_raise=True, force_shutdown=True):
+        # in case of an error, these are the runners that we must shutdown
         left = list(runners)
         for runner in runners:
             with log_with(runner.language) as log:

byexample/runner.py

@@ -72,6 +72,21 @@ def initialize(self, options):
         executing any example.
 
         See also shutdown()
+
+        The following state diagram should picture this:
+
+                           new file,
+        (not alive) --> call initialize() --> (alive, clean) --> call run() <-|
+              ^                                      ^               |        |
+              |                                      |               v        |
+              |                                 reset True    (alive, dirty) -/
+              |                                      ^               |
+              |                     if forced        |               v
+              |                  /- shutdown  <----- | ----- no more examples;
+              |                 /                    |               |
+              |                /                     |               v
+         call shutdown() <----/- reset False or  <---\---- not forced shutdown,
+                                     failed                   call reset()
         '''
         raise NotImplementedError()  # pragma: no cover
 
@@ -85,7 +100,9 @@ def shutdown(self):
         of examples (another file) so *no* shutdown will be done.
 
         shutdown() will **not** be called as long as reset() is being
-        called and returning True.
+        called and returning True in general but it *MAY* be called even that
+        if an error is detected in another runner or the whole execution
+        is shutting down.
 
         Otherwise it will be called after executing each file's examples.