5 -----------------------------
6 Asynchronous socket handler
7 -----------------------------
9 Synopsis: A base class for developing asynchronous socket
12 Module-Author: Sam Rushing <rushing@nightmare.com>
13 Author: Christopher Petrilli <petrilli@amber.org>
14 Author: Steve Holden <sholden@holdenweb.com>
16 .. Type: ... builtin, standard, various others: any specific usages required?
18 .. Heavily adapted from original documentation by Sam Rushing.
20 .. ............................................
21 .. This is the (first) RFC822-reader strawman
22 .. ............................................
23 .. Presumes a custom reader appropriate to docpy
24 .. RFC822 continuation IS allowed (see Synopsis)
25 .. Needtocheck: RFC822-readers and multiple entities? (Author lines)
26 .. Dunno about implication of \section in the original
27 .. Dunno about comments (#?); "Credit: Sam Rushing?"
28 .. Note in passing: names of new roles and directives made similar to
29 .. the existing docpy macros on purpose (for existing corpus & community)
31 .. Markups needed, used, and existing in rst:
34 .. Markups needed, used, and modified by this strawman:
37 .. Roles needed below by this strawman:
46 .. Directives needed below by this strawman:
48 .. need to parse for optional argumnents shown as [...]
52 .. TBS - formals, e.g., funcdesc - several alternatives proposed
53 .. below (see funcdesc) in this draft
54 .. the one shown first seems on track for consensus 04.3.20
55 .. (the directive will parse brackets, etc. - easier to use!)
57 This module provides the basic infrastructure for writing asynchronous
58 socket service clients and servers.
60 There are only two ways to have a program on a single processor do
61 "more than one thing at a time." Multi-threaded programming is the
62 simplest and most popular way to do it, but there is another very
63 different technique, that lets you have nearly all the advantages of
64 multi-threading, without actually using multiple threads. It's really
65 only practical if your program is largely I/O bound. If your program
66 is processor bound, then pre-emptive scheduled threads are probably what
67 you really need. Network servers are rarely processor bound, however.
69 If your operating system supports the :cfunction:`select()` system call
70 in its I/O library (and nearly all do), then you can use it to juggle
71 multiple communication channels at once; doing other work while your
72 I/O is taking place in the "background." Although this strategy can
73 seem strange and complex, especially at first, it is in many ways
74 easier to understand and control than multi-threaded programming.
75 The :module:`asyncore` module solves many of the difficult problems for
76 you, making the task of building sophisticated high-performance
77 network servers and clients a snap. For "conversational" applications
78 and protocols the companion :refmodule:`asynchat` module is invaluable.
80 The basic idea behind both modules is to create one or more network
81 *channels*, instances of class :class:`asyncore.dispatcher` and
82 :class:`asynchat.async_chat`. Creating the channels adds them to a global
83 map, used by the :function:`loop()` function if you do not provide it
84 with your own :var:`map`.
86 Once the initial channel(s) is(are) created, calling the :function:`loop()`
87 function activates channel service, which continues until the last
88 channel (including any that have been added to the map during asynchronous
91 .. funcdesc:: loop([timeout [, use_poll [, map]]])
93 Enter a polling loop that only terminates after all open channels
94 have been closed. All arguments are optional. The :var:`timeout`
95 argument sets the timeout parameter for the appropriate
96 :function:`select()` or :function:`poll()` call, measured in seconds;
97 the default is 30 seconds. The :var:`use_poll` parameter, if true,
98 indicates that :function:`poll()` should be used in preference to
99 :function:`select()` (the default is ``False``). The :var:`map` parameter
100 is a dictionary whose items are the channels to watch. As channels
101 are closed they are deleted from their map. If :var:`map` is
102 omitted, a global map is used (this map is updated by the default
103 class :method:`__init__()`
104 -- make sure you extend, rather than override, :method:`__init__()`
105 if you want to retain this behavior).
107 Channels (instances of :class:`asyncore.dispatcher`, :class:`asynchat.async_chat`
108 and subclasses thereof) can freely be mixed in the map.
110 .. classdesc:: dispatcher()
112 The :class:`dispatcher` class is a thin wrapper around a low-level socket object.
113 To make it more useful, it has a few methods for event-handling which are called
114 from the asynchronous loop.
115 Otherwise, it can be treated as a normal non-blocking socket object.
117 Two class attributes can be modified, to improve performance,
118 or possibly even to conserve memory.
120 .. datadesc:: ac_in_buffer_size
121 The asynchronous input buffer size (default ``4096``).
123 .. datadesc:: ac_out_buffer_size
124 The asynchronous output buffer size (default ``4096``).
126 The firing of low-level events at certain times or in certain connection
127 states tells the asynchronous loop that certain higher-level events have
128 taken place. For example, if we have asked for a socket to connect to
129 another host, we know that the connection has been made when the socket
130 becomes writable for the first time (at this point you know that you may
131 write to it with the expectation of success). The implied higher-level
134 =================== ===============================================
135 ``Event`` Description
136 ------------------- -----------------------------------------------
137 ``handle_connect()`` Implied by the first write event
138 ``handle_close()`` Implied by a read event with no data available
139 ``handle_accept()`` Implied by a read event on a listening socket
140 =================== ===============================================
143 During asynchronous processing, each mapped channel's :method:`readable()`
144 and :method:`writable()` methods are used to determine whether the channel's
145 socket should be added to the list of channels :cfunction:`select()`\ ed or
146 :cfunction:`poll()`\ ed for read and write events.
148 Thus, the set of channel events is larger than the basic socket events.
149 The full set of methods that can be overridden in your subclass follows:
151 .. methoddesc:: handle_read()
152 Called when the asynchronous loop detects that a :method:`read()`
153 call on the channel's socket will succeed.
155 .. methoddesc:: handle_write()
156 Called when the asynchronous loop detects that a writable socket
158 Often this method will implement the necessary buffering for
159 performance. For example::
162 def handle_write(self):
163 sent = self.send(self.buffer)
164 self.buffer = self.buffer[sent:]
166 .. methoddesc:: handle_expt()
167 Called when there is out of band (OOB) data for a socket
168 connection. This will almost never happen, as OOB is
169 tenuously supported and rarely used.
171 .. methoddesc:: handle_connect()
172 Called when the active opener's socket actually makes a connection.
173 Might send a ``welcome'' banner, or initiate a protocol
174 negotiation with the remote endpoint, for example.
176 .. methoddesc:: handle_close()
177 Called when the socket is closed.
179 .. methoddesc:: handle_error()
180 Called when an exception is raised and not otherwise handled. The default
181 version prints a condensed traceback.
183 .. methoddesc:: handle_accept()
184 Called on listening channels (passive openers) when a
185 connection can be established with a new remote endpoint that
186 has issued a :method:`connect() call for the local endpoint.
188 .. methoddesc:: readable()
189 Called each time around the asynchronous loop to determine whether a
190 channel's socket should be added to the list on which read events can
191 occur. The default method simply returns ``True``,
192 indicating that by default, all channels will be interested in
195 .. methoddesc:: writable()
196 Called each time around the asynchronous loop to determine whether a
197 channel's socket should be added to the list on which write events can
198 occur. The default method simply returns ``True``,
199 indicating that by default, all channels will be interested in
202 In addition, each channel delegates or extends many of the socket methods.
203 Most of these are nearly identical to their socket partners.
205 .. methoddesc:: create_socket(family, type)
206 This is identical to the creation of a normal socket, and
207 will use the same options for creation. Refer to the
208 :refmodule:`socket` documentation for information on creating
211 .. methoddesc:: connect(address)
212 As with the normal socket object, :var:`address` is a
213 tuple with the first element the host to connect to, and the
214 second the port number.
216 .. methoddesc:: send(data)
217 Send :var:`data` to the remote end-point of the socket.
219 .. methoddesc:: recv(buffer_size)
220 Read at most :var:`buffer_size` bytes from the socket's remote end-point.
221 An empty string implies that the channel has been closed from the other
224 .. methoddesc:: listen(backlog)
225 Listen for connections made to the socket. The :var:`backlog`
226 argument specifies the maximum number of queued connections
227 and should be at least 1; the maximum value is
228 system-dependent (usually 5).
230 .. methoddesc:: bind(address)
231 Bind the socket to :var:`address`. The socket must not already
232 be bound. (The format of :var:`address` depends on the address
233 family --- see above.)
235 .. methoddesc:: accept()
236 Accept a connection. The socket must be bound to an address
237 and listening for connections. The return value is a pair
238 ``(conn , address)`` where :var:`conn` is a
239 *new* socket object usable to send and receive data on
240 the connection, and :var:`address` is the address bound to the
241 socket on the other end of the connection.
243 .. methoddesc:: close()
244 Close the socket. All future operations on the socket object
245 will fail. The remote end-point will receive no more data (after
246 queued data is flushed). Sockets are automatically closed
247 when they are garbage-collected.
250 asyncore Example basic HTTP client :label:`asyncore-example`
251 ------------------------------------------------------------
252 As a basic example, below is a very basic HTTP client that uses the
253 :class:`dispatcher` class to implement its socket handling::
255 class http_client(asyncore.dispatcher):
256 def __init__(self, host,path):
257 asyncore.dispatcher.__init__(self)
259 self.create_socket(socket.AF_INET, socket.SOCK_STREAM)
260 self.connect( (host, 80) )
261 self.buffer = 'GET %s HTTP/1.0\r\n\r\n' % self.path
263 def handle_connect(self):
266 def handle_read(self):
267 data = self.recv(8192)
271 return (len(self.buffer) > 0)
273 def handle_write(self):
274 sent = self.send(self.buffer)
275 self.buffer = self.buffer[sent:]