twisted.protocols.amp.BoxDispatcher
class documentationtwisted.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' AmpBox
es, both
incoming and outgoing, to their appropriate destinations.
Outgoing commands are converted into Deferred
s 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 Deferred
s,
respectively.
Incoming '_ask' boxes are converted into method calls on a supplied method locator.
Instance Variable | locator | an object with a CommandLocator.locateResponder
method that locates a responder function that takes a Box and returns a
result (either a Box or a Deferred which fires one). |
Instance Variable | boxSender | an object which can send boxes, via the _sendBoxCommand
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 outstanding 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. |
Instance Variable | _outstandingRequests | a dictionary mapping request IDs to Deferred s
which were returned for those requests. |
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. |
Deferred
s
which were returned for those requests.
CommandLocator.locateResponder
method that locates a responder function that takes a Box and returns a
result (either a Box or a Deferred which fires one).
_sendBoxCommand
method, such as an AMP
instance. (type: IBoxSender
)
The given boxSender is going to start calling boxReceived on this BoxDispatcher
.
Parameters | boxSender | The IBoxSender to
send command responses to. |
No further boxes will be received here. Terminate all currently outstanding command deferreds with the given reason.
Call the errback on all outstanding requests awaiting responses.
Parameters | reason | the Failure instance to pass to those errbacks. |
Generate protocol-local serial numbers for _ask keys.
Returns | a string that has not yet been used on this connection. |
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.
Parameters | command | a bytes , the name of the command to issue. |
box | an AmpBox with the arguments for the command. | |
requiresAnswer | a 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. | |
Returns | a Deferred which fires the AmpBox that holds the response to this command, or None, as specified by requiresAnswer. | |
Raises | ProtocolSwitched | if the protocol has been switched. |
This is a low-level API, designed only for optimizing simple messages for which the overhead of parsing is too great.
Parameters | command | a bytes naming the command. |
kw | arguments to the amp box. | |
requiresAnswer | a 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. | |
Returns | a Deferred which fires the AmpBox that holds the response to this command, or None, as specified by requiresAnswer. |
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.
Parameters | commandType | a subclass of Command. (type: type ) |
a | Positional (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. | |
kw | Keyword 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 . | |
Returns | If 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. |
This is a terminal callback called after application code has had a chance to quash any errors.
An AMP box was received that answered a command previously sent with callRemote
.
Parameters | box | an AmpBox with a value for its ANSWER key. |
An AMP box was received that answered a command previously sent with callRemote
,
with an error.
Parameters | box | an AmpBox with
a value for its ERROR , ERROR_CODE ,
and ERROR_DESCRIPTION
keys. |
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.
Parameters | box | an AmpBox |
Raises | NoEmptyBoxes | when 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. |
Emit a box, ignoring ProtocolSwitched
and ConnectionLost
errors which cannot be usefully handled.
A box with a _command key was received.
Dispatch it to a local handler call it.
Parameters | proto | an AMP instance. |
box | an AmpBox to be dispatched. |