[Twisted-Python] Is there pb documentation somewhere?

[Glyph]

On Aug 8, 2014, at 6:31 PM, Daniel Sank <sank.daniel at gmail.com> wrote:

> Now to bring the thread back on-topic,

Yes, let's get back to it, shall we?

> I'd like to ask what pb should do in principle. In other words, what is the specification for the flavors? I think a discussion of each pb flavor would be helpful and would provide me material from which I can generate missing docstrings [1]. I'd rather do it this way instead of backing out what the standing implementation currently does so that I don't waste time working on something which is a fundamentally bad idea. This discussion should be a small investment at the present time.

That sounds like a good idea.

> Copyable:
> The functionality provided by Copyable is simple. The sender of the Copyable just sends it and *forgets*. Therefore, sending a Copyable is basically just sending atomic data in a particular format. I don't think we need to discuss this any further.

Yes.  There's an important corollary to this: a Copyable ought to be immutable.  A Copyable really represents a "value" in the functional programming sense, and not an "object" in the OO sense.

> Referenceable:
> When I send you a Referenceable, I send a GUID so that you can later refer to that object.

It's not really a GUID.  The "G" in GUID stands for "global", and the IDs in Referenceable specifically draw a distinction: <https://github.com/twisted/twisted/blob/a8227e5562a4f9074bb0d5faf6a10e91069704aa/twisted/spread/pb.py#L507-L511>.  They're named LUIDs throughout.

The ID is connection-local.  When the PB connection goes away, so does the reference to that object.

> For example, I send you a message with argument (psuedo code)
> 
> "referenceable-'Joe'"
> 
> This is a declaration that I am keeping hold of an object called "Joe" upon which you may call methods remotely. Specifically, you can send me
> 
> "'Joe-foo-4"
> 
> which tells me to call Joe.foo(4) and send you the result.
> 
> 1. How long should the GUID for Joe survive? If Joe is deleted can I reuse the name "Joe" for an object created later?

Right now these IDs survive until the end of the connection.  We might want to have other ways to address objects, but that should be something higher-level; a naming service that lets you request an object by some identifier.

The ID is a counter, and since it's a Python integer, it'll never even wrap around, so it won't be re-used within the scope of the same connection.

> 2. Do I notify you if Joe disappears on my side?

Yes. <https://github.com/twisted/twisted/blob/a8227e5562a4f9074bb0d5faf6a10e91069704aa/twisted/spread/pb.py#L365-L369>.

> Let's stop here for now. I owe glyph some reviews [2].
> 
> Yours sincerely,
> Daniel
> 
> [1] I already submitted a patch to the pb documentation and improved the submission based on review. I hope this provides some indication of my commitment to make material contributions. I mention this because glyph made a comment suggesting that showing real work would be valuable.

Thanks for pointing that out.  Stuff is happening, everybody ;-).

> [2] Is this the beginning of a process which will lead me in the end to complete servitude and loss of ownership of my own soul?

Oh, don't worry.  That's not the end.  That is merely the beginning.

-glyph

-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20140809/1155068d/attachment-0002.html>