Step 1 - Coroutine Concept

To explain the concept in full detail let us look at standard function calls again.

def function():
    # do something
    return # some value

def other_function():
    # do something else
    return # another value

some_value = function()
another_value = other_function()

As a sequence diagram:

sequenceDiagram participant c as Caller participant f1 as Function participant f2 as Other Function activate c activate c c->>f1: call deactivate c activate f1 f1->>c: return deactivate f1 activate c c->>f2: call deactivate c activate f2 f2->>c: return deactivate f2 deactivate c

All function calls are run in a sequence. The caller must wait until the function is finished to execute its next code, for example another function call.

Besides let us take a look at Generators/Iterators.

def generator():
    # do something
    yield # something
    # do something else
    yield # something else
    # do another thing
    return # some value

def function():
    # do something
    return # a value


gen = generator()
next(gen)
next(gen)
a_value = function()
try:
    next(gen)
except StopIteration as e:
    some_value = e.value

Also as a sequence diagram:

sequenceDiagram participant c as Caller participant g as Generator participant f as Function activate c activate c c->>g: next deactivate c activate g activate g g-->>c: yield deactivate g activate c c->>g: next deactivate c activate g g-->>c: yield deactivate g activate c c->>f: call deactivate c activate f f->>c: return deactivate f activate c c->>g: next deactivate c activate g g->>c: return/StopIteration deactivate g deactivate g deactivate c

A Generator can yield values to the caller during its execution. The caller can request the next value from the Generator and do other things in between for example calling a function.

Summary

• Calling a function blocks the caller until the function returns.

• A Generator can give control back to the caller.

• The caller can do other things after getting in control again like calling another function.

• The caller can resume the Generator.

• The caller doesn’t need to be interested in the yielded values.

• A Generator can return a final value just like a normal function.

• A Generator is a coroutine.

Note

When mentioning the term coroutine in the following steps of this chapter, it references a Python generator function or generator object.