ObjectProxy and Future¶

After initial setup, these classes are the main API through which a remote process is controlled.

class pyacq.core.rpc.ObjectProxy(rpc_addr, obj_id, ref_id, type_str='', attributes=(), **kwds)[source]¶

Proxy to an object stored by a remote RPCServer.

A proxy behaves in most ways like the object that it wraps–you can request the same attributes, call methods, etc. There are a few important differences:

A proxy can be on a different thread, process, or machine than its object, so long as the object’s thread has an RPCServer and the proxy’s thread has an associated RPCClient.
Attribute lookups and method calls can be slower because the request and response must traverse a socket. These can also be performed asynchronously to avoid blocking the client thread.
Function argument and return types must be serializable or proxyable. Most basic types can be serialized, including numpy arrays. All other objects are automatically proxied, but there are some cases when this will not work well.
__repr__() and __str__() are overridden on proxies to allow safe debugging.
__hash__() is overridden to ensure that remote hash values are not used locally.

For the most part, object proxies can be used exactly as if they are local objects:

client = RPCClient(address)  # connect to RPCServer
rsys = client._import('sys') # returns proxy to sys module on remote process
rsys.stdout.write            # proxy to remote sys.stdout.write
rsys.stdout.write('hello')   # calls sys.stdout.write('hello') on remote machine
                             # and returns the result (None)

When calling a proxy to a remote function, the call can be made synchronous (caller is blocked until result can be returned), asynchronous (Future is returned immediately and result can be accessed later), or return can be disabled entirely:

ros = proc._import('os')

# synchronous call; caller blocks until result is returned
pid = ros.getpid()

# asynchronous call
request = ros.getpid(_sync='async')
while not request.hasResult():
    time.sleep(0.01)
pid = request.result()

# disable return when we know it isn't needed.
rsys.stdout.write('hello', _sync='off')

Additionally, values returned from a remote function call are automatically returned either by value (must be picklable) or by proxy. This behavior can be forced:

rnp = proc._import('numpy')
arrProxy = rnp.array([1,2,3,4], _return_type='proxy')
arrValue = rnp.array([1,2,3,4], _return_type='value')

The default sync and return_type behaviors (as well as others) can be set for each proxy individually using ObjectProxy._set_proxy_options() or globally using proc.set_proxy_options().

It is also possible to send arguments by proxy if an RPCServer is running in the caller’s thread (this can be used, for example, to connect Qt signals across network connections):

def callback():
    print("called back.")

# Remote process can invoke our callback function as long as there is 
# a server running here to process the request.
remote_object.set_callback(proxy(callback))

__call__(*args, **kwargs)[source]¶

Call the proxied object from the remote process.

All positional and keyword arguments (except those listed below) are sent to the remote procedure call.

In synchronous mode (see parameters below), this method blocks until the remote return value has been received, and then returns that value. In asynchronous mode, this method returns a Future instance immediately, which may be used to retrieve the return value later. If return is disabled, then the method immediately returns None.

If the remote call raises an exception on the remote process, then this method will raise RemoteCallException if in synchronous mode, or calling Future.result() will raise RemoteCallException if in asynchronous mode. If return is disabled, then remote exceptions will be ignored.

Parameters:

_sync: ‘off’, ‘sync’, or ‘async’: Set the sync mode for this call. The default value is determined by the ‘sync’ argument to _set_proxy_options().
_return_type: ‘value’, ‘proxy’, or ‘auto’: Set the return type for this call. The default value is determined by the ‘return_type’ argument to _set_proxy_options().
_timeout: float: Set the timeout for this call. The default value is determined by the ‘timeout’ argument to _set_proxy_options().