To make a RPC request, dereference the Remote pointer to get a stub object. Stub objects are automatically generated from the IDL and serve for two purposes:
To change parameters affecting the way the call will be performed, and
To perform the call.
Methods that set options for a remote call are universal - they are the same for each stub object. All of them return a reference to the stub object, which allows you to set multiple options and perform the call in single statement. The methods will be introduced in the following sections, for a complete list check Section 8.8, “RPC Reference Guide”
For each method defined in the IDL, two methods are implemented by the stub:
async_bar() performs asynchronous remote call (see Section 8.3, “Asynchronous RPC”).
sync_bar() performs synchronous remote call (see Section 8.4, “Synchronous RPC”).
The RPC is implemented on top of the migration protocols. Standard localization protocols are used when sending RPC requests and results. Both requests and results will be archived properly when remote call is pending. Check Chapter 6, Migration to understand potential restrictions and problems.
Execution of the standard remote call can be divided into the following steps:
When a stub object is instructed to perform a call, it creates a RPCObject, marshalls method arguments into the object and migrates it to the callee object. The stub will also create a ResultObject, which will remain on the caller node and track status of the pending call (see Figure 8.1, “Inititating Remote Call”).
When the RPCObject with the call request is delivered to the callee object, it performs the call. If the call returns successfully, RPCObject will collect the results (values of method result type and out and inout arguments). Otherwise, if exception is thrown by the method or if the RPCObject can't perform the call, information about the error will be stored in the RPCObject (see Figure 8.2, “Performing Remote Call”).
The RPCObject is sent back to ResultObject, which has been created in the first step (see Figure 8.3, “Sending Back Call Results”)
When the ResultObject receives the RPCObject, it changes its state according to the result of the call. If the call is asynchronous, the caller should check state of the ResultObject and do whatever he wants.
If the call is synchronous, the ResultObject is managed by the stub. When its state changes, stub will either simply return (if the call has been successful) or throw an exceptiong (if the call failed). The execution of the caller code will then resume (see Figure 8.4, “Delivering Call Results”)
![[Note]](images/note.png) | Note |
|---|---|
These figures describe synchronous remote call, and asynchronous remote call when delivery of results is requested. In real code, the most common variant of the RPC used is probably simple asynchronous call, which ignores results of the call. No ResultObject is created in that case, and RPCObject ignores results of the call and remains on the callee node until it's destroyed by the garbage collector. | |