Skip to content

Commit

Permalink
improve description of required actions
Browse files Browse the repository at this point in the history
This commit addresses comment
#476 (comment).

It modifies the explanation to describe:

 a) what needs to be done, and
 b) what is done in provided generator-protocols

That should help to comprehend what
a user has to do, when implementing
a new protocol.
  • Loading branch information
christian-monch committed Oct 23, 2023
1 parent 3429099 commit cd13ec7
Showing 1 changed file with 5 additions and 4 deletions.
9 changes: 5 additions & 4 deletions docs/source/developer_guide/generator-runner.rst
Original file line number Diff line number Diff line change
Expand Up @@ -93,10 +93,11 @@ Whenever the caller invokes ``send()`` on the generator, e.g. by iterating over
5. The subprocess has exited, the next call to the its ``send()``-method will retrieve the exit status of the subprocess and end the iteration by raising ``StopIteration``.

From the description above and from the figure it should be clear, that, if a user wants to receive output from a subprocess and not just wait for its exit, the user has to send
data that is received via ``pipe_data_received`` to the result queue of the result generator.
That means basically he has to call ``send_result()``.
This is not automatically mixed into the protocol class by ``GeneratorMixIn``.
A minimal generator protocol would therefore look like this.
data that is received via the ``pipe_data_received``-callback of the protocol to the result queue of the result generator.
Because the ``GeneratorMixIn``-class does not overwrite ``pipe_data_received``, the respective generator protocol has to implement a ``pipe_data_received``-callback that eventually calls ``send_result()``.
All provided generator protocols behave this way.
If a user implements a new generator protocol, he has to implement this behavior himeself.
A minimal generator protocol that makes all data that is given as argument to ``pipe_data_received`` available at the result generator could therefore look like this:

.. code-block:: python
Expand Down

0 comments on commit cd13ec7

Please sign in to comment.