Skip to content

gh-92679: Clarify roles of asyncio protocols and transports #92680

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 8 commits into from
24 changes: 12 additions & 12 deletions Doc/library/asyncio-protocol.rst
Original file line number Diff line number Diff line change
Expand Up @@ -23,21 +23,21 @@ This documentation page covers both `Transports`_ and `Protocols`_.

.. rubric:: Introduction

At the highest level, the transport is concerned with *how* bytes
are transmitted, while the protocol determines *which* bytes to
transmit (and to some extent when).
The transport is an interface for a source of raw bytes,
while the protocol represents a consumer of these bytes that may answer back.

A different way of saying the same thing: a transport is an
abstraction for a socket (or similar I/O endpoint) while a protocol
is an abstraction for an application, from the transport's point
of view.
The protocol object may either generate and consume data on its own (like a
fallback background sender behind :func:`~asyncio.loop.sendfile`), be an
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have no idea what a "fallback background sender" would be or why sendfile is used here. I suppose I could look it up in the source, but that's asking a bit much in a section labeled "Introduction". It should speak for itself.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm sorry for postponing the stuff for so long. I've got a load of thesis work in the university so I'll be free and able to address all the comments a couple of weeks later.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, I am patiently waiting.

adapter for another I/O interface (like the
:func:`~asyncio.StreamReader`/:func:`~asyncio.StreamWriter` backend),
or play a role of a converter middle man between other transport and protocol
(like the one created by :func:`~asyncio.loop.start_tls`).

Yet another view is the transport and protocol interfaces
together define an abstract interface for using network I/O and
interprocess I/O.
While the transport is actively puppeteered by an asyncio event loop, the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"puppeteered" is a bit poetic for technical documentation. :-)

protocol is passively triggered by events from the transport.

There is always a 1:1 relationship between transport and protocol
objects: the protocol calls transport methods to send data,
There is always a 1:1 relationship between immediately communicating transport
and protocol objects: the protocol calls transport methods to send data,
while the transport calls protocol methods to pass it data that
has been received.

Expand Down