Add docs

Author: 1st1

Doc/library/asyncio-protocol.rst

@@ -333,6 +333,16 @@ Protocol classes
    The base class for implementing streaming protocols (for use with
    e.g. TCP and SSL transports).
 
+.. class:: BufferedProtocol
+
+   A base class for implementing streaming protocols with manual
+   control of the receive buffer.
+
+   .. versionadded:: 3.7
+      **Important:** this has been been added to asyncio in Python 3.7
+      *on a provisional basis*!  Treat it as an experimental API that
+      might be changed or removed in Python 3.8.
+
 .. class:: DatagramProtocol
 
    The base class for implementing datagram protocols (for use with
@@ -428,9 +438,66 @@ and, if called, :meth:`data_received` won't be called after it.
 
 State machine:
 
+.. code-block:: none
+
+    start -> :meth:`~BaseProtocol.connection_made`
+        [-> :meth:`~Protocol.data_received`]*
+        [-> :meth:`~Protocol.eof_received`]?
+    -> :meth:`~BaseProtocol.connection_lost` -> end
+
+
+Streaming protocols with manual receive buffer control
+------------------------------------------------------
+
+.. versionadded:: 3.7
+   **Important:** :class:`BufferedProtocol` has been been added to
+   asyncio in Python 3.7 *on a provisional basis*!  Treat it as an
+   experimental API that might be changed or removed in Python 3.8.
+
+
+Event methods, such as :meth:`AbstractEventLoop.create_server` and
+:meth:`AbstractEventLoop.create_connection`, accept factories that
+return protocols that implement this interface.
+
+The idea of BufferedProtocol is that it allows to manually allocate
+and control the receive buffer.  Event loops can then use the buffer
+provided by the protocol to avoid unnecessary data copies.  This
+can result in noticeable performance improvement for protocols that
+receive big amounts of data.  Sophisticated protocols can allocate
+the buffer only once at creation time.
+
+The following callbacks are called on :class:`BufferedProtocol`
+instances:
+
+.. method:: BufferedProtocol.get_buffer()
+
+   Called to allocate a new receive buffer.  Must return an object
+   that implements the :ref:`buffer protocol <bufferobjects>`.
+
+.. method:: BufferedProtocol.buffer_updated(nbytes)
+
+   Called when the buffer was updated with the received data.
+
+   *nbytes* is the total number of bytes that were written to the buffer.
+
+.. method:: BufferedProtocol.eof_received()
+
+   See the documentation of the :meth:`Protocol.eof_received` method.
+
+
+:meth:`get_buffer` can be called an arbitrary number of times during
+a connection.  However, :meth:`eof_received` is called at most once
+and, if called, :meth:`data_received` won't be called after it.
+
+State machine:
+
+.. code-block:: none
+
     start -> :meth:`~BaseProtocol.connection_made`
-    [-> :meth:`~Protocol.data_received` \*]
-    [-> :meth:`~Protocol.eof_received` ?]
+        [-> :meth:`~BufferedProtocol.get_buffer`
+            [-> :meth:`~BufferedProtocol.buffer_updated`]?
+        ]*
+        [-> :meth:`~Protocol.eof_received`]?
     -> :meth:`~BaseProtocol.connection_lost` -> end
 
 

Lib/asyncio/protocols.py

@@ -103,11 +103,46 @@ def eof_received(self):
 
 
 class BufferedProtocol(BaseProtocol):
+    """Interface for stream protocol with manual buffer control.
+
+    Important: this has been been added to asyncio in Python 3.7
+    *on a provisional basis*!  Treat it as an experimental API that
+    might be changed or removed in Python 3.8.
+
+    Event methods, such as `create_server` and `create_connection`,
+    accept factories that return protocols that implement this interface.
+
+    The idea of BufferedProtocol is that it allows to manually allocate
+    and control the receive buffer.  Event loops can then use the buffer
+    provided by the protocol to avoid unnecessary data copies.  This
+    can result in noticeable performance improvement for protocols that
+    receive big amounts of data.  Sophisticated protocols can allocate
+    the buffer only once at creation time.
+
+    State machine of calls:
+
+      start -> CM [-> GB [-> BU?]]* [-> ER?] -> CL -> end
+
+    * CM: connection_made()
+    * GB: get_buffer()
+    * BU: buffer_updated()
+    * ER: eof_received()
+    * CL: connection_lost()
+    """
+
     def get_buffer(self):
-        raise NotImplementedError
+        """Called to allocate a new receive buffer.
+
+        Must return an object that implements the
+        :ref:`buffer protocol <bufferobjects>`.
+        """
 
     def buffer_updated(self, nbytes):
-        pass
+        """Called when the buffer was updated with the received data.
+
+        *nbytes* is the total number of bytes that were written to
+        the buffer.
+        """
 
     def eof_received(self):
         """Called when the other end calls write_eof() or equivalent.