gevent.socket
– Cooperative low-level networking interface¶
This module provides socket operations and some related functions. The
API of the functions and classes matches the API of the corresponding
items in the standard socket
module exactly, but the
synchronous functions in this module only block the current greenlet
and let the others run.
Tip
gevent’s sockets, like most gevent objects, have thread
affinity. That is, they can only be used from the operating
system thread that created them (any greenlet in that thread
can use the socket). The results of attempting to use the
socket in another thread (for example, passing it to the
threadpool) are not defined (but one common outcome is a
LoopExit
exception).
For convenience, exceptions (like error
and
timeout
) as well as the constants from the
socket
module are imported into this module. In almost all
cases one can simply replace import socket
with from gevent
import socket
to start using cooperative sockets with no other
changes (or use gevent.monkey.patch_socket()
at startup if code
changes are not desired or possible).
Standard Library Interface¶
The exact API exposed by this module varies depending on what version of Python you are using. The documents below describe the API for Python 2 and Python 3, respectively.
Note
All the described APIs should be imported from
gevent.socket
, and not from their implementation modules.
Their organization is an implementation detail that may change at
any time.
- gethostbyname(host) address [source]¶
Return the IP address (a string of the form ‘255.255.255.255’) for a host.
See also
- class socket[source]¶
The cooperative socket object. See the version documentation for specifics.
Changed in version 20.12.0: Socket objects no longer have a
__dict__
or accept arbitrary instance variables. Previously they did, but standard library sockets never have.
- Python 3 interface
SocketType
socket
socket.accept()
socket.bind()
socket.connect()
socket.connect_ex()
socket.detach()
socket.dup()
socket.fileno()
socket.get_inheritable()
socket.getblocking()
socket.getpeername()
socket.getsockname()
socket.getsockopt()
socket.gettimeout()
socket.listen()
socket.makefile()
socket.recv()
socket.recv_into()
socket.recvfrom()
socket.recvfrom_into()
socket.send()
socket.sendall()
socket.sendfile()
socket.sendto()
socket.set_inheritable()
socket.setblocking()
socket.setsockopt()
socket.settimeout()
socket.shutdown()
socket.family
socket.proto
socket.type
create_connection()
fromfd()
getaddrinfo()
getfqdn()
gethostbyaddr()
gethostbyname()
gethostbyname_ex()
getnameinfo()
socketpair()
Gevent Extensions¶
Beyond the basic standard library interface, gevent.socket
provides some extensions. These are identical and shared by all
versions of Python.
Changed in version 1.3a2: The undocumented class BlockingResolver
has been documented
and moved to gevent.resolver.blocking.Resolver
.
Waiting¶
These functions are used to block the current greenlet until an open file (socket) is ready to perform I/O operations. These are low-level functions not commonly used by many programs.
Note
These use the underlying event loop io
watchers, which means
that they share the same implementation limits. For example,
on some platforms they can be used with more than just
sockets, while on others the applicability is more limited
(POSIX platforms like Linux and OS X can use pipes and fifos
but Windows is limited to sockets).
Note
On Windows with the libev event loop, gevent is limited to 1024 open sockets.
- wait_read(fileno, timeout=None[, timeout_exc=None]) None [source]¶
Block the current greenlet until fileno is ready to read.
For the meaning of the other parameters and possible exceptions, see
wait()
.See also
- wait_write(fileno, timeout=None[, timeout_exc=None]) None [source]¶
Block the current greenlet until fileno is ready to write.
For the meaning of the other parameters and possible exceptions, see
wait()
.Deprecated since version 1.1: The keyword argument event is ignored. Applications should not pass this parameter. In the future, doing so will become an error.
See also
- wait_readwrite(fileno, timeout=None[, timeout_exc=None]) None [source]¶
Block the current greenlet until fileno is ready to read or write.
For the meaning of the other parameters and possible exceptions, see
wait()
.Deprecated since version 1.1: The keyword argument event is ignored. Applications should not pass this parameter. In the future, doing so will become an error.
See also
- wait(watcher, timeout=None[, timeout_exc=None]) None ¶
Block the current greenlet until watcher is ready.
If timeout is non-negative, then timeout_exc is raised after timeout second has passed.
If
cancel_wait()
is called on watcher by another greenlet, raise an exception in this blocking greenlet (socket.error(EBADF, 'File descriptor was closed in another greenlet')
by default).- Parameters:
watcher – An event loop watcher, most commonly an IO watcher obtained from
gevent.core.loop.io()
timeout_exc – The exception to raise if the timeout expires. By default, a
socket.timeout
exception is raised. If you pass a value for this keyword, it is interpreted as forgevent.timeout.Timeout
.
- Raises:
ConcurrentObjectUseError – If the watcher is already started.