# gevent

# `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

  Return the IP address (a string of the form ‘255.255.255.255’) for a host.

  See also

  Name Resolution (DNS)

class `socket`

  The cooperative socket object. See the version documentation for specifics.

- Python 3 interface
- Python 2 interface

## 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

  Block the current greenlet until fileno is ready to read.

  For the meaning of the other parameters and possible exceptions, see `wait()`.

  See also

  `cancel_wait()`

`wait_write`(fileno, timeout=None[, timeout_exc=None]) → None

  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

  `cancel_wait()`

`wait_readwrite`(fileno, timeout=None[, timeout_exc=None]) → None

  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

  `cancel_wait()`

`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 io by another greenlet, raise an exception in this blocking greenlet (`socket.error(EBADF, 'File descriptor was closed in another greenlet')` by default).

  Parameters:

  - io – 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 for `gevent.timeout.Timeout`.

  Raises: | ConcurrentObjectUseError – If the watcher is already started.

`cancel_wait`(watcher, error=<class 'gevent._socketcommon.cancel_wait_ex'>)

  See `gevent.hub.Hub.cancel_wait()`

Next page: `gevent._socket3` – Python 3 socket module