Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`asyncore` --- Asynchronous socket handler |
| 2 | =============================================== |
| 3 | |
| 4 | .. module:: asyncore |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 5 | :synopsis: A base class for developing asynchronous socket handling |
| 6 | services. |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 7 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | .. moduleauthor:: Sam Rushing <rushing@nightmare.com> |
| 9 | .. sectionauthor:: Christopher Petrilli <petrilli@amber.org> |
| 10 | .. sectionauthor:: Steve Holden <sholden@holdenweb.com> |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 11 | .. heavily adapted from original documentation by Sam Rushing |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 12 | |
Raymond Hettinger | ead4975 | 2011-01-24 16:28:06 +0000 | [diff] [blame] | 13 | **Source code:** :source:`Lib/asyncore.py` |
| 14 | |
Guido van Rossum | 16591f4 | 2016-10-25 08:49:13 -0700 | [diff] [blame] | 15 | .. deprecated:: 3.6 |
| 16 | Please use :mod:`asyncio` instead. |
| 17 | |
Raymond Hettinger | ead4975 | 2011-01-24 16:28:06 +0000 | [diff] [blame] | 18 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 19 | |
Guido van Rossum | 4da459c | 2013-11-22 12:27:45 -0800 | [diff] [blame] | 20 | .. note:: |
| 21 | |
| 22 | This module exists for backwards compatibility only. For new code we |
| 23 | recommend using :mod:`asyncio`. |
Guido van Rossum | aa40775 | 2013-11-22 11:57:35 -0800 | [diff] [blame] | 24 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 25 | This module provides the basic infrastructure for writing asynchronous socket |
| 26 | service clients and servers. |
| 27 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 28 | There are only two ways to have a program on a single processor do "more than |
| 29 | one thing at a time." Multi-threaded programming is the simplest and most |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 30 | popular way to do it, but there is another very different technique, that lets |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 31 | you have nearly all the advantages of multi-threading, without actually using |
| 32 | multiple threads. It's really only practical if your program is largely I/O |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 33 | bound. If your program is processor bound, then pre-emptive scheduled threads |
| 34 | are probably what you really need. Network servers are rarely processor |
| 35 | bound, however. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 36 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 37 | If your operating system supports the :c:func:`select` system call in its I/O |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 38 | library (and nearly all do), then you can use it to juggle multiple |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 39 | communication channels at once; doing other work while your I/O is taking |
| 40 | place in the "background." Although this strategy can seem strange and |
| 41 | complex, especially at first, it is in many ways easier to understand and |
| 42 | control than multi-threaded programming. The :mod:`asyncore` module solves |
| 43 | many of the difficult problems for you, making the task of building |
| 44 | sophisticated high-performance network servers and clients a snap. For |
| 45 | "conversational" applications and protocols the companion :mod:`asynchat` |
| 46 | module is invaluable. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 47 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 48 | The basic idea behind both modules is to create one or more network |
| 49 | *channels*, instances of class :class:`asyncore.dispatcher` and |
| 50 | :class:`asynchat.async_chat`. Creating the channels adds them to a global |
| 51 | map, used by the :func:`loop` function if you do not provide it with your own |
| 52 | *map*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 53 | |
| 54 | Once the initial channel(s) is(are) created, calling the :func:`loop` function |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 55 | activates channel service, which continues until the last channel (including |
| 56 | any that have been added to the map during asynchronous service) is closed. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 57 | |
| 58 | |
| 59 | .. function:: loop([timeout[, use_poll[, map[,count]]]]) |
| 60 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 61 | Enter a polling loop that terminates after count passes or all open |
| 62 | channels have been closed. All arguments are optional. The *count* |
Serhiy Storchaka | ecf41da | 2016-10-19 16:29:26 +0300 | [diff] [blame] | 63 | parameter defaults to ``None``, resulting in the loop terminating only when all |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 64 | channels have been closed. The *timeout* argument sets the timeout |
Serhiy Storchaka | bfdcd43 | 2013-10-13 23:09:14 +0300 | [diff] [blame] | 65 | parameter for the appropriate :func:`~select.select` or :func:`~select.poll` |
| 66 | call, measured in seconds; the default is 30 seconds. The *use_poll* |
| 67 | parameter, if true, indicates that :func:`~select.poll` should be used in |
| 68 | preference to :func:`~select.select` (the default is ``False``). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 69 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 70 | The *map* parameter is a dictionary whose items are the channels to watch. |
| 71 | As channels are closed they are deleted from their map. If *map* is |
| 72 | omitted, a global map is used. Channels (instances of |
| 73 | :class:`asyncore.dispatcher`, :class:`asynchat.async_chat` and subclasses |
| 74 | thereof) can freely be mixed in the map. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 75 | |
| 76 | |
| 77 | .. class:: dispatcher() |
| 78 | |
| 79 | The :class:`dispatcher` class is a thin wrapper around a low-level socket |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 80 | object. To make it more useful, it has a few methods for event-handling |
| 81 | which are called from the asynchronous loop. Otherwise, it can be treated |
| 82 | as a normal non-blocking socket object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 83 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 84 | The firing of low-level events at certain times or in certain connection |
| 85 | states tells the asynchronous loop that certain higher-level events have |
| 86 | taken place. For example, if we have asked for a socket to connect to |
| 87 | another host, we know that the connection has been made when the socket |
| 88 | becomes writable for the first time (at this point you know that you may |
| 89 | write to it with the expectation of success). The implied higher-level |
| 90 | events are: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 91 | |
| 92 | +----------------------+----------------------------------------+ |
| 93 | | Event | Description | |
| 94 | +======================+========================================+ |
R. David Murray | 78532ba | 2009-04-12 15:35:44 +0000 | [diff] [blame] | 95 | | ``handle_connect()`` | Implied by the first read or write | |
| 96 | | | event | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 97 | +----------------------+----------------------------------------+ |
| 98 | | ``handle_close()`` | Implied by a read event with no data | |
| 99 | | | available | |
| 100 | +----------------------+----------------------------------------+ |
Giampaolo Rodolà | 977c707 | 2010-10-04 21:08:36 +0000 | [diff] [blame] | 101 | | ``handle_accepted()``| Implied by a read event on a listening | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 102 | | | socket | |
| 103 | +----------------------+----------------------------------------+ |
| 104 | |
| 105 | During asynchronous processing, each mapped channel's :meth:`readable` and |
| 106 | :meth:`writable` methods are used to determine whether the channel's socket |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 107 | should be added to the list of channels :c:func:`select`\ ed or |
| 108 | :c:func:`poll`\ ed for read and write events. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 109 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 110 | Thus, the set of channel events is larger than the basic socket events. The |
| 111 | full set of methods that can be overridden in your subclass follows: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 112 | |
| 113 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 114 | .. method:: handle_read() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 115 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 116 | Called when the asynchronous loop detects that a :meth:`read` call on the |
| 117 | channel's socket will succeed. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 118 | |
| 119 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 120 | .. method:: handle_write() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 121 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 122 | Called when the asynchronous loop detects that a writable socket can be |
| 123 | written. Often this method will implement the necessary buffering for |
| 124 | performance. For example:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 125 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 126 | def handle_write(self): |
| 127 | sent = self.send(self.buffer) |
| 128 | self.buffer = self.buffer[sent:] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 129 | |
| 130 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 131 | .. method:: handle_expt() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 132 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 133 | Called when there is out of band (OOB) data for a socket connection. This |
| 134 | will almost never happen, as OOB is tenuously supported and rarely used. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 135 | |
| 136 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 137 | .. method:: handle_connect() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 138 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 139 | Called when the active opener's socket actually makes a connection. Might |
| 140 | send a "welcome" banner, or initiate a protocol negotiation with the |
| 141 | remote endpoint, for example. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 142 | |
| 143 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 144 | .. method:: handle_close() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 145 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 146 | Called when the socket is closed. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 147 | |
| 148 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 149 | .. method:: handle_error() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 150 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 151 | Called when an exception is raised and not otherwise handled. The default |
| 152 | version prints a condensed traceback. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 153 | |
| 154 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 155 | .. method:: handle_accept() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 156 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 157 | Called on listening channels (passive openers) when a connection can be |
| 158 | established with a new remote endpoint that has issued a :meth:`connect` |
Giampaolo Rodolà | 977c707 | 2010-10-04 21:08:36 +0000 | [diff] [blame] | 159 | call for the local endpoint. Deprecated in version 3.2; use |
| 160 | :meth:`handle_accepted` instead. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 161 | |
Georg Brandl | eeed955 | 2010-10-05 07:16:01 +0000 | [diff] [blame] | 162 | .. deprecated:: 3.2 |
| 163 | |
Giampaolo Rodolà | 977c707 | 2010-10-04 21:08:36 +0000 | [diff] [blame] | 164 | |
| 165 | .. method:: handle_accepted(sock, addr) |
| 166 | |
| 167 | Called on listening channels (passive openers) when a connection has been |
| 168 | established with a new remote endpoint that has issued a :meth:`connect` |
Senthil Kumaran | 656df5e | 2011-06-19 18:22:33 -0700 | [diff] [blame] | 169 | call for the local endpoint. *sock* is a *new* socket object usable to |
| 170 | send and receive data on the connection, and *addr* is the address |
Giampaolo Rodolà | 977c707 | 2010-10-04 21:08:36 +0000 | [diff] [blame] | 171 | bound to the socket on the other end of the connection. |
| 172 | |
Georg Brandl | eeed955 | 2010-10-05 07:16:01 +0000 | [diff] [blame] | 173 | .. versionadded:: 3.2 |
| 174 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 175 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 176 | .. method:: readable() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 177 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 178 | Called each time around the asynchronous loop to determine whether a |
| 179 | channel's socket should be added to the list on which read events can |
| 180 | occur. The default method simply returns ``True``, indicating that by |
| 181 | default, all channels will be interested in read events. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 182 | |
| 183 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 184 | .. method:: writable() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 185 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 186 | Called each time around the asynchronous loop to determine whether a |
| 187 | channel's socket should be added to the list on which write events can |
| 188 | occur. The default method simply returns ``True``, indicating that by |
| 189 | default, all channels will be interested in write events. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 190 | |
| 191 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 192 | In addition, each channel delegates or extends many of the socket methods. |
| 193 | Most of these are nearly identical to their socket partners. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 194 | |
| 195 | |
Giampaolo Rodolà | 103a6d6 | 2011-02-25 22:21:22 +0000 | [diff] [blame] | 196 | .. method:: create_socket(family=socket.AF_INET, type=socket.SOCK_STREAM) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 197 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 198 | This is identical to the creation of a normal socket, and will use the |
| 199 | same options for creation. Refer to the :mod:`socket` documentation for |
| 200 | information on creating sockets. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 201 | |
Georg Brandl | f5a1d76 | 2012-03-09 12:22:12 +0100 | [diff] [blame] | 202 | .. versionchanged:: 3.3 |
| 203 | *family* and *type* arguments can be omitted. |
Giampaolo Rodolà | 103a6d6 | 2011-02-25 22:21:22 +0000 | [diff] [blame] | 204 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 205 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 206 | .. method:: connect(address) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 207 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 208 | As with the normal socket object, *address* is a tuple with the first |
| 209 | element the host to connect to, and the second the port number. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 210 | |
| 211 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 212 | .. method:: send(data) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 213 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 214 | Send *data* to the remote end-point of the socket. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 215 | |
| 216 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 217 | .. method:: recv(buffer_size) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 218 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 219 | Read at most *buffer_size* bytes from the socket's remote end-point. An |
Serhiy Storchaka | 5e028ae | 2014-02-06 21:10:41 +0200 | [diff] [blame] | 220 | empty bytes object implies that the channel has been closed from the |
| 221 | other end. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 222 | |
Victor Stinner | 45cff66 | 2014-07-24 18:49:36 +0200 | [diff] [blame] | 223 | Note that :meth:`recv` may raise :exc:`BlockingIOError` , even though |
| 224 | :func:`select.select` or :func:`select.poll` has reported the socket |
| 225 | ready for reading. |
| 226 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 227 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 228 | .. method:: listen(backlog) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 229 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 230 | Listen for connections made to the socket. The *backlog* argument |
| 231 | specifies the maximum number of queued connections and should be at least |
| 232 | 1; the maximum value is system-dependent (usually 5). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 233 | |
| 234 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 235 | .. method:: bind(address) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 236 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 237 | Bind the socket to *address*. The socket must not already be bound. (The |
Benjamin Peterson | 21896a3 | 2010-03-21 22:03:03 +0000 | [diff] [blame] | 238 | format of *address* depends on the address family --- refer to the |
| 239 | :mod:`socket` documentation for more information.) To mark |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 240 | the socket as re-usable (setting the :const:`SO_REUSEADDR` option), call |
| 241 | the :class:`dispatcher` object's :meth:`set_reuse_addr` method. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 242 | |
| 243 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 244 | .. method:: accept() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 245 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 246 | Accept a connection. The socket must be bound to an address and listening |
Giampaolo Rodolà | 977c707 | 2010-10-04 21:08:36 +0000 | [diff] [blame] | 247 | for connections. The return value can be either ``None`` or a pair |
| 248 | ``(conn, address)`` where *conn* is a *new* socket object usable to send |
| 249 | and receive data on the connection, and *address* is the address bound to |
| 250 | the socket on the other end of the connection. |
| 251 | When ``None`` is returned it means the connection didn't take place, in |
| 252 | which case the server should just ignore this event and keep listening |
| 253 | for further incoming connections. |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 254 | |
| 255 | |
| 256 | .. method:: close() |
| 257 | |
| 258 | Close the socket. All future operations on the socket object will fail. |
| 259 | The remote end-point will receive no more data (after queued data is |
| 260 | flushed). Sockets are automatically closed when they are |
| 261 | garbage-collected. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 262 | |
Giampaolo Rodolà | 977c707 | 2010-10-04 21:08:36 +0000 | [diff] [blame] | 263 | |
| 264 | .. class:: dispatcher_with_send() |
| 265 | |
| 266 | A :class:`dispatcher` subclass which adds simple buffered output capability, |
| 267 | useful for simple clients. For more sophisticated usage use |
| 268 | :class:`asynchat.async_chat`. |
| 269 | |
Josiah Carlson | d74900e | 2008-07-07 04:15:08 +0000 | [diff] [blame] | 270 | .. class:: file_dispatcher() |
| 271 | |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 272 | A file_dispatcher takes a file descriptor or :term:`file object` along |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 273 | with an optional map argument and wraps it for use with the :c:func:`poll` |
| 274 | or :c:func:`loop` functions. If provided a file object or anything with a |
| 275 | :c:func:`fileno` method, that method will be called and passed to the |
Josiah Carlson | d74900e | 2008-07-07 04:15:08 +0000 | [diff] [blame] | 276 | :class:`file_wrapper` constructor. Availability: UNIX. |
| 277 | |
| 278 | .. class:: file_wrapper() |
| 279 | |
| 280 | A file_wrapper takes an integer file descriptor and calls :func:`os.dup` to |
| 281 | duplicate the handle so that the original handle may be closed independently |
| 282 | of the file_wrapper. This class implements sufficient methods to emulate a |
| 283 | socket for use by the :class:`file_dispatcher` class. Availability: UNIX. |
| 284 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 285 | |
Giampaolo Rodolà | 977c707 | 2010-10-04 21:08:36 +0000 | [diff] [blame] | 286 | .. _asyncore-example-1: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 287 | |
| 288 | asyncore Example basic HTTP client |
| 289 | ---------------------------------- |
| 290 | |
| 291 | Here is a very basic HTTP client that uses the :class:`dispatcher` class to |
| 292 | implement its socket handling:: |
| 293 | |
Giampaolo Rodola' | 0fb41b5 | 2012-05-15 15:46:00 +0200 | [diff] [blame] | 294 | import asyncore |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 295 | |
Giampaolo Rodolà | 977c707 | 2010-10-04 21:08:36 +0000 | [diff] [blame] | 296 | class HTTPClient(asyncore.dispatcher): |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 297 | |
| 298 | def __init__(self, host, path): |
| 299 | asyncore.dispatcher.__init__(self) |
Giampaolo Rodolà | 103a6d6 | 2011-02-25 22:21:22 +0000 | [diff] [blame] | 300 | self.create_socket() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 301 | self.connect( (host, 80) ) |
Georg Brandl | 45ec333 | 2011-03-06 11:05:03 +0100 | [diff] [blame] | 302 | self.buffer = bytes('GET %s HTTP/1.0\r\nHost: %s\r\n\r\n' % |
| 303 | (path, host), 'ascii') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 304 | |
| 305 | def handle_connect(self): |
| 306 | pass |
| 307 | |
| 308 | def handle_close(self): |
| 309 | self.close() |
| 310 | |
| 311 | def handle_read(self): |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 312 | print(self.recv(8192)) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 313 | |
| 314 | def writable(self): |
| 315 | return (len(self.buffer) > 0) |
| 316 | |
| 317 | def handle_write(self): |
| 318 | sent = self.send(self.buffer) |
| 319 | self.buffer = self.buffer[sent:] |
| 320 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 321 | |
Serhiy Storchaka | dba9039 | 2016-05-10 12:01:23 +0300 | [diff] [blame] | 322 | client = HTTPClient('www.python.org', '/') |
| 323 | asyncore.loop() |
Giampaolo Rodolà | 977c707 | 2010-10-04 21:08:36 +0000 | [diff] [blame] | 324 | |
| 325 | .. _asyncore-example-2: |
| 326 | |
| 327 | asyncore Example basic echo server |
| 328 | ---------------------------------- |
| 329 | |
Giampaolo Rodolà | 61a0bf5 | 2011-02-25 14:50:57 +0000 | [diff] [blame] | 330 | Here is a basic echo server that uses the :class:`dispatcher` class to accept |
Giampaolo Rodolà | 977c707 | 2010-10-04 21:08:36 +0000 | [diff] [blame] | 331 | connections and dispatches the incoming connections to a handler:: |
| 332 | |
| 333 | import asyncore |
Giampaolo Rodolà | 977c707 | 2010-10-04 21:08:36 +0000 | [diff] [blame] | 334 | |
| 335 | class EchoHandler(asyncore.dispatcher_with_send): |
| 336 | |
| 337 | def handle_read(self): |
| 338 | data = self.recv(8192) |
Giampaolo Rodolà | 61a0bf5 | 2011-02-25 14:50:57 +0000 | [diff] [blame] | 339 | if data: |
| 340 | self.send(data) |
Giampaolo Rodolà | 977c707 | 2010-10-04 21:08:36 +0000 | [diff] [blame] | 341 | |
| 342 | class EchoServer(asyncore.dispatcher): |
| 343 | |
| 344 | def __init__(self, host, port): |
| 345 | asyncore.dispatcher.__init__(self) |
Giampaolo Rodolà | 103a6d6 | 2011-02-25 22:21:22 +0000 | [diff] [blame] | 346 | self.create_socket() |
Giampaolo Rodolà | 977c707 | 2010-10-04 21:08:36 +0000 | [diff] [blame] | 347 | self.set_reuse_addr() |
| 348 | self.bind((host, port)) |
| 349 | self.listen(5) |
| 350 | |
| 351 | def handle_accepted(self, sock, addr): |
| 352 | print('Incoming connection from %s' % repr(addr)) |
| 353 | handler = EchoHandler(sock) |
| 354 | |
| 355 | server = EchoServer('localhost', 8080) |
| 356 | asyncore.loop() |