wireprotov2: document client reactor actions
authorGregory Szorc <gregory.szorc@gmail.com>
Thu, 04 Oct 2018 15:43:21 -0700
changeset 40128 080419fa4fe4
parent 40127 327d40b94bed
child 40129 57782791b7e9
wireprotov2: document client reactor actions We should document these so consumers have an easier life. Differential Revision: https://phab.mercurial-scm.org/D4917
mercurial/wireprotoframing.py
--- a/mercurial/wireprotoframing.py	Thu Oct 04 16:26:45 2018 -0700
+++ b/mercurial/wireprotoframing.py	Thu Oct 04 15:43:21 2018 -0700
@@ -1309,6 +1309,40 @@
     the TCP socket. For transports where there are multiple discrete
     interactions (say tunneled within in HTTP request), there will be a
     separate instance for each distinct interaction.
+
+    Consumers are expected to tell instances when events occur by calling
+    various methods. These methods return a 2-tuple describing any follow-up
+    action(s) to take. The first element is the name of an action to
+    perform. The second is a data structure (usually a dict) specific to
+    that action that contains more information. e.g. if the reactor wants
+    to send frames to the server, the data structure will contain a reference
+    to those frames.
+
+    Valid actions that consumers can be instructed to take are:
+
+    noop
+       Indicates no additional action is required.
+
+    sendframes
+       Indicates that frames should be sent to the server. The ``framegen``
+       key contains a generator of frames that should be sent. The reactor
+       assumes that all frames in this generator are sent to the server.
+
+    error
+       Indicates that an error occurred. The ``message`` key contains an
+       error message describing the failure.
+
+    responsedata
+       Indicates a response to a previously-issued command was received.
+
+       The ``request`` key contains the ``commandrequest`` instance that
+       represents the request this data is for.
+
+       The ``data`` key contains the decoded data from the server.
+
+       ``expectmore`` and ``eos`` evaluate to True when more response data
+       is expected to follow or we're at the end of the response stream,
+       respectively.
     """
     def __init__(self, hasmultiplesend=False, buffersends=True):
         """Create a new instance.