RPCStubs — client-side (caller-side) part of RPC implementation.
class RPCStubs
{
public:
RPCStubs & param
(
int flags = RPC_DEFAULT,
const STime & time = STime()
);
RPCStubs & request_replica
(
const STime & timeout
);
RPCStubs & optimize_replica
(
const STime & timeout
);
}; |
The synopsis is a bit misleading. For each managed class (class described in the IDL), single stub class will be generated. Each stub class implements the three methods mentioned above, as well as methods performing the call (described in Section 8.3, “Asynchronous RPC” and Section 8.4, “Synchronous RPC”). In the synopsis, RPCStubs stands for class name of any stub class.
Dereferencing a Remote pointer returns a stub object for a class of a given type. To be able to use Remote pointers to class described in foo.idl, include generated header foo_rpc.h.
You should never store a reference or a pointer to a stub object. Each of the three “universal” methods returns reference to the stub object itself, so they can all be called easily in a single statement. Actually, it's hard not to do the whole set-up-options-and-perform-the-call in a single statement, because dereferencing a Remote pointer always returns a new stub object instance with default options set. This means that you don't really have to care about the real stub class names.
Use param() to change call flags and delivery time. The method has two optional arguments:
flags: Combination of RPCFlags, described below.
time: Simulation time when the remote method should be called. Depending on flags, it's either absolute (if RPC_TIMED flag is set) or relative to current simulation time (if RPC_DELAYED flag is set).
Default parameters yield one-way asynchronous immediate call or immediate synchronous call.
The following public RPCFlags are defined:
| Flag | Description |
|---|---|
| RPC_TIMED[a] | The time argument is absolute. |
| RPC_DELAYED[a][b] | The time argument is relative to current simulation tieme. |
| RPC_RESULTS | When performing asynchronous call, the stub will return a ResultObject and return pointer to the object. It can be used to monitor call status and to retrieve call results. See Section 8.5.4, “Getting Reply to Asynchronous RPC”. |
| RPC_ALLOW_LOCAL_REPLICA_CALL[c] | Enable replica-optimized SRPC. See Section 8.5.2, “Synchronous RPC Optimizations”. |
| RPC_REPLICAS[b] | Call method of replicas of given object. This flag can't be combined with RPC_RESULTS. See Section 8.5.3, “Asynchronous RPC to Replicas”. |
| RPC_DEFAULT | Default value of flags. Equal to RPC_TIMED. |
[a] Exactly one of RPC_TIMED and RPC_DELAYED flags must be set. [b] It's illegal to set this flag when performing a synchronous call. [c] It's illegal to set this flag when performing an asynchronous call. | |
Because synchronous calls can't be scheduled into the future, you can't set the RPC_DELAYED flags or time argument to non-zero time.
Request replication of the callee object to the caller node for timeout number of seconds. See Section 8.5.1, “Triggering Replication by RPC”.