fwRPC
 All Files Functions Variables
fwRPC_client.ctl File Reference

Functions

bool fwRPC_client_monitorIsRunning (anytype ctx)
 
void fwRPC_client_startMonitor (anytype &ctx, string &clientName, bool distributed=false, bool forceReduDetect=false)
 
void fwRPC_client_startMonitor_poolContext (anytype &ctx, string &clientName, bool distributed=false, bool forceReduDetect=false)
 
void fwRPC_client_stopMonitor_poolContext (anytype ctx, string clientName)
 
string _fwRPC_client_getContextNameFromPool ()
 
bool _fwRPC_client_returnContextNameToPool (const string contextName)
 
void fwRPC_client_ensureMinimumPoolSize (const uint minPoolSize)
 
void fwRPC_client_stopMonitor (anytype ctx)
 
private void _fwRPC_client_dbg_report (anytype ctx)
 
private void _fwRPC_client_beginTick (anytype ctx, bool isRedundantSystem=false)
 
int fwRPC_client_recover (anytype ctx, string callback)
 
int fwRPC_client_acknowledge (anytype ctx, anytype rpcHandle)
 
int fwRPC_client_getResult (anytype ctx, anytype rpcHandle, mixed &result, bool acknowledge=true, int timeout=5000)
 
int fwRPC_client_call (anytype ctx, anytype &rpcHandle, string func, anytype params, bool autoAck=false, int timeout=0)
 
int fwRPC_client_callSync (anytype ctx, string func, anytype params, mixed &result, bool acknowledge=true, int timeout=5000)
 
int fwRPC_client_cancel (anytype ctx, anytype rpcHandle)
 
int fwRPC_client_listServices (anytype ctx, dyn_string &services, bool refresh=false, int timeout=5000)
 
int fwRPC_client_getStatus (anytype ctx, anytype rpcHandle)
 
void fwRPC_client_subscribeCallStatus (anytype ctx, anytype rpcRef, string callback)
 
void fwRPC_client_unsubscribeCallStatus (anytype ctx, anytype rpcRef, string callback)
 
bool fwRPC_client_isConnected (anytype ctx)
 
private void _fwRPC_client_distHdlConnect (anytype ctx, string project, string name, anytype msg)
 
private void _fwRPC_client_distHdlResult (anytype ctx, string project, string name, anytype msg)
 
private void _fwRPC_client_distHdlListServices (anytype ctx, string project, string name, anytype msg)
 
private void _fwRPC_client_distHdlStatus (anytype ctx, string project, string name, anytype msg)
 
private void _fwRPC_client_unsubscribeAllCallbacks (anytype ctx, anytype rpcRef)
 
private void _fwRPC_client_executeCB (string callback, anytype hdl, int status)
 
private void _fwRPC_client_processStatusUpdate (anytype ctx, anytype rpcHandle, int status, mixed retval=fwRPC_REQUEST_INVALID_RETVAL)
 
private void _fwRPC_client_assertRunning (anytype ctx, bool running)
 
private void _fwRPC_client_assertValidHdl (anytype handle)
 
private void _fwRPC_client_linkRedu ()
 
private void _fwRPC_client_unlinkRedu ()
 
private void _fwRPC_client_reduEventCB (anytype _, dyn_dyn_anytype results) synchronized(g_fwRPC_client_redu_state)
 

Variables

global const int fwRPC_CLIENT_E_SUCCESS = 0
 
global const int fwRPC_CLIENT_E_ERROR = -1
 
global const int fwRPC_CLIENT_E_TIMEOUT = -2
 
private global mapping g_fwRPC_client_subscriptions
 
private global mapping g_fwRPC_client_monitorIsRunning
 
private global mapping g_fwRPC_client_activeRequests
 
private global mapping g_fwRPC_client_services
 
private global mapping g_fwRPC_client_isConnected
 
private global const int _fwRPC_CLIENT_TICK_RATE_S = 1
 
private global const int _fwRPC_CLIENT_RESPONSE_POLL_MS = 50
 
private global mapping g_fwRPC_client_redu_state
 
private const string fwRPC_MSGCLIENT_POOL_NAME = "clientPool"
 

Detailed Description

This library contains the set of functions to request and monitor RPC calls. Part of the client-side RPC library.

Author
Victor Rodrigues (CERN, BE-ICS-SDS)

Function Documentation

string _fwRPC_client_getContextNameFromPool ( )
Returns
context name from the shared pool of contexts. If no context is available, empty string is returned.
bool _fwRPC_client_returnContextNameToPool ( const string  contextName)

Puts the given context back to the shared pool

Parameters
stringcontextName - name of the context that should be put back to the shared pool
Returns
true if the operation was successful, else false.

We put the context in the pool, AT THE END of the list. It would be more effecient to put it at the beginning, however there seems to be a problem with Ring Buffer indexes when the context are used too frequently.

See Also
PSEN-2287, ENS-22030
int fwRPC_client_acknowledge ( anytype  ctx,
anytype  rpcHandle 
)

Attempt to acknowledge a previous RPC request. Acknowledging a requests will cause the rpcHandle to no longer be valid for the current request instance.

Parameters
rpcHandle(IN, anytype) RPC request handle
Returns
fwRPC_CLIENT_E_SUCCESS on success fwRPC_CLIENT_E_ERROR otherwise
Exceptions
ifthe client was not initialized if the monitor is not running
int fwRPC_client_call ( anytype  ctx,
anytype &  rpcHandle,
string  func,
anytype  params,
bool  autoAck = false,
int  timeout = 0 
)

Attempt an asynchronous RPC call to a registered function with given parameters. Returns a request handle which is used to reference the particular requests when using other functions such as for subscription.

Note that it there is no guarantee as to which system the function is called at when in distributed mode, nor is it consistent, as requests are balanced by the broker.

A timeout value can be specified which, if set to a positive value, the client monitor will locally timeout the request if no response has been received by the broker by that time. Timeout is specified in milliseconds.

Parameters
rpcHandle(OUT, anytype) RPC request handle
func(IN, string) function to call
params(IN, anytype) function parameters
timeout(IN, int) time to wait before setting state to TIMEOUT
Returns
fwRPC_CLIENT_E_SUCCESS on success fwRPC_CLIENT_E_ERROR otherwise
Exceptions
ifthe monitor is not running if function is an empty string
int fwRPC_client_callSync ( anytype  ctx,
string  func,
anytype  params,
mixed &  result,
bool  acknowledge = true,
int  timeout = 5000 
)

Attempt a synchronous RPC call to a registered function with given parameters. Will wait for a result (blocking) until timeout is reached.

This function has the same effect as calling fwRPC_client_call() followed by fwRPC_client_getResult().

Parameters
func(IN, string) the name of the function to call
params(IN, anytype) parameters ot pass to the function
result(OUT, mixed) result of the function call
acknowledge(IN, bool) wheter or not to automatically acknowledge on success
timeout(IN, int) timeout, in MS to wait for a response
Returns
last known result status fwRPC_CLIENT_E_ERROR on error fwRPC_CLIENT_E_TIMEOUT on timeout
Exceptions
ifthe monitor is not running if func is an empty string
int fwRPC_client_cancel ( anytype  ctx,
anytype  rpcHandle 
)

Attempt to cancel an active request. Note that it is not guaranteed that a cancellation will take place before the request completes.

Parameters
rpcHandle(IN, anytype) RPC request handle
Returns
fwRPC_CLIENT_E_SUCCESS on success fwRPC_CLEINT_E_ERROR otherwise
Exceptions
ifthe monitor is not running
void fwRPC_client_ensureMinimumPoolSize ( const uint  minPoolSize)

Ensures that shared context pool for clients has a minimal size.

uint minPoolSize - min size of the client context pool

int fwRPC_client_getResult ( anytype  ctx,
anytype  rpcHandle,
mixed &  result,
bool  acknowledge = true,
int  timeout = 5000 
)

Retrieve a result from a previous RPC request. If timeout is > 0, then it will wait (blocking) until the request is complete.

If the return value is not fwRPC_REQUEST_STATUS_DONE or fwRPC_REQUEST_STATUS_ERROR, then the result parameter will be undefined.

Parameters
rpcHandle(IN, anytype) RPC request handle
result(OUT, mixed) the result, if timeout not reached
acknowledge(IN, bool) whether or not to automatically acknowledge the request on success
timeout(IN, int) timeout, in MS to wait for a response
Returns
result code on success last known status if result is not ready fwRPC_CLIENT_E_ERROR on failure fwRPC_CLIENT_E_TIMEOUT on result retrieval timeout
Exceptions
ifthe monitor is not running if the provided handle is invalid
int fwRPC_client_getStatus ( anytype  ctx,
anytype  rpcHandle 
)

Retrieve the status of a RPC request.

Parameters
rpcHandle(IN, anytype) RPC request handle
Returns
last known status for the given request
Exceptions
ifthe monitor is not running
bool fwRPC_client_isConnected ( anytype  ctx)

Check whether or not the client is connected to a core / broker.

Returns
true if connected false otherwise
Exceptions
nothing
int fwRPC_client_listServices ( anytype  ctx,
dyn_string &  services,
bool  refresh = false,
int  timeout = 5000 
)

Retrieve a list of active services. Caches the list of services until this function is called again with refresh set to true. If the client is in local mode, then the timeout parameter may be ignored.

Parameters
services(OUT, dyn_string) list of available services
refresh(IN, bool) whether or not to refresh the list of services
timeout(IN, int) in distributed mode, the amount of time to wait in MS for a response.
Returns
fwRPC_CLIENT_E_SUCCESS on success, fwRPC_CLIENT_E_TIMEOUT on timeout fwRPC_CLIENT_E_ERROR otherwise
Exceptions
ifthe client COMM was not initialized when in distributed mode.
bool fwRPC_client_monitorIsRunning ( anytype  ctx)

Return whether or not the client monitor is currently running.

Returns
true if the client monitor is running false otherwise
Exceptions
nothing
int fwRPC_client_recover ( anytype  ctx,
string  callback 
)

Attempt to recover previous unacknowledged requests. Useful in case of client crash.

The callback function should follow the same signature as the subscription callback function.

Parameters
callback(IN, string) callback function
Returns
fwRPC_CLIENT_E_SUCCESS on success fwRPC_CLIENT_E_ERROR otherwise
Exceptions
ifthe monitor is not running
void fwRPC_client_startMonitor ( anytype &  ctx,
string &  clientName,
bool  distributed = false,
bool  forceReduDetect = false 
)

Start the client. Required for any RPC requests, local or remote. If a client with the given or generated name was already running in the current CTRL context, then it is taken over.

The client name is automatically set to the panel name, or if started in a WCCOActrl manager, it will be set to a value generated by the msgClient. The name can also be manually specified.

If manually specified, the client name MUST be unique.

Parameters
clientName(IN|OUT, string) unique client name.
distributed(IN, bool) whether or not to start in distributed mode
Returns
nothing
Exceptions
ifthe connection was not successful.
void fwRPC_client_startMonitor_poolContext ( anytype &  ctx,
string &  clientName,
bool  distributed = false,
bool  forceReduDetect = false 
)

Similar to fwRPC_client_startMonitor() but ignores the given client name (context name). Instead it assigns a context from a shared pool.

See Also
fwRPC_client_startMonitor()
void fwRPC_client_stopMonitor ( anytype  ctx)

Stop the current client monitor. Detaches any message listeners in local or distributed mode.

Returns
nothing
Exceptions
ifthe monitor is not running if dpQueryConnect failed
void fwRPC_client_stopMonitor_poolContext ( anytype  ctx,
string  clientName 
)

Similar to fwRPC_client_stopMonitor() function but this one is used for stopping monitor of contexts taken from shared pool. This function returns the given context back to the shared pool so it can be reused again during another RPC call.

See Also
fwRPC_client_stopMonitor()
void fwRPC_client_subscribeCallStatus ( anytype  ctx,
anytype  rpcRef,
string  callback 
)

Subscribe a callback function to the status change event of an async RPC call

Callback function must have the following signatue: void callback(anytype callHandle, int status)

The callHandle parameter passed to the callback function is the same as the rpcRef passed to this function.

Parameters
rpcRef(IN, anytype) async RPC call handle
callback(IN, string) name of the function to call on event.
Returns
nothing
Exceptions
ifthe monitor is not running if rpcRef is not a valid handle
void fwRPC_client_unsubscribeCallStatus ( anytype  ctx,
anytype  rpcRef,
string  callback 
)

Unsubscribe a callback function from the status change event of an async RPC call.

The specified callback function and call handle must be the same pair as a currently subscribed pair.

Parameters
rpcRef(IN, anytype) async RPC call handle
callback(IN, string) name of the function to call on event.
Returns
nothing
Exceptions
ifthe monitor is not running if rpcRef is not a valid handle

Variable Documentation

private global const int _fwRPC_CLIENT_RESPONSE_POLL_MS = 50

Time in ms to wait between poll attempts for a message response. Used for getResult polls and listServices.

private global const int _fwRPC_CLIENT_TICK_RATE_S = 1

Time to wait in seconds between ticks to check for local request timeout.

global const int fwRPC_CLIENT_E_SUCCESS = 0

Error codes

private global mapping g_fwRPC_client_activeRequests

Mapping of all call results. Structure: key = client context handle value = mapping: key = request handle value = request model

private global mapping g_fwRPC_client_isConnected

Whether or not the client is presumed to be connected to a core or broker. Structure: key = client context handle value = client with ctx is connected

private global mapping g_fwRPC_client_monitorIsRunning

Whether or not the client is running. Structure: key = client context handle value = client with ctx is running

private global mapping g_fwRPC_client_redu_state

Previous known redu states. Used when connected to a redundant system. key: key: redu peer value: dyn_bool:

private global mapping g_fwRPC_client_services

List of available services. Structure: key = client context handle value = DYN_STRING: [x]: procedure name

private global mapping g_fwRPC_client_subscriptions

End error codes Collection of client subscriptions. Structure: key = client context handle value = DYN_DYN_MIXED: [1]: request handle [2]: callback function