Add a example which uses the run_iter function in a for loop

The run iteration capability can be used to iterate over the
engines activity and do various other activities in-between
the engine state iteration; this example shows a primitive
use of this to output the state counter and the transition
itself.

Change-Id: I63ac343566a4a090a20a84c626ddea3651033926

taskflow/examples/run_by_iter_enumerate.out.txt

@@ -0,0 +1,42 @@
+Transition 1: RESUMING
+Transition 2: SCHEDULING
+echo_1
+Transition 3: WAITING
+Transition 4: ANALYZING
+Transition 5: SCHEDULING
+echo_2
+Transition 6: WAITING
+Transition 7: ANALYZING
+Transition 8: SCHEDULING
+echo_3
+Transition 9: WAITING
+Transition 10: ANALYZING
+Transition 11: SCHEDULING
+echo_4
+Transition 12: WAITING
+Transition 13: ANALYZING
+Transition 14: SCHEDULING
+echo_5
+Transition 15: WAITING
+Transition 16: ANALYZING
+Transition 17: SCHEDULING
+echo_6
+Transition 18: WAITING
+Transition 19: ANALYZING
+Transition 20: SCHEDULING
+echo_7
+Transition 21: WAITING
+Transition 22: ANALYZING
+Transition 23: SCHEDULING
+echo_8
+Transition 24: WAITING
+Transition 25: ANALYZING
+Transition 26: SCHEDULING
+echo_9
+Transition 27: WAITING
+Transition 28: ANALYZING
+Transition 29: SCHEDULING
+echo_10
+Transition 30: WAITING
+Transition 31: ANALYZING
+Transition 32: SUCCESS

taskflow/examples/run_by_iter_enumerate.py

@@ -0,0 +1,59 @@
+# -*- coding: utf-8 -*-
+
+#    Copyright (C) 2014 Yahoo! Inc. All Rights Reserved.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+import logging
+import os
+import sys
+
+logging.basicConfig(level=logging.ERROR)
+
+self_dir = os.path.abspath(os.path.dirname(__file__))
+top_dir = os.path.abspath(os.path.join(os.path.dirname(__file__),
+                                       os.pardir,
+                                       os.pardir))
+sys.path.insert(0, top_dir)
+sys.path.insert(0, self_dir)
+
+from taskflow.engines.action_engine import engine
+from taskflow.patterns import linear_flow as lf
+from taskflow.persistence.backends import impl_memory
+from taskflow import task
+from taskflow.utils import persistence_utils
+
+# INTRO: This examples shows how to run a engine using the engine iteration
+# capability, in between iterations other activities occur (in this case a
+# value is output to stdout); but more complicated actions can occur at the
+# boundary when a engine yields its current state back to the caller.
+
+
+class EchoNameTask(task.Task):
+    def execute(self):
+        print(self.name)
+
+
+f = lf.Flow("counter")
+for i in range(0, 10):
+    f.add(EchoNameTask("echo_%s" % (i + 1)))
+
+be = impl_memory.MemoryBackend()
+book = persistence_utils.temporary_log_book(be)
+fd = persistence_utils.create_flow_detail(f, book, be)
+e = engine.SingleThreadedActionEngine(f, fd, be, {})
+e.compile()
+e.prepare()
+
+for i, st in enumerate(e.run_iter(), 1):
+    print("Transition %s: %s" % (i, st))