API Usage: Remote Procedure Calls (RPC)

Introduction

In the context of TE, Remote Procedure Calls functionality provides the ability to invoke a function on a Test Agent side. It can be obvious, but anyway it is worth nothing that in order to call a function on Test Agent a special action shall be done to tell Agent to treat that function as a function for RPC calls. I.e. RPC does not allow any function on Test Agent to be called, but only a set of functions that were told to be RPC aware.

On Test Engine side RPC functionlity is exported by RCF RPC library: API: RCF RPC, but end users should utilize and if necessary enhance upper layer API exported by TAPI: Remote Procedure Calls (RPC).

Here is the diagram of libraries and TE components that take part in RPC data flow:

RCF RPC library is actually reside at the same layer as RCF API library, but it is selected to a dedicated library just to split it on functionality basis.

RPC Server

Any RPC call is done in the context of RPC Server. RPC Server is a separate process or thread on Test Agent side in which context a function call is done. From Test code point of view RPC Server is represented by rcf_rpc_server data structure and it is associated with a pair of names - Test Agent name and RPC Server name (this pair of names are used in configurator tree to identify RPC Server).

In order to create or delete an RPC Server, functions from RCF RPC library should be used:

rcf_rpc_server_create() - to create an RPC Server with particular name on the particular Test Agent;
rcf_rpc_server_destroy() - to destroy an RPC Server.

Creating and deleting an RPC Server is done via Configurator management tree. On Test Agent side this causes RCF PCH library to pass control to corresponding configuration model handlers - /agent/rpcserver node.

When a new RPC Server is being created Test Agent creates a new thread or process (depending on the desired location of RPC server). Please note that to create an RPC Server in thread context you will first need to create an RPC Server in a process context and only then you can create another RPC Server as a thread of that previously created process context RPC Server.

Each RPC Server has its own communication link with Test Agent process. On RPC Server start-up it connects to Test Agent in order to set-up that communication link.

There are the following functions available for creating RPC Server in different contexts:

Each RPC Server can be switched to use a particular dynamic library on function name resolution during RPC call operation. To change dynamic library name the following function shall be used:

rcf_rpc_setlibname().

Once you have an RPC Server handle you are ready to do RPC call by means of the following function:

rcf_rpc_call().

For more information on functions exported by RCF RPC library refer to API: RCF RPC.

TAPI for RPC

Test code should not use rcf_rpc_call() function directly, but instead it shall use functions exported by TAPI: Remote Procedure Calls (RPC).