[Twisted-Python] Hip-bone's connected to the...

[Kevin Turner]

Abstract: Trace the construction of a PB-using application from the top,
    to the side, to the inside-out.

[XXX: Add "why the gleep you should actually care about PB
     introduction-hook here."]

Disclaimer: I wrote this before writing any code, and reading only a
    little.  So the possibility remains open that I am horribly,
    tragically wrong.

 ----

Application (twisted.internet.main.Application):

The overall container and entry point for your program as a whole.  The
answer to the question "Uh, okay, now how do I start it?".  In addition
to starting, it also handles shutdown, typically pickling itself to disk
in the process.  And yes, that means that when you pickle.load an object
from a twisted .spl file, an Application is what you are getting.

An Application has a name (first argument to the constructor), a string
which it uses in naming logfiles, shutdown pickles, etc.

When Applications are running, they typically have at least one Port
(see below) listening for connections, as internet..Applications which
don't communicate with anyone are less fun than dead puppies.  Ports
are added with the .addPort() method, and the Application has them
startListening as soon as it is run().

 - -

Port (twisted.internet.tcp.Port):

The class of much-debated naming, an open "server port" or "listener
port".  Constructed of two arguments (port, factory): the first is
either a TCP port number or the filename of a unix socket, the second is
an instance of a protocol.Factory -- typically a pb.BrokerFactory()

So when a Port gets a connection, it has the factory pop out a new
Protocol (in this case, a Broker), and hooks it up to the connection
with a Transport.

 - -

Broker (twisted.spread.pb.Broker)

Typically created by a pb.BrokerFactory, these broker between a
connection (from the Port) and a pb.Service.  The services available to
the broker are those which have been added to the BrokerFactory with its
addService method.

 - -

Service (twisted.spread.pb.Service)

The service you are providing (XXX: a less vauge, circular description?)
is defined as a subclass of pb.Service (ex: web.ResourcePublisher).
I expect the common usage is to only have no more than one instance
of a given Service class, as it defines the service *as a whole*,
and generally does not bother itself with the details of a request.
Instead, Services are asked (through the broker) for Perspectives,
through the getPerspectiveNamed method.

 - -

Perspective (twisted.spread.pb.Perspective)

Well, it's called "Perspective Broker", and that's what all the
excitement is about, right?  That's probably why my clarity has been
dropping as I near it...  Let me see if I can explain this.  Then
someone will have to jump in and tell me if I explained the right thing.

The reason the client is asking the server to perform a service is
because the server is able to see and do things the client does not
have access to.  That is, from the client's perspective, these things
are not visible, but from the server's perspective, they're perfectly
accessible.

Enter one Perspective Broker.  Through the Perspective Broker, clients
may have actions performed from the perspective of an object on the
server.

These objects are instances of classes descended from pb.Perspective.
If a client runs a method .foo() on a reference to such an object, the
server will run the method .perspective_foo() on the instance on the
server side.

XXX: Examples would help loads.

Note: Since all commands over the broker happen asynchronously, the
client cannot receive return values from a perspective_foo() method.

 - - 

Referenced (twisted.spread.pb.Referenced)

Since a Perspective object cannot pass data back to the client through
return values, how does the client ever learn anything about what
it's done through the broker?  If the client passes an object that is
Referenced through to the perspective, then the perspective on the
server side will be able to pass data to methods of the Referenced
object.  A call to .foo() on the server's side will call .remote_foo()
on the object in the client.  This works in much the same way as clients
calling methods of Perspective objects.

 ----

Ports get added to Applications
(a BrokerFactory is attached to the port)
Services get added to BrokerFactories
Perspectives are issued by Services

 ----

How does error notification work?
What naming conventions should application authors use?
Any other must-have pb classes?