/Doc/library/asyncore.rst

  1
  2:mod:`asyncore` --- Asynchronous socket handler
  3===============================================
  4
  5.. module:: asyncore
  6   :synopsis: A base class for developing asynchronous socket handling
  7              services.
  8.. moduleauthor:: Sam Rushing <rushing@nightmare.com>
  9.. sectionauthor:: Christopher Petrilli <petrilli@amber.org>
 10.. sectionauthor:: Steve Holden <sholden@holdenweb.com>
 11.. heavily adapted from original documentation by Sam Rushing
 12
 13
 14This module provides the basic infrastructure for writing asynchronous  socket
 15service clients and servers.
 16
 17There are only two ways to have a program on a single processor do  "more than
 18one thing at a time." Multi-threaded programming is the  simplest and most
 19popular way to do it, but there is another very different technique, that lets
 20you have nearly all the advantages of  multi-threading, without actually using
 21multiple threads.  It's really  only practical if your program is largely I/O
 22bound.  If your program is processor bound, then pre-emptive scheduled threads
 23are probably what you really need.  Network servers are rarely processor
 24bound, however.
 25
 26If your operating system supports the :cfunc:`select` system call in its I/O
 27library (and nearly all do), then you can use it to juggle multiple
 28communication channels at once; doing other work while your I/O is taking
 29place in the "background."  Although this strategy can seem strange and
 30complex, especially at first, it is in many ways easier to understand and
 31control than multi-threaded programming.  The :mod:`asyncore` module solves
 32many of the difficult problems for you, making the task of building
 33sophisticated high-performance network servers and clients a snap.  For
 34"conversational" applications and protocols the companion :mod:`asynchat`
 35module is invaluable.
 36
 37The basic idea behind both modules is to create one or more network
 38*channels*, instances of class :class:`asyncore.dispatcher` and
 39:class:`asynchat.async_chat`.  Creating the channels adds them to a global
 40map, used by the :func:`loop` function if you do not provide it with your own
 41*map*.
 42
 43Once the initial channel(s) is(are) created, calling the :func:`loop` function
 44activates channel service, which continues until the last channel (including
 45any that have been added to the map during asynchronous service) is closed.
 46
 47
 48.. function:: loop([timeout[, use_poll[, map[,count]]]])
 49
 50   Enter a polling loop that terminates after count passes or all open
 51   channels have been closed.  All arguments are optional.  The *count*
 52   parameter defaults to None, resulting in the loop terminating only when all
 53   channels have been closed.  The *timeout* argument sets the timeout
 54   parameter for the appropriate :func:`select` or :func:`poll` call, measured
 55   in seconds; the default is 30 seconds.  The *use_poll* parameter, if true,
 56   indicates that :func:`poll` should be used in preference to :func:`select`
 57   (the default is ``False``).
 58
 59   The *map* parameter is a dictionary whose items are the channels to watch.
 60   As channels are closed they are deleted from their map.  If *map* is
 61   omitted, a global map is used. Channels (instances of
 62   :class:`asyncore.dispatcher`, :class:`asynchat.async_chat` and subclasses
 63   thereof) can freely be mixed in the map.
 64
 65
 66.. class:: dispatcher()
 67
 68   The :class:`dispatcher` class is a thin wrapper around a low-level socket
 69   object. To make it more useful, it has a few methods for event-handling
 70   which are called from the asynchronous loop.   Otherwise, it can be treated
 71   as a normal non-blocking socket object.
 72
 73   The firing of low-level events at certain times or in certain connection
 74   states tells the asynchronous loop that certain higher-level events have
 75   taken place.  For example, if we have asked for a socket to connect to
 76   another host, we know that the connection has been made when the socket
 77   becomes writable for the first time (at this point you know that you may
 78   write to it with the expectation of success).  The implied higher-level
 79   events are:
 80
 81   +----------------------+----------------------------------------+
 82   | Event                | Description                            |
 83   +======================+========================================+
 84   | ``handle_connect()`` | Implied by the first read or write     |
 85   |                      | event                                  |
 86   +----------------------+----------------------------------------+
 87   | ``handle_close()``   | Implied by a read event with no data   |
 88   |                      | available                              |
 89   +----------------------+----------------------------------------+
 90   | ``handle_accept()``  | Implied by a read event on a listening |
 91   |                      | socket                                 |
 92   +----------------------+----------------------------------------+
 93
 94   During asynchronous processing, each mapped channel's :meth:`readable` and
 95   :meth:`writable` methods are used to determine whether the channel's socket
 96   should be added to the list of channels :cfunc:`select`\ ed or
 97   :cfunc:`poll`\ ed for read and write events.
 98
 99   Thus, the set of channel events is larger than the basic socket events.  The
100   full set of methods that can be overridden in your subclass follows:
101
102
103   .. method:: handle_read()
104
105      Called when the asynchronous loop detects that a :meth:`read` call on the
106      channel's socket will succeed.
107
108
109   .. method:: handle_write()
110
111      Called when the asynchronous loop detects that a writable socket can be
112      written.  Often this method will implement the necessary buffering for
113      performance.  For example::
114
115         def handle_write(self):
116             sent = self.send(self.buffer)
117             self.buffer = self.buffer[sent:]
118
119
120   .. method:: handle_expt()
121
122      Called when there is out of band (OOB) data for a socket connection.  This
123      will almost never happen, as OOB is tenuously supported and rarely used.
124
125
126   .. method:: handle_connect()
127
128      Called when the active opener's socket actually makes a connection.  Might
129      send a "welcome" banner, or initiate a protocol negotiation with the
130      remote endpoint, for example.
131
132
133   .. method:: handle_close()
134
135      Called when the socket is closed.
136
137
138   .. method:: handle_error()
139
140      Called when an exception is raised and not otherwise handled.  The default
141      version prints a condensed traceback.
142
143
144   .. method:: handle_accept()
145
146      Called on listening channels (passive openers) when a connection can be
147      established with a new remote endpoint that has issued a :meth:`connect`
148      call for the local endpoint.
149
150
151   .. method:: readable()
152
153      Called each time around the asynchronous loop to determine whether a
154      channel's socket should be added to the list on which read events can
155      occur.  The default method simply returns ``True``, indicating that by
156      default, all channels will be interested in read events.
157
158
159   .. method:: writable()
160
161      Called each time around the asynchronous loop to determine whether a
162      channel's socket should be added to the list on which write events can
163      occur.  The default method simply returns ``True``, indicating that by
164      default, all channels will be interested in write events.
165
166
167   In addition, each channel delegates or extends many of the socket methods.
168   Most of these are nearly identical to their socket partners.
169
170
171   .. method:: create_socket(family, type)
172
173      This is identical to the creation of a normal socket, and will use the
174      same options for creation.  Refer to the :mod:`socket` documentation for
175      information on creating sockets.
176
177
178   .. method:: connect(address)
179
180      As with the normal socket object, *address* is a tuple with the first
181      element the host to connect to, and the second the port number.
182
183
184   .. method:: send(data)
185
186      Send *data* to the remote end-point of the socket.
187
188
189   .. method:: recv(buffer_size)
190
191      Read at most *buffer_size* bytes from the socket's remote end-point.  An
192      empty string implies that the channel has been closed from the other end.
193
194
195   .. method:: listen(backlog)
196
197      Listen for connections made to the socket.  The *backlog* argument
198      specifies the maximum number of queued connections and should be at least
199      1; the maximum value is system-dependent (usually 5).
200
201
202   .. method:: bind(address)
203
204      Bind the socket to *address*.  The socket must not already be bound.  (The
205      format of *address* depends on the address family --- see above.)  To mark
206      the socket as re-usable (setting the :const:`SO_REUSEADDR` option), call
207      the :class:`dispatcher` object's :meth:`set_reuse_addr` method.
208
209
210   .. method:: accept()
211
212      Accept a connection.  The socket must be bound to an address and listening
213      for connections.  The return value is a pair ``(conn, address)`` where
214      *conn* is a *new* socket object usable to send and receive data on the
215      connection, and *address* is the address bound to the socket on the other
216      end of the connection.
217
218
219   .. method:: close()
220
221      Close the socket.  All future operations on the socket object will fail.
222      The remote end-point will receive no more data (after queued data is
223      flushed).  Sockets are automatically closed when they are
224      garbage-collected.
225
226.. class:: file_dispatcher()
227
228   A file_dispatcher takes a file descriptor or file object along with an
229   optional map argument and wraps it for use with the :cfunc:`poll` or
230   :cfunc:`loop` functions.  If provided a file object or anything with a
231   :cfunc:`fileno` method, that method will be called and passed to the
232   :class:`file_wrapper` constructor.  Availability: UNIX.
233
234.. class:: file_wrapper()
235
236   A file_wrapper takes an integer file descriptor and calls :func:`os.dup` to
237   duplicate the handle so that the original handle may be closed independently
238   of the file_wrapper.  This class implements sufficient methods to emulate a
239   socket for use by the :class:`file_dispatcher` class.  Availability: UNIX.
240
241
242.. _asyncore-example:
243
244asyncore Example basic HTTP client
245----------------------------------
246
247Here is a very basic HTTP client that uses the :class:`dispatcher` class to
248implement its socket handling::
249
250   import asyncore, socket
251
252   class http_client(asyncore.dispatcher):
253
254       def __init__(self, host, path):
255           asyncore.dispatcher.__init__(self)
256           self.create_socket(socket.AF_INET, socket.SOCK_STREAM)
257           self.connect( (host, 80) )
258           self.buffer = 'GET %s HTTP/1.0\r\n\r\n' % path
259
260       def handle_connect(self):
261           pass
262
263       def handle_close(self):
264           self.close()
265
266       def handle_read(self):
267           print self.recv(8192)
268
269       def writable(self):
270           return (len(self.buffer) > 0)
271
272       def handle_write(self):
273           sent = self.send(self.buffer)
274           self.buffer = self.buffer[sent:]
275
276   c = http_client('www.python.org', '/')
277
278   asyncore.loop()