traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

#11979: improve wording and markup in sockets howto. Patch by Xavier Morel.

This commit is contained in:
Ezio Melotti 2011-05-14 09:17:52 +03:00
parent 4dcb7be696
commit 9b323a521c
1 changed files with 17 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
Doc/howto/sockets.rst
View File

@ -43,10 +43,10 @@ web server it's talking to uses both "server" sockets and "client" sockets.
History History
------- -------
Of the various forms of IPC (*Inter Process Communication*), sockets are by far Of the various forms of :abbr:`IPC (Inter Process Communication)`,
the most popular. On any given platform, there are likely to be other forms of sockets are by far the most popular. On any given platform, there are
IPC that are faster, but for cross-platform communication, sockets are about the likely to be other forms of IPC that are faster, but for
only game in town. cross-platform communication, sockets are about the only game in town.
They were invented in Berkeley as part of the BSD flavor of Unix. They spread They were invented in Berkeley as part of the BSD flavor of Unix. They spread
like wildfire with the Internet. With good reason --- the combination of sockets like wildfire with the Internet. With good reason --- the combination of sockets
@ -67,13 +67,14 @@ your browser did something like the following::
# - the normal http port # - the normal http port
s.connect(("www.mcmillan-inc.com", 80)) s.connect(("www.mcmillan-inc.com", 80))
When the ``connect`` completes, the socket ``s`` can now be used to send in a When the ``connect`` completes, the socket ``s`` can be used to send
request for the text of this page. The same socket will read the reply, and then in a request for the text of the page. The same socket will read the
be destroyed. That's right - destroyed. Client sockets are normally only used reply, and then be destroyed. That's right, destroyed. Client sockets
for one exchange (or a small set of sequential exchanges). are normally only used for one exchange (or a small set of sequential
exchanges).
What happens in the web server is a bit more complex. First, the web server What happens in the web server is a bit more complex. First, the web server
creates a "server socket". :: creates a "server socket"::
#create an INET, STREAMing socket #create an INET, STREAMing socket
serversocket = socket.socket( serversocket = socket.socket(
@ -97,7 +98,7 @@ Finally, the argument to ``listen`` tells the socket library that we want it to
queue up as many as 5 connect requests (the normal max) before refusing outside queue up as many as 5 connect requests (the normal max) before refusing outside
connections. If the rest of the code is written properly, that should be plenty. connections. If the rest of the code is written properly, that should be plenty.
OK, now we have a "server" socket, listening on port 80. Now we enter the Now that we have a "server" socket, listening on port 80, we can enter the
mainloop of the web server:: mainloop of the web server::
while 1: while 1:
@ -146,7 +147,7 @@ perhaps a signon. But that's a design decision - it's not a rule of sockets.
Now there are two sets of verbs to use for communication. You can use ``send`` Now there are two sets of verbs to use for communication. You can use ``send``
and ``recv``, or you can transform your client socket into a file-like beast and and ``recv``, or you can transform your client socket into a file-like beast and
use ``read`` and ``write``. The latter is the way Java presents their sockets. use ``read`` and ``write``. The latter is the way Java presents its sockets.
I'm not going to talk about it here, except to warn you that you need to use I'm not going to talk about it here, except to warn you that you need to use
``flush`` on sockets. These are buffered "files", and a common mistake is to ``flush`` on sockets. These are buffered "files", and a common mistake is to
``write`` something, and then ``read`` for a reply. Without a ``flush`` in ``write`` something, and then ``read`` for a reply. Without a ``flush`` in
@ -167,11 +168,11 @@ this connection. Ever. You may be able to send data successfully; I'll talk
about that some on the next page. about that some on the next page.
A protocol like HTTP uses a socket for only one transfer. The client sends a A protocol like HTTP uses a socket for only one transfer. The client sends a
request, the reads a reply. That's it. The socket is discarded. This means that request, then reads a reply. That's it. The socket is discarded. This means that
a client can detect the end of the reply by receiving 0 bytes. a client can detect the end of the reply by receiving 0 bytes.
But if you plan to reuse your socket for further transfers, you need to realize But if you plan to reuse your socket for further transfers, you need to realize
that *there is no "EOT" (End of Transfer) on a socket.* I repeat: if a socket that *there is no* :abbr:`EOT (End of Transfer)` *on a socket.* I repeat: if a socket
``send`` or ``recv`` returns after handling 0 bytes, the connection has been ``send`` or ``recv`` returns after handling 0 bytes, the connection has been
broken. If the connection has *not* been broken, you may wait on a ``recv`` broken. If the connection has *not* been broken, you may wait on a ``recv``
forever, because the socket will *not* tell you that there's nothing more to forever, because the socket will *not* tell you that there's nothing more to
@ -337,7 +338,7 @@ Use ``select``.
In C, coding ``select`` is fairly complex. In Python, it's a piece of cake, but In C, coding ``select`` is fairly complex. In Python, it's a piece of cake, but
it's close enough to the C version that if you understand ``select`` in Python, it's close enough to the C version that if you understand ``select`` in Python,
you'll have little trouble with it in C. :: you'll have little trouble with it in C::
ready_to_read, ready_to_write, in_error = \ ready_to_read, ready_to_write, in_error = \
select.select( select.select(
@ -354,9 +355,9 @@ call is blocking, but you can give it a timeout. This is generally a sensible
thing to do - give it a nice long timeout (say a minute) unless you have good thing to do - give it a nice long timeout (say a minute) unless you have good
reason to do otherwise. reason to do otherwise.
In return, you will get three lists. They have the sockets that are actually In return, you will get three lists. They contain the sockets that are actually
readable, writable and in error. Each of these lists is a subset (possibly readable, writable and in error. Each of these lists is a subset (possibly
empty) of the corresponding list you passed in. And if you put a socket in more empty) of the corresponding list you passed in. If you put a socket in more
than one input list, it will only be (at most) in one output list. than one input list, it will only be (at most) in one output list.
If a socket is in the output readable list, you can be If a socket is in the output readable list, you can be