f | |
| :mod:`asyncore` --- Asynchronous socket handler |
| =============================================== |
| |
| .. module:: asyncore |
n | :synopsis: A base class for developing asynchronous socket handling services. |
n | :synopsis: A base class for developing asynchronous socket handling |
| services. |
| .. moduleauthor:: Sam Rushing <rushing@nightmare.com> |
| .. sectionauthor:: Christopher Petrilli <petrilli@amber.org> |
| .. sectionauthor:: Steve Holden <sholden@holdenweb.com> |
n | .. heavily adapted from original documentation by Sam Rushing |
| |
| |
| This module provides the basic infrastructure for writing asynchronous socket |
| service clients and servers. |
| |
n | .. % Heavily adapted from original documentation by Sam Rushing. |
| |
| There are only two ways to have a program on a single processor do "more than |
| one thing at a time." Multi-threaded programming is the simplest and most |
n | popular way to do it, but there is another very different technique, that lets |
n | popular way to do it, but there is another very different technique, that lets |
| you have nearly all the advantages of multi-threading, without actually using |
| multiple threads. It's really only practical if your program is largely I/O |
n | bound. If your program is processor bound, then pre-emptive scheduled threads |
n | bound. If your program is processor bound, then pre-emptive scheduled threads |
| are probably what you really need. Network servers are rarely processor bound, |
| are probably what you really need. Network servers are rarely processor |
| however. |
| bound, however. |
| |
n | If your operating system supports the :cfunc:`select` system call in its I/O |
n | If your operating system supports the :cfunc:`select` system call in its I/O |
| library (and nearly all do), then you can use it to juggle multiple |
| library (and nearly all do), then you can use it to juggle multiple |
| communication channels at once; doing other work while your I/O is taking place |
| communication channels at once; doing other work while your I/O is taking |
| in the "background." Although this strategy can seem strange and complex, |
| place in the "background." Although this strategy can seem strange and |
| especially at first, it is in many ways easier to understand and control than |
| complex, especially at first, it is in many ways easier to understand and |
| multi-threaded programming. The :mod:`asyncore` module solves many of the |
| control than multi-threaded programming. The :mod:`asyncore` module solves |
| difficult problems for you, making the task of building sophisticated high- |
| many of the difficult problems for you, making the task of building |
| performance network servers and clients a snap. For "conversational" |
| sophisticated high-performance network servers and clients a snap. For |
| applications and protocols the companion :mod:`asynchat` module is invaluable. |
| "conversational" applications and protocols the companion :mod:`asynchat` |
| module is invaluable. |
| |
n | The basic idea behind both modules is to create one or more network *channels*, |
n | The basic idea behind both modules is to create one or more network |
| instances of class :class:`asyncore.dispatcher` and |
| *channels*, instances of class :class:`asyncore.dispatcher` and |
| :class:`asynchat.async_chat`. Creating the channels adds them to a global map, |
| :class:`asynchat.async_chat`. Creating the channels adds them to a global |
| used by the :func:`loop` function if you do not provide it with your own *map*. |
| map, used by the :func:`loop` function if you do not provide it with your own |
| *map*. |
| |
| Once the initial channel(s) is(are) created, calling the :func:`loop` function |
n | activates channel service, which continues until the last channel (including any |
n | activates channel service, which continues until the last channel (including |
| that have been added to the map during asynchronous service) is closed. |
| any that have been added to the map during asynchronous service) is closed. |
| |
| |
| .. function:: loop([timeout[, use_poll[, map[,count]]]]) |
| |
n | Enter a polling loop that terminates after count passes or all open channels |
n | Enter a polling loop that terminates after count passes or all open |
| have been closed. All arguments are optional. The *(*count) parameter defaults |
| channels have been closed. All arguments are optional. The *count* |
| to None, resulting in the loop terminating only when all channels have been |
| parameter defaults to None, resulting in the loop terminating only when all |
| closed. The *timeout* argument sets the timeout parameter for the appropriate |
| channels have been closed. The *timeout* argument sets the timeout |
| :func:`select` or :func:`poll` call, measured in seconds; the default is 30 |
| parameter for the appropriate :func:`select` or :func:`poll` call, measured |
| seconds. The *use_poll* parameter, if true, indicates that :func:`poll` should |
| in seconds; the default is 30 seconds. The *use_poll* parameter, if true, |
| be used in preference to :func:`select` (the default is ``False``). |
| indicates that :func:`poll` should be used in preference to :func:`select` |
| (the default is ``False``). |
| |
n | The *map* parameter is a dictionary whose items are the channels to watch. As |
n | The *map* parameter is a dictionary whose items are the channels to watch. |
| channels are closed they are deleted from their map. If *map* is omitted, a |
| As channels are closed they are deleted from their map. If *map* is |
| global map is used. Channels (instances of :class:`asyncore.dispatcher`, |
| omitted, a global map is used. Channels (instances of |
| :class:`asynchat.async_chat` and subclasses thereof) can freely be mixed in the |
| :class:`asyncore.dispatcher`, :class:`asynchat.async_chat` and subclasses |
| map. |
| thereof) can freely be mixed in the map. |
| |
| |
| .. class:: dispatcher() |
| |
| The :class:`dispatcher` class is a thin wrapper around a low-level socket |
n | object. To make it more useful, it has a few methods for event-handling which |
n | object. To make it more useful, it has a few methods for event-handling |
| are called from the asynchronous loop. Otherwise, it can be treated as a |
| which are called from the asynchronous loop. Otherwise, it can be treated |
| normal non-blocking socket object. |
| as a normal non-blocking socket object. |
| |
n | Two class attributes can be modified, to improve performance, or possibly even |
| to conserve memory. |
| |
| |
| .. data:: ac_in_buffer_size |
| |
| The asynchronous input buffer size (default ``4096``). |
| |
| |
| .. data:: ac_out_buffer_size |
| |
| The asynchronous output buffer size (default ``4096``). |
| |
| The firing of low-level events at certain times or in certain connection states |
| The firing of low-level events at certain times or in certain connection |
| tells the asynchronous loop that certain higher-level events have taken place. |
| states tells the asynchronous loop that certain higher-level events have |
| For example, if we have asked for a socket to connect to another host, we know |
| taken place. For example, if we have asked for a socket to connect to |
| that the connection has been made when the socket becomes writable for the first |
| another host, we know that the connection has been made when the socket |
| time (at this point you know that you may write to it with the expectation of |
| becomes writable for the first time (at this point you know that you may |
| success). The implied higher-level events are: |
| write to it with the expectation of success). The implied higher-level |
| events are: |
| |
| +----------------------+----------------------------------------+ |
| | Event | Description | |
| +======================+========================================+ |
| | ``handle_connect()`` | Implied by the first write event | |
| +----------------------+----------------------------------------+ |
| | ``handle_close()`` | Implied by a read event with no data | |
| | | available | |
| +----------------------+----------------------------------------+ |
| | ``handle_accept()`` | Implied by a read event on a listening | |
| | | socket | |
| +----------------------+----------------------------------------+ |
| |
| During asynchronous processing, each mapped channel's :meth:`readable` and |
| :meth:`writable` methods are used to determine whether the channel's socket |
n | should be added to the list of channels :cfunc:`select`\ ed or :cfunc:`poll`\ ed |
n | should be added to the list of channels :cfunc:`select`\ ed or |
| for read and write events. |
| :cfunc:`poll`\ ed for read and write events. |
| |
n | Thus, the set of channel events is larger than the basic socket events. The full |
n | Thus, the set of channel events is larger than the basic socket events. The |
| set of methods that can be overridden in your subclass follows: |
| full set of methods that can be overridden in your subclass follows: |
| |
| |
n | .. method:: dispatcher.handle_read() |
n | .. method:: handle_read() |
| |
n | Called when the asynchronous loop detects that a :meth:`read` call on the |
n | Called when the asynchronous loop detects that a :meth:`read` call on the |
| channel's socket will succeed. |
| channel's socket will succeed. |
| |
| |
n | .. method:: dispatcher.handle_write() |
n | .. method:: handle_write() |
| |
n | Called when the asynchronous loop detects that a writable socket can be written. |
n | Called when the asynchronous loop detects that a writable socket can be |
| Often this method will implement the necessary buffering for performance. For |
| written. Often this method will implement the necessary buffering for |
| example:: |
| performance. For example:: |
| |
n | def handle_write(self): |
n | def handle_write(self): |
| sent = self.send(self.buffer) |
| sent = self.send(self.buffer) |
| self.buffer = self.buffer[sent:] |
| self.buffer = self.buffer[sent:] |
| |
| |
n | .. method:: dispatcher.handle_expt() |
n | .. method:: handle_expt() |
| |
n | Called when there is out of band (OOB) data for a socket connection. This will |
n | Called when there is out of band (OOB) data for a socket connection. This |
| almost never happen, as OOB is tenuously supported and rarely used. |
| will almost never happen, as OOB is tenuously supported and rarely used. |
| |
| |
n | .. method:: dispatcher.handle_connect() |
n | .. method:: handle_connect() |
| |
n | Called when the active opener's socket actually makes a connection. Might send a |
n | Called when the active opener's socket actually makes a connection. Might |
| "welcome" banner, or initiate a protocol negotiation with the remote endpoint, |
| send a "welcome" banner, or initiate a protocol negotiation with the |
| for example. |
| remote endpoint, for example. |
| |
| |
n | .. method:: dispatcher.handle_close() |
n | .. method:: handle_close() |
| |
n | Called when the socket is closed. |
n | Called when the socket is closed. |
| |
| |
n | .. method:: dispatcher.handle_error() |
n | .. method:: handle_error() |
| |
n | Called when an exception is raised and not otherwise handled. The default |
n | Called when an exception is raised and not otherwise handled. The default |
| version prints a condensed traceback. |
| version prints a condensed traceback. |
| |
| |
n | .. method:: dispatcher.handle_accept() |
n | .. method:: handle_accept() |
| |
n | Called on listening channels (passive openers) when a connection can be |
n | Called on listening channels (passive openers) when a connection can be |
| established with a new remote endpoint that has issued a :meth:`connect` call |
| established with a new remote endpoint that has issued a :meth:`connect` |
| for the local endpoint. |
| call for the local endpoint. |
| |
| |
n | .. method:: dispatcher.readable() |
n | .. method:: readable() |
| |
n | Called each time around the asynchronous loop to determine whether a channel's |
n | Called each time around the asynchronous loop to determine whether a |
| socket should be added to the list on which read events can occur. The default |
| channel's socket should be added to the list on which read events can |
| method simply returns ``True``, indicating that by default, all channels will |
| occur. The default method simply returns ``True``, indicating that by |
| be interested in read events. |
| default, all channels will be interested in read events. |
| |
| |
n | .. method:: dispatcher.writable() |
n | .. method:: writable() |
| |
n | Called each time around the asynchronous loop to determine whether a channel's |
n | Called each time around the asynchronous loop to determine whether a |
| socket should be added to the list on which write events can occur. The default |
| channel's socket should be added to the list on which write events can |
| method simply returns ``True``, indicating that by default, all channels will |
| occur. The default method simply returns ``True``, indicating that by |
| be interested in write events. |
| default, all channels will be interested in write events. |
| |
n | |
| In addition, each channel delegates or extends many of the socket methods. Most |
| In addition, each channel delegates or extends many of the socket methods. |
| of these are nearly identical to their socket partners. |
| Most of these are nearly identical to their socket partners. |
| |
| |
n | .. method:: dispatcher.create_socket(family, type) |
n | .. method:: create_socket(family, type) |
| |
n | This is identical to the creation of a normal socket, and will use the same |
n | This is identical to the creation of a normal socket, and will use the |
| options for creation. Refer to the :mod:`socket` documentation for information |
| same options for creation. Refer to the :mod:`socket` documentation for |
| on creating sockets. |
| information on creating sockets. |
| |
| |
n | .. method:: dispatcher.connect(address) |
n | .. method:: connect(address) |
| |
n | As with the normal socket object, *address* is a tuple with the first element |
n | As with the normal socket object, *address* is a tuple with the first |
| the host to connect to, and the second the port number. |
| element the host to connect to, and the second the port number. |
| |
| |
n | .. method:: dispatcher.send(data) |
n | .. method:: send(data) |
| |
n | Send *data* to the remote end-point of the socket. |
n | Send *data* to the remote end-point of the socket. |
| |
| |
n | .. method:: dispatcher.recv(buffer_size) |
n | .. method:: recv(buffer_size) |
| |
n | Read at most *buffer_size* bytes from the socket's remote end-point. An empty |
n | Read at most *buffer_size* bytes from the socket's remote end-point. An |
| string implies that the channel has been closed from the other end. |
| empty string implies that the channel has been closed from the other end. |
| |
| |
n | .. method:: dispatcher.listen(backlog) |
n | .. method:: listen(backlog) |
| |
n | Listen for connections made to the socket. The *backlog* argument specifies the |
n | Listen for connections made to the socket. The *backlog* argument |
| maximum number of queued connections and should be at least 1; the maximum value |
| specifies the maximum number of queued connections and should be at least |
| is system-dependent (usually 5). |
| 1; the maximum value is system-dependent (usually 5). |
| |
| |
n | .. method:: dispatcher.bind(address) |
n | .. method:: bind(address) |
| |
n | Bind the socket to *address*. The socket must not already be bound. (The |
n | Bind the socket to *address*. The socket must not already be bound. (The |
| format of *address* depends on the address family --- see above.) |
| format of *address* depends on the address family --- see above.) To mark |
| the socket as re-usable (setting the :const:`SO_REUSEADDR` option), call |
| the :class:`dispatcher` object's :meth:`set_reuse_addr` method. |
| |
| |
n | .. method:: dispatcher.accept() |
n | .. method:: accept() |
| |
n | Accept a connection. The socket must be bound to an address and listening for |
n | Accept a connection. The socket must be bound to an address and listening |
| connections. The return value is a pair ``(conn, address)`` where *conn* is a |
| for connections. The return value is a pair ``(conn, address)`` where |
| *new* socket object usable to send and receive data on the connection, and |
| *conn* is a *new* socket object usable to send and receive data on the |
| *address* is the address bound to the socket on the other end of the connection. |
| connection, and *address* is the address bound to the socket on the other |
| end of the connection. |
| |
| |
n | .. method:: dispatcher.close() |
n | .. method:: close() |
| |
n | Close the socket. All future operations on the socket object will fail. The |
n | Close the socket. All future operations on the socket object will fail. |
| remote end-point will receive no more data (after queued data is flushed). |
| The remote end-point will receive no more data (after queued data is |
| Sockets are automatically closed when they are garbage-collected. |
| flushed). Sockets are automatically closed when they are |
| garbage-collected. |
| |
| .. class:: file_dispatcher() |
| |
| A file_dispatcher takes a file descriptor or file object along with an |
| optional map argument and wraps it for use with the :cfunc:`poll` or |
| :cfunc:`loop` functions. If provided a file object or anything with a |
| :cfunc:`fileno` method, that method will be called and passed to the |
| :class:`file_wrapper` constructor. Availability: UNIX. |
| |
| .. class:: file_wrapper() |
| |
| A file_wrapper takes an integer file descriptor and calls :func:`os.dup` to |
| duplicate the handle so that the original handle may be closed independently |
| of the file_wrapper. This class implements sufficient methods to emulate a |
| socket for use by the :class:`file_dispatcher` class. Availability: UNIX. |
| |
| |
| .. _asyncore-example: |
| |
| asyncore Example basic HTTP client |
| ---------------------------------- |
| |
| Here is a very basic HTTP client that uses the :class:`dispatcher` class to |