From cd13ec7c13abeb5f10cc584ab7f48c7f13f1785c Mon Sep 17 00:00:00 2001 From: Christian Monch Date: Mon, 23 Oct 2023 11:16:11 +0200 Subject: [PATCH] improve description of required actions This commit addresses comment https://github.com/datalad/datalad-next/pull/476#discussion_r1366839035. 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. --- docs/source/developer_guide/generator-runner.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/source/developer_guide/generator-runner.rst b/docs/source/developer_guide/generator-runner.rst index ddbbfecc..27e8074f 100644 --- a/docs/source/developer_guide/generator-runner.rst +++ b/docs/source/developer_guide/generator-runner.rst @@ -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