Package qbuf :: Module twisted_support :: Class MultiBufferer

Class MultiBufferer

source code

twisted.internet.protocol.BaseProtocol --+    
                                         |    
        twisted.internet.protocol.Protocol --+
                                             |
                                            MultiBufferer
Known Subclasses:

A replacement for a couple of buffering classes provided by twisted.

Without subclassing, it can work the same way as LineReceiver and StatefulProtocol.

When the buffering mode is MODE_RAW, rawDataReceived is called with all of the data that comes in.

When the buffering mode is MODE_DELIMITED, lineReceived is called with each complete line without the delimiter on the end. The 'delimiter' instance attribute is used for keeping track of the current delimiter.

When the buffering mode is MODE_STATEFUL, a user-passed function is called for every so many bytes received. If self.current_state is None, getInitialState is called to get the initial state. See the documentation on getInitialState.

MultiBufferers can also return Deferreds that are fired when a certain amount of data has been sent over the wire. This is intended for use with twisted.internet.defer.inlineCallbacks.

Instance Methods
 
__init__(self) source code
 
close(self, disconnect=True)
Stop buffering incoming data.
source code
 
connectionLost(self, reason)
Called when the connection is shut down.
source code
 
dataReceived(self, data)
Called whenever data is received.
source code
 
getInitialState(self)
Called when there is no current state for MODE_STATEFUL.
source code
 
lineReceived(self, line)
Called when the buffering mode is MODE_DELIMITED and there is a new line available.
source code
 
rawDataReceived(self, data)
Called when the buffering mode is MODE_RAW and there is new data available.
source code
 
read(self, size=None)
Wait for some data to be received.
source code
 
readline(self, delimiter=None)
Wait for a line to be received.
source code
 
setMode(self, mode, extra='', flush=False, state=None, delimiter=None)
Change the buffering mode.
source code
 
unpack(self, fmt)
Wait for some struct to be received.
source code
 
write(self, data)
Send some data over the wire.
source code

Inherited from twisted.internet.protocol.BaseProtocol: __providedBy__, connectionMade, makeConnection

Class Variables
  current_state = None
  initial_delimiter = '\r\n'
  mode = 0

Inherited from twisted.internet.protocol.Protocol: __implemented__, __provides__

Inherited from twisted.internet.protocol.BaseProtocol: connected, transport

Properties
  delimiter
Method Details

close(self, disconnect=True)

source code 

Stop buffering incoming data.

This will clear the input buffer and stop adding new data to the buffer. If 'disconnect' is True, this will also lose the connection on the transport.

connectionLost(self, reason)

source code 

Called when the connection is shut down.

Clear any circular references here, and any external references to this Protocol. The connection has been closed.

Overrides: twisted.internet.protocol.Protocol.connectionLost
(inherited documentation)

dataReceived(self, data)

source code 

Called whenever data is received.

Use this method to translate to a higher-level message. Usually, some callback will be made upon the receipt of each complete protocol message.

Parameters:
  • data - a string of indeterminate length. Please keep in mind that you will probably need to buffer some data, as partial (or multiple) protocol messages may be received! I recommend that unit tests for protocols call through to this method with differing chunk sizes, down to one byte at a time.
Overrides: twisted.internet.protocol.Protocol.dataReceived
(inherited documentation)

getInitialState(self)

source code 

Called when there is no current state for MODE_STATEFUL.

This function must return a tuple of (some_callable, bytes_to_read), where the callable will be called when that number of bytes has been read, with those same bytes as the only argument. That callable can return None to keep the same (callable, n_bytes) state, or return a new (callable, n_bytes) tuple.

read(self, size=None)

source code 

Wait for some data to be received.

If 'size' is provided, wait for that many bytes to be received. Otherwise, wait for the next chunk of incoming data, regardless of the size. Returns a Deferred that will be fired with the received data.

readline(self, delimiter=None)

source code 

Wait for a line to be received.

Wait for a line of data to be received. If 'delimiter' is provided, the underlying BufferQueue's delimiter will be set to whatever is provided when the MultiBufferer is ready to receive that line. Returns a Deferred that will be fired with the received line, without delimiter.

setMode(self, mode, extra='', flush=False, state=None, delimiter=None)

source code 

Change the buffering mode.

If 'extra' is provided, add that to the buffer. If 'flush' is True and 'extra' is provided, also flush the buffer as much as possible. If 'state' is not None, that value will be assigned to self.current_state before anything else. If 'delimiter' is not None, the delimiter will be set before anything else.

unpack(self, fmt)

source code 

Wait for some struct to be received.

This method takes a struct format as understood by the 'struct' module and waits for enough data to be received to unpack it. Returns a Deferred that will be fired with the unpacked struct.

write(self, data)

source code 

Send some data over the wire.

This method merely forwards the data to the underlying transport, provided to parallel the read/readline methods.


Property Details

delimiter

Get Method:
_get_delimiter(self)
Set Method:
_set_delimiter(self, delimiter)