Go to the latest version of this document.

# ``twisted`.`protocols`.`amp`.`BoxDispatcher``

class documentation

`class BoxDispatcher: (source)`

Known subclasses: `twisted.protocols.amp.AMP`

Constructor: `BoxDispatcher(locator)`

Implements interfaces: `twisted.protocols.amp.IBoxReceiver`

View In Hierarchy

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.

Method | `__init__` | Undocumented
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 | `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 | `callRemoteString` | This is a low-level API, designed only for optimizing simple messages for which the overhead of parsing is too great.
Method | `dispatchCommand` | A box with a _command key was received.
Method | `failAllOutgoing` | Call the errback on all outstanding requests awaiting responses.
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 | `unhandledError` | This is a terminal callback called after application code has had a chance to quash any errors.
Instance Variable | `boxSender` | an object which can send boxes, via the `_sendBoxCommand` method, such as an `AMP` instance.
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).
Method | `_answerReceived` | An AMP box was received that answered a command previously sent with `callRemote`.
Method | `_commandReceived` | No summary
Method | `_errorReceived` | An AMP box was received that answered a command previously sent with `callRemote`, with an error.
Method | `_nextTag` | Generate protocol-local serial numbers for _ask keys.
Method | `_safeEmit` | Emit a box, ignoring `ProtocolSwitched` and `ConnectionLost` errors which cannot be usefully handled.
Method | `_sendBoxCommand` | Send a command across the wire with the given `amp.Box`.
Class Variable | `_counter` | Undocumented
Instance Variable | `_failAllReason` | Undocumented
Instance Variable | `_outstandingRequests` | a dictionary mapping request IDs to `Deferred`s which were returned for those requests.

def __init__(self, locator): (source)
overridden in `twisted.protocols.amp.AMP`

Undocumented

def ampBoxReceived(self, box): (source)
from `twisted.protocols.amp.IBoxReceiver`

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.

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.

Parameters
commandType:`type` | a subclass of Command.
*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.

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.

Parameters
command | a `bytes` naming 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.
**kw | arguments to the amp box.

Returns
a Deferred which fires the AmpBox that holds the response to this command, or None, as specified by requiresAnswer.

def dispatchCommand(self, box): (source)

A box with a _command key was received.

Dispatch it to a local handler call it.

Parameters
box | an AmpBox to be dispatched.

def failAllOutgoing(self, reason): (source)

Call the errback on all outstanding requests awaiting responses.

Parameters
reason | the Failure instance to pass to those errbacks.

def startReceivingBoxes(self, boxSender): (source)
from `twisted.protocols.amp.IBoxReceiver`

The given boxSender is going to start calling boxReceived on this `BoxDispatcher`.

Parameters
boxSender | The `IBoxSender` to send command responses to.

def stopReceivingBoxes(self, reason): (source)
from `twisted.protocols.amp.IBoxReceiver`

No further boxes will be received here. Terminate all currently outstanding command deferreds with the given reason.

def unhandledError(self, failure): (source)

This is a terminal callback called after application code has had a chance to quash any errors.

boxSender: `IBoxSender` = (source)

an object which can send boxes, via the `_sendBoxCommand` method, such as an `AMP` instance.

locator = (source)

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).

def _answerReceived(self, box): (source)

An AMP box was received that answered a command previously sent with `callRemote`.

Parameters
box | an AmpBox with a value for its `ANSWER` key.

def _commandReceived(self, box): (source)

Parameters
box | an `AmpBox` with a value for its `COMMAND` and `ASK` keys.

def _errorReceived(self, box): (source)

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.

def _nextTag(self): (source)

Generate protocol-local serial numbers for _ask keys.

Returns
a string that has not yet been used on this connection.

def _safeEmit(self, aBox): (source)

Emit a box, ignoring `ProtocolSwitched` and `ConnectionLost` errors which cannot be usefully handled.

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.

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.

_counter: `int` = (source)

Undocumented

_failAllReason = (source)

Undocumented

_outstandingRequests = (source)

a dictionary mapping request IDs to `Deferred`s which were returned for those requests.