Introduction to Perspective Broker
Suppose you find yourself in control of both ends of the wire: you have two programs that need to talk to each other, and you get to use any protocol you want. If you can think of your problem in terms of objects that need to make method calls on each other, then chances are good that you can use twisted's Perspective Broker protocol rather than trying to shoehorn your needs into something like HTTP, or implementing yet another RPC mechanism1.
The Perspective Broker system (abbreviated PB, spawning numerous sandwich-related puns) is based upon a few central concepts:
serialization: taking fairly arbitrary objects and types, turning them into a chunk of bytes, sending them over a wire, then reconstituting them on the other end. By keeping careful track of object ids, the serialized objects can contain references to other objects and the remote copy will still be useful.
remote method calls: doing something to a local object and causing a method to get run on a distant one. The local object is called a RemoteReference, and you do something by running its .callRemote method.
This document will contain several examples that will (hopefully) appear redundant and verbose once you've figured out what's going on. To begin with, much of the code will just be labelled magic: don't worry about how these parts work yet. It will be explained more fully later.