Opened 5 years ago

Last modified 5 years ago

#4228 enhancement new

Add explicit example to pb documentation showing returning a deferred in a remote_ method can be used to delay the method response

Reported by: chris_laws Owned by:
Priority: normal Milestone:
Component: pb Keywords: pb, documentation
Cc: Branch:
Author: Launchpad Bug:

Description

While writing some pb related funcitonailty in my application I needed to delay the response to a pb callRemote method call.
I spent time (on Twisted Docs and using Google) looking for some documentation showing any examples or usage patterns where I could call obj.callRemote and not return a result to the caller until some time later. The current pb documentation appears to return a result immediately.

I could not find any clear example showing that returning a deferred in a pb remote_* method would delay the delivery of the callRemote response to the caller.

<start Andrew Bennetts mailing list response>

Huh, surprisingly not in the primary PB docs. The Twisted “finger” tutorial
does do this, though, if you read it carefully enough. See finger21.tac in
<http://twistedmatrix.com/documents/current/core/howto/tutorial/pb.html>; the
remote_* methods of PerspectiveFingerFromService delegate to self.service, which
is FingerService, which returns Deferreds from its getUser and getUsers methods.

<end Andrew Bennetts mailing list response>

Through some prototyping I discovered that returning a deferred would achieve the desired result. However, it was not clear to me how this worked. (For example: was the deferred actually getting returned to the callRemote caller or was pb simply managing the deferred locally and finally delivering the result when the deferred fired?)

I was happy enough with the informative response to my "deferring result to PB a callRemote method" (Mon Jan 18 09:32:05 EST 2010) question posted to the twisted-python mailing list.
However, in a subsequent response someone mentioned that perhaps a ticket should be raised to update the documentation to clearly show this usage pattern (as it seems common) and perhaps explain how the deferred is not actually returned to the caller but is managed locally.

The following description from the mailing list response may be useful when updating documentation if this enhancement is implemented:

<start Andrew Bennetts mailing list response>

PB doesn't actually send the Deferred over the network, but it does manage the
deferred for you. It works because when you return a Deferred, PB on the server
will add a callback to it that will send that eventual result over the network,
rather than sending one immediately.

On the client side, as the PB docs point out: “because of the delay involved
[waiting for a network connection], callRemote() returns a Deferred.” (From
<http://twistedmatrix.com/documents/current/core/howto/pb-usage.html>).

The client doesn't know or care if the server used a Deferred or not, the bytes
on the wire are the same. (And a delay caused by the server waiting for a
Deferred to fire could just as easily be a delay caused by network congestion.)

<end Andrew Bennetts mailing list response>

Change History (3)

comment:1 Changed 5 years ago by khorn

thanks for submitting this ticket!

comment:2 Changed 5 years ago by exarkun

  • Milestone regular-releases deleted

comment:3 Changed 4 years ago by <automation>

  • Owner warner deleted
Note: See TracTickets for help on using tickets.