diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/library/ssl.rst | 23 |
1 files changed, 20 insertions, 3 deletions
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index 94a0c81..b473c45 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -1588,8 +1588,19 @@ the sockets in non-blocking mode and use an event loop). Notes on non-blocking sockets ----------------------------- -When working with non-blocking sockets, there are several things you need -to be aware of: +SSL sockets behave slightly different than regular sockets in +non-blocking mode. When working with non-blocking sockets, there are +thus several things you need to be aware of: + +- Most :class:`SSLSocket` methods will raise either + :exc:`SSLWantWriteError` or :exc:`SSLWantReadError` instead of + :exc:`BlockingIOError` if an I/O operation would + block. :exc:`SSLWantReadError` will be raised if a read operation on + the underlying socket is necessary, and :exc:`SSLWantWriteError` for + a write operation on the underlying socket. Note that attempts to + *write* to an SSL socket may require *reading* from the underlying + socket first, and attempts to *read* from the SSL socket may require + a prior *write* to the underlying socket. - Calling :func:`~select.select` tells you that the OS-level socket can be read from (or written to), but it does not imply that there is sufficient @@ -1598,8 +1609,14 @@ to be aware of: and :meth:`SSLSocket.send` failures, and retry after another call to :func:`~select.select`. +- Conversely, since the SSL layer has its own framing, a SSL socket may + still have data available for reading without :func:`~select.select` + being aware of it. Therefore, you should first call + :meth:`SSLSocket.recv` to drain any potentially available data, and then + only block on a :func:`~select.select` call if still necessary. + (of course, similar provisions apply when using other primitives such as - :func:`~select.poll`) + :func:`~select.poll`, or those in the :mod:`selectors` module) - The SSL handshake itself will be non-blocking: the :meth:`SSLSocket.do_handshake` method has to be retried until it returns |