t.p.a.BoxDispatcher : class documentation

Part of twisted.protocols.amp View Source View In Hierarchy

Known subclasses: twisted.protocols.amp.AMP

Implements interfaces: twisted.protocols.amp.IBoxReceiver

A BoxDispatcher dispatches '_ask', '_answer', and '_error' AmpBoxes, both incoming and outgoing, to their appropriate destinations.

Outgoing commands are converted into Deferreds and outgoing boxes, and associated tracking state to fire those Deferred when '_answer' boxes come back. Incoming '_answer' and '_error' boxes are converted into callbacks and errbacks on those Deferreds, respectively.

Incoming '_ask' boxes are converted into method calls on a supplied method locator.
Instance Variables_outstandingRequestsa dictionary mapping request IDs to Deferreds which were returned for those requests.
locatoran object with a locateResponder method that locates a responder function that takes a Box and returns a result (either a Box or a Deferred which fires one).
boxSenderan object which can send boxes, via the _sendBox method, such as an AMP instance. (type: IBoxSender )
Method __init__ Undocumented
Method startReceivingBoxes The given boxSender is going to start calling boxReceived on this BoxDispatcher.
Method stopReceivingBoxes No further boxes will be received here. Terminate all currently oustanding command deferreds with the given reason.
Method failAllOutgoing Call the errback on all outstanding requests awaiting responses.
Method callRemoteString This is a low-level API, designed only for optimizing simple messages for which the overhead of parsing is too great.
Method callRemote This is the primary high-level API for sending messages via AMP. Invoke it with a command and appropriate arguments to send a message to this connection's peer.
Method unhandledError This is a terminal callback called after application code has had a chance to quash any errors.
Method ampBoxReceived An AmpBox was received, representing a command, or an answer to a previously issued command (either successful or erroneous). Respond to it according to its contents.
Method dispatchCommand A box with a _command key was received.
Method _nextTag Generate protocol-local serial numbers for _ask keys.
Method _sendBoxCommand Send a command across the wire with the given amp.Box.
Method _answerReceived An AMP box was received that answered a command previously sent with callRemote.
Method _errorReceived An AMP box was received that answered a command previously sent with callRemote, with an error.
Method _commandReceived
Method _safeEmit Emit a box, ignoring ProtocolSwitched and ConnectionLost errors which cannot be usefully handled.
def __init__(self, locator): (source)
Undocumented
def startReceivingBoxes(self, boxSender): (source)
The given boxSender is going to start calling boxReceived on this BoxDispatcher.
ParametersboxSenderThe IBoxSender to send command responses to.
def stopReceivingBoxes(self, reason): (source)
No further boxes will be received here. Terminate all currently oustanding command deferreds with the given reason.
def failAllOutgoing(self, reason): (source)
Call the errback on all outstanding requests awaiting responses.
Parametersreasonthe Failure instance to pass to those errbacks.
def _nextTag(self): (source)
Generate protocol-local serial numbers for _ask keys.
Returnsa string that has not yet been used on this connection.
def _sendBoxCommand(self, command, box, requiresAnswer=True): (source)

Send a command across the wire with the given amp.Box.

Mutate the given box to give it any additional keys (_command, _ask) required for the command and request/response machinery, then send it.

If requiresAnswer is True, returns a Deferred which fires when a response is received. The Deferred is fired with an amp.Box on success, or with an amp.RemoteAmpError if an error is received.

If the Deferred fails and the error is not handled by the caller of this method, the failure will be logged and the connection dropped.
Parameterscommanda str, the name of the command to issue.
boxan AmpBox with the arguments for the command.
requiresAnswera boolean. Defaults to True. If True, return a Deferred which will fire when the other side responds to this command. If False, return None and do not ask the other side for acknowledgement.
Returnsa Deferred which fires the AmpBox that holds the response to this command, or None, as specified by requiresAnswer.
RaisesProtocolSwitchedif the protocol has been switched.
def callRemoteString(self, command, requiresAnswer=True, **kw): (source)
This is a low-level API, designed only for optimizing simple messages for which the overhead of parsing is too great.
Parameterscommanda str naming the command.
kwarguments to the amp box.
requiresAnswera boolean. Defaults to True. If True, return a Deferred which will fire when the other side responds to this command. If False, return None and do not ask the other side for acknowledgement.
Returnsa Deferred which fires the AmpBox that holds the response to this command, or None, as specified by requiresAnswer.
def callRemote(self, commandType, *a, **kw): (source)
This is the primary high-level API for sending messages via AMP. Invoke it with a command and appropriate arguments to send a message to this connection's peer.
ParameterscommandTypea subclass of Command. (type: type )
aPositional (special) parameters taken by the command. Positional parameters will typically not be sent over the wire. The only command included with AMP which uses positional parameters is ProtocolSwitchCommand, which takes the protocol that will be switched to as its first argument.
kwKeyword arguments taken by the command. These are the arguments declared in the command's 'arguments' attribute. They will be encoded and sent to the peer as arguments for the commandType.
ReturnsIf commandType has a requiresAnswer attribute set to False, then return None. Otherwise, return a Deferred which fires with a dictionary of objects representing the result of this call. Additionally, this Deferred may fail with an exception representing a connection failure, with UnknownRemoteError if the other end of the connection fails for an unknown reason, or with any error specified as a key in commandType's errors dictionary.
def unhandledError(self, failure): (source)
This is a terminal callback called after application code has had a chance to quash any errors.
def _answerReceived(self, box): (source)
An AMP box was received that answered a command previously sent with callRemote.
Parametersboxan AmpBox with a value for its ANSWER key.
def _errorReceived(self, box): (source)
An AMP box was received that answered a command previously sent with callRemote, with an error.
Parametersboxan AmpBox with a value for its ERROR, ERROR_CODE, and ERROR_DESCRIPTION keys.
def _commandReceived(self, box): (source)
Parametersboxan AmpBox with a value for its COMMAND and ASK keys.
def ampBoxReceived(self, box): (source)
An AmpBox was received, representing a command, or an answer to a previously issued command (either successful or erroneous). Respond to it according to its contents.
Parametersboxan AmpBox
RaisesNoEmptyBoxeswhen a box is received that does not contain an '_answer', '_command' / '_ask', or '_error' key; i.e. one which does not fit into the command / response protocol defined by AMP.
def _safeEmit(self, aBox): (source)
Emit a box, ignoring ProtocolSwitched and ConnectionLost errors which cannot be usefully handled.
def dispatchCommand(self, box): (source)

A box with a _command key was received.

Dispatch it to a local handler call it.
Parametersprotoan AMP instance.
boxan AmpBox to be dispatched.
API Documentation for Twisted, generated by pydoctor at 2011-10-27 16:27:37.