App Engine Python SDK  v1.6.9 rev.445
The Python runtime is available as an experimental Preview feature.
Classes | Public Member Functions | Public Attributes | List of all members
google.appengine.api.apiproxy_stub_map.UserRPC Class Reference
Inheritance diagram for google.appengine.api.apiproxy_stub_map.UserRPC:

Classes

class  MyLocal
 

Public Member Functions

def __init__
 
def service
 
def method
 
def deadline
 
def request
 
def response
 
def state
 
def get_result_hook
 
def user_data
 
def make_call
 
def wait
 
def check_success
 
def get_result
 
def wait_any
 
def wait_all
 

Public Attributes

 callback
 

Detailed Description

Wrapper class for asynchronous RPC.

Simplest low-level usage pattern:

  rpc = UserRPC('service', [deadline], [callback])
  rpc.make_call('method', request, response)
  .
  .
  .
  rpc.wait()
  rpc.check_success()

However, a service module normally provides a wrapper so that the
typical usage pattern becomes more like this:

  from google.appengine.api import service
  rpc = service.create_rpc([deadline], [callback])
  service.make_method_call(rpc, [service-specific-args])
  .
  .
  .
  rpc.wait()
  result = rpc.get_result()

The service.make_method_call() function sets a service- and method-
specific hook function that is called by rpc.get_result() with the
rpc object as its first argument, and service-specific value as its
second argument.  The hook function should call rpc.check_success()
and then extract the user-level result from the rpc.result
protobuffer.  Additional arguments may be passed from
make_method_call() to the get_result hook via the second argument.

Also note wait_any() and wait_all(), which wait for multiple RPCs.

Constructor & Destructor Documentation

def google.appengine.api.apiproxy_stub_map.UserRPC.__init__ (   self,
  service,
  deadline = None,
  callback = None,
  stubmap = None 
)
Constructor.

Args:
  service: The service name.
  deadline: Optional deadline.  Default depends on the implementation.
  callback: Optional argument-less callback function.
  stubmap: optional APIProxyStubMap instance, for dependency injection.

Member Function Documentation

def google.appengine.api.apiproxy_stub_map.UserRPC.check_success (   self)
Check for success of the RPC, possibly raising an exception.

This function should be called at least once per RPC.  If wait()
hasn't been called yet, it is called first.  If the RPC caused
an exceptional condition, an exception will be raised here.
The first time check_success() is called, the postcall hooks
are called.
def google.appengine.api.apiproxy_stub_map.UserRPC.deadline (   self)
Return the deadline, if set explicitly (otherwise None).
def google.appengine.api.apiproxy_stub_map.UserRPC.get_result (   self)
Get the result of the RPC, or possibly raise an exception.

This implies a call to check_success().  If a get-result hook was
passed to make_call(), that hook is responsible for calling
check_success(), and the return value of the hook is returned.
Otherwise, check_success() is called directly and None is
returned.
def google.appengine.api.apiproxy_stub_map.UserRPC.get_result_hook (   self)
Return the get-result hook function.
def google.appengine.api.apiproxy_stub_map.UserRPC.make_call (   self,
  method,
  request,
  response,
  get_result_hook = None,
  user_data = None 
)
Initiate a call.

Args:
  method: The method name.
  request: The request protocol buffer.
  response: The response protocol buffer.
  get_result_hook: Optional get-result hook function.  If not None,
this must be a function with exactly one argument, the RPC
object (self).  Its return value is returned from get_result().
  user_data: Optional additional arbitrary data for the get-result
hook function.  This can be accessed as rpc.user_data.  The
type of this value is up to the service module.

This function may only be called once per RPC object.  It sends
the request to the remote server, but does not wait for a
response.  This allows concurrent execution of the remote call and
further local processing (e.g., making additional remote calls).

Before the call is initiated, the precall hooks are called.
def google.appengine.api.apiproxy_stub_map.UserRPC.method (   self)
Return the method name.
def google.appengine.api.apiproxy_stub_map.UserRPC.request (   self)
Return the request protocol buffer object.
def google.appengine.api.apiproxy_stub_map.UserRPC.response (   self)
Return the response protocol buffer object.
def google.appengine.api.apiproxy_stub_map.UserRPC.service (   self)
Return the service name.
def google.appengine.api.apiproxy_stub_map.UserRPC.state (   self)
Return the RPC state.

Possible values are attributes of apiproxy_rpc.RPC: IDLE, RUNNING,
FINISHING.
def google.appengine.api.apiproxy_stub_map.UserRPC.user_data (   self)
Return the user data for the hook function.
def google.appengine.api.apiproxy_stub_map.UserRPC.wait (   self)
Wait for the call to complete, and call callback if needed.

This and wait_any()/wait_all() are the only time callback
functions may be called.  (However, note that check_success() and
get_result() call wait().)  Waiting for one RPC will not cause
callbacks for other RPCs to be called.  Callback functions may
call check_success() and get_result().

Callbacks are called without arguments; if a callback needs access
to the RPC object a Python nested function (a.k.a. closure) or a
bound may be used.  To facilitate this, the callback may be
assigned after the RPC object is created (but before make_call()
is called).

Note: don't confuse callbacks with get-result hooks or precall
and postcall hooks.
def google.appengine.api.apiproxy_stub_map.UserRPC.wait_all (   cls,
  rpcs 
)
Wait until all given RPCs are finished.

This is a thin wrapper around wait_any() that loops until all
given RPCs have finished.

Args:
  rpcs: Iterable collection of UserRPC instances.

Returns:
  None.
def google.appengine.api.apiproxy_stub_map.UserRPC.wait_any (   cls,
  rpcs 
)
Wait until an RPC is finished.

Args:
  rpcs: Iterable collection of UserRPC instances.

Returns:
  A UserRPC instance, indicating the first RPC among the given
  RPCs that finished; or None, indicating that either an RPC not
  among the given RPCs finished in the mean time, or the iterable
  is empty.

NOTES:

(1) Repeatedly calling wait_any() with the same arguments will not
make progress; it will keep returning the same RPC (the one
that finished first).  The callback, however, will only be
called the first time the RPC finishes (which may be here or
in the wait() method).

(2) It may return before any of the given RPCs finishes, if
another pending RPC exists that is not included in the rpcs
argument.  In this case the other RPC's callback will *not*
be called.  The motivation for this feature is that wait_any()
may be used as a low-level building block for a variety of
high-level constructs, some of which prefer to block for the
minimal amount of time without busy-waiting.

The documentation for this class was generated from the following file: