diff options
Diffstat (limited to 'Doc/library/asynchat.rst')
| -rw-r--r-- | Doc/library/asynchat.rst | 200 |
1 files changed, 109 insertions, 91 deletions
diff --git a/Doc/library/asynchat.rst b/Doc/library/asynchat.rst index b651c40..8e9437d 100644 --- a/Doc/library/asynchat.rst +++ b/Doc/library/asynchat.rst @@ -9,72 +9,90 @@ This module builds on the :mod:`asyncore` infrastructure, simplifying -asynchronous clients and servers and making it easier to handle protocols whose -elements are terminated by arbitrary strings, or are of variable length. +asynchronous clients and servers and making it easier to handle protocols +whose elements are terminated by arbitrary strings, or are of variable length. :mod:`asynchat` defines the abstract class :class:`async_chat` that you subclass, providing implementations of the :meth:`collect_incoming_data` and :meth:`found_terminator` methods. It uses the same asynchronous loop as -:mod:`asyncore`, and the two types of channel, :class:`asyncore.dispatcher` and -:class:`asynchat.async_chat`, can freely be mixed in the channel map. Typically -an :class:`asyncore.dispatcher` server channel generates new -:class:`asynchat.async_chat` channel objects as it receives incoming connection -requests. +:mod:`asyncore`, and the two types of channel, :class:`asyncore.dispatcher` +and :class:`asynchat.async_chat`, can freely be mixed in the channel map. +Typically an :class:`asyncore.dispatcher` server channel generates new +:class:`asynchat.async_chat` channel objects as it receives incoming +connection requests. .. class:: async_chat() This class is an abstract subclass of :class:`asyncore.dispatcher`. To make practical use of the code you must subclass :class:`async_chat`, providing - meaningful :meth:`collect_incoming_data` and :meth:`found_terminator` methods. + meaningful :meth:`collect_incoming_data` and :meth:`found_terminator` + methods. The :class:`asyncore.dispatcher` methods can be used, although not all make sense in a message/response context. - Like :class:`asyncore.dispatcher`, :class:`async_chat` defines a set of events - that are generated by an analysis of socket conditions after a :cfunc:`select` - call. Once the polling loop has been started the :class:`async_chat` object's - methods are called by the event-processing framework with no action on the part - of the programmer. + Like :class:`asyncore.dispatcher`, :class:`async_chat` defines a set of + events that are generated by an analysis of socket conditions after a + :cfunc:`select` call. Once the polling loop has been started the + :class:`async_chat` object's methods are called by the event-processing + framework with no action on the part of the programmer. - Unlike :class:`asyncore.dispatcher`, :class:`async_chat` allows you to define a - first-in-first-out queue (fifo) of *producers*. A producer need have only one - method, :meth:`more`, which should return data to be transmitted on the channel. + 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``). + + Unlike :class:`asyncore.dispatcher`, :class:`async_chat` allows you to + define a first-in-first-out queue (fifo) of *producers*. A producer need + have only one method, :meth:`more`, which should return data to be + transmitted on the channel. The producer indicates exhaustion (*i.e.* that it contains no more data) by having its :meth:`more` method return the empty string. At this point the - :class:`async_chat` object removes the producer from the fifo and starts using - the next producer, if any. When the producer fifo is empty the + :class:`async_chat` object removes the producer from the fifo and starts + using the next producer, if any. When the producer fifo is empty the :meth:`handle_write` method does nothing. You use the channel object's - :meth:`set_terminator` method to describe how to recognize the end of, or an - important breakpoint in, an incoming transmission from the remote endpoint. + :meth:`set_terminator` method to describe how to recognize the end of, or + an important breakpoint in, an incoming transmission from the remote + endpoint. To build a functioning :class:`async_chat` subclass your input methods - :meth:`collect_incoming_data` and :meth:`found_terminator` must handle the data - that the channel receives asynchronously. The methods are described below. + :meth:`collect_incoming_data` and :meth:`found_terminator` must handle the + data that the channel receives asynchronously. The methods are described + below. .. method:: async_chat.close_when_done() - Pushes a ``None`` on to the producer fifo. When this producer is popped off the - fifo it causes the channel to be closed. + Pushes a ``None`` on to the producer fifo. When this producer is popped off + the fifo it causes the channel to be closed. .. method:: async_chat.collect_incoming_data(data) - Called with *data* holding an arbitrary amount of received data. The default - method, which must be overridden, raises a :exc:`NotImplementedError` exception. + Called with *data* holding an arbitrary amount of received data. The + default method, which must be overridden, raises a + :exc:`NotImplementedError` exception. .. method:: async_chat.discard_buffers() - In emergencies this method will discard any data held in the input and/or output - buffers and the producer fifo. + In emergencies this method will discard any data held in the input and/or + output buffers and the producer fifo. .. method:: async_chat.found_terminator() - Called when the incoming data stream matches the termination condition set by - :meth:`set_terminator`. The default method, which must be overridden, raises a - :exc:`NotImplementedError` exception. The buffered input data should be - available via an instance attribute. + Called when the incoming data stream matches the termination condition set + by :meth:`set_terminator`. The default method, which must be overridden, + raises a :exc:`NotImplementedError` exception. The buffered input data + should be available via an instance attribute. .. method:: async_chat.get_terminator() @@ -90,59 +108,59 @@ requests. .. method:: async_chat.handle_read() - Called when a read event fires on the channel's socket in the asynchronous loop. - The default method checks for the termination condition established by - :meth:`set_terminator`, which can be either the appearance of a particular - string in the input stream or the receipt of a particular number of characters. - When the terminator is found, :meth:`handle_read` calls the - :meth:`found_terminator` method after calling :meth:`collect_incoming_data` with - any data preceding the terminating condition. + Called when a read event fires on the channel's socket in the asynchronous + loop. The default method checks for the termination condition established + by :meth:`set_terminator`, which can be either the appearance of a + particular string in the input stream or the receipt of a particular number + of characters. When the terminator is found, :meth:`handle_read` calls the + :meth:`found_terminator` method after calling :meth:`collect_incoming_data` + with any data preceding the terminating condition. .. method:: async_chat.handle_write() - Called when the application may write data to the channel. The default method - calls the :meth:`initiate_send` method, which in turn will call - :meth:`refill_buffer` to collect data from the producer fifo associated with the - channel. + Called when the application may write data to the channel. The default + method calls the :meth:`initiate_send` method, which in turn will call + :meth:`refill_buffer` to collect data from the producer fifo associated + with the channel. .. method:: async_chat.push(data) - Creates a :class:`simple_producer` object (*see below*) containing the data and - pushes it on to the channel's ``producer_fifo`` to ensure its transmission. This - is all you need to do to have the channel write the data out to the network, - although it is possible to use your own producers in more complex schemes to - implement encryption and chunking, for example. + Creates a :class:`simple_producer` object (*see below*) containing the data + and pushes it on to the channel's ``producer_fifo`` to ensure its + transmission. This is all you need to do to have the channel write the + data out to the network, although it is possible to use your own producers + in more complex schemes to implement encryption and chunking, for example. .. method:: async_chat.push_with_producer(producer) - Takes a producer object and adds it to the producer fifo associated with the - channel. When all currently-pushed producers have been exhausted the channel - will consume this producer's data by calling its :meth:`more` method and send - the data to the remote endpoint. + Takes a producer object and adds it to the producer fifo associated with + the channel. When all currently-pushed producers have been exhausted the + channel will consume this producer's data by calling its :meth:`more` + method and send the data to the remote endpoint. .. method:: async_chat.readable() - Should return ``True`` for the channel to be included in the set of channels - tested by the :cfunc:`select` loop for readability. + Should return ``True`` for the channel to be included in the set of + channels tested by the :cfunc:`select` loop for readability. .. method:: async_chat.refill_buffer() - Refills the output buffer by calling the :meth:`more` method of the producer at - the head of the fifo. If it is exhausted then the producer is popped off the - fifo and the next producer is activated. If the current producer is, or becomes, - ``None`` then the channel is closed. + Refills the output buffer by calling the :meth:`more` method of the + producer at the head of the fifo. If it is exhausted then the producer is + popped off the fifo and the next producer is activated. If the current + producer is, or becomes, ``None`` then the channel is closed. .. method:: async_chat.set_terminator(term) - Sets the terminating condition to be recognised on the channel. ``term`` may be - any of three types of value, corresponding to three different ways to handle - incoming protocol data. + Sets the terminating condition to be recognized on the channel. ``term`` + may be any of three types of value, corresponding to three different ways + to handle incoming protocol data. +-----------+---------------------------------------------+ | term | Description | @@ -158,8 +176,8 @@ requests. | | forever | +-----------+---------------------------------------------+ - Note that any data following the terminator will be available for reading by the - channel after :meth:`found_terminator` is called. + Note that any data following the terminator will be available for reading + by the channel after :meth:`found_terminator` is called. .. method:: async_chat.writable() @@ -174,29 +192,29 @@ asynchat - Auxiliary Classes and Functions .. class:: simple_producer(data[, buffer_size=512]) - A :class:`simple_producer` takes a chunk of data and an optional buffer size. - Repeated calls to its :meth:`more` method yield successive chunks of the data no - larger than *buffer_size*. + A :class:`simple_producer` takes a chunk of data and an optional buffer + size. Repeated calls to its :meth:`more` method yield successive chunks of + the data no larger than *buffer_size*. .. method:: simple_producer.more() - Produces the next chunk of information from the producer, or returns the empty - string. + Produces the next chunk of information from the producer, or returns the + empty string. .. class:: fifo([list=None]) - Each channel maintains a :class:`fifo` holding data which has been pushed by the - application but not yet popped for writing to the channel. A :class:`fifo` is a - list used to hold data and/or producers until they are required. If the *list* - argument is provided then it should contain producers or data items to be - written to the channel. + Each channel maintains a :class:`fifo` holding data which has been pushed + by the application but not yet popped for writing to the channel. A + :class:`fifo` is a list used to hold data and/or producers until they are + required. If the *list* argument is provided then it should contain + producers or data items to be written to the channel. .. method:: fifo.is_empty() - Returns ``True`` iff the fifo is empty. + Returns ``True`` if and only if the fifo is empty. .. method:: fifo.first() @@ -206,14 +224,14 @@ asynchat - Auxiliary Classes and Functions .. method:: fifo.push(data) - Adds the given data (which may be a string or a producer object) to the producer - fifo. + Adds the given data (which may be a string or a producer object) to the + producer fifo. .. method:: fifo.pop() - If the fifo is not empty, returns ``True, first()``, deleting the popped item. - Returns ``False, None`` for an empty fifo. + If the fifo is not empty, returns ``True, first()``, deleting the popped + item. Returns ``False, None`` for an empty fifo. The :mod:`asynchat` module also defines one utility function, which may be of use in network and textual analysis operations. @@ -221,8 +239,8 @@ use in network and textual analysis operations. .. function:: find_prefix_at_end(haystack, needle) - Returns ``True`` if string *haystack* ends with any non-empty prefix of string - *needle*. + Returns ``True`` if string *haystack* ends with any non-empty prefix of + string *needle*. .. _asynchat-example: @@ -231,19 +249,20 @@ asynchat Example ---------------- The following partial example shows how HTTP requests can be read with -:class:`async_chat`. A web server might create an :class:`http_request_handler` -object for each incoming client connection. Notice that initially the channel -terminator is set to match the blank line at the end of the HTTP headers, and a -flag indicates that the headers are being read. +:class:`async_chat`. A web server might create an +:class:`http_request_handler` object for each incoming client connection. +Notice that initially the channel terminator is set to match the blank line at +the end of the HTTP headers, and a flag indicates that the headers are being +read. -Once the headers have been read, if the request is of type POST (indicating that -further data are present in the input stream) then the ``Content-Length:`` -header is used to set a numeric terminator to read the right amount of data from -the channel. +Once the headers have been read, if the request is of type POST (indicating +that further data are present in the input stream) then the +``Content-Length:`` header is used to set a numeric terminator to read the +right amount of data from the channel. The :meth:`handle_request` method is called once all relevant input has been -marshalled, after setting the channel terminator to ``None`` to ensure that any -extraneous data sent by the web client are ignored. :: +marshalled, after setting the channel terminator to ``None`` to ensure that +any extraneous data sent by the web client are ignored. :: class http_request_handler(asynchat.async_chat): @@ -281,4 +300,3 @@ extraneous data sent by the web client are ignored. :: self.handling = True self.ibuffer = [] self.handle_request() - |