google.appengine.api.apiproxy_stub_map.UserRPC

Wrapper class for asynchronous RPC.

Inherits From: expected_type

google.appengine.api.apiproxy_stub_map.UserRPC(
    service, deadline=None, callback=None, stubmap=None
)

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.

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.

deadline Return the deadline, if set explicitly (otherwise None).
future Return the underlying RPC's future, if present.
get_result_hook Return the get-result hook function.
method Return the method name.
request Return the request protocol buffer object.
response Return the response protocol buffer object.
service Return the service name.
state Return the RPC state.

Possible values are attributes of apiproxy_rpc.RPC: IDLE, RUNNING, FINISHING.

user_data Return the user data for the hook function.

Child Classes

class MyLocal

Methods

check_success

View source

check_success()

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.

get_result

View source

get_result()

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.

make_call

View source

make_call(
    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.

wait

View source

wait()

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).

wait_all

View source

@classmethod
wait_all(
    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.

wait_any

View source

@classmethod
wait_any(
    rpcs
)

Wait until an RPC is finished.

A WaitCanceller can also be included in the list of RPCs as a mechanism to cancel the wait.

Args
rpcs Iterable collection of UserRPC or WaitCanceller 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:

  • Repeatedly calling wait_any() with the same arguments will not wait; it will immediately return, meaning it will return the same RPC until one earlier in the collection finishes. The callback, however, will only be called the first time the RPC finishes (which may be here or in the wait() method).