RPC over LPF

Collaboration diagram for RPC over LPF:

Typedefs
typedef lpf_init_t	lpf_rpc_server_t
typedef lpf_args_t	lpf_rpc_query_t

Functions
lpf_err_t	lpf_mpirpc_open (const char *const hostname, const char *const portname, const int timeout, lpf_rpc_server_t *const server)
lpf_err_t	lpf_mpirpc_close_server (const lpf_rpc_server_t server)
lpf_err_t	lpf_rpc_query_create (const void *const payload, const size_t payload_size, const size_t response_size, lpf_rpc_query_t *const query)
lpf_err_t	lpf_rpc_query_destroy (lpf_rpc_query_t query)
lpf_err_t	lpf_rpc_send_query (lpf_rpc_query_t query, lpf_rpc_server_t server, void **const response)

Variables
const lpf_rpc_server_t	LPF_RPC_SERVER_NONE
const lpf_rpc_query_t	LPF_RPC_QUERY_NONE
const lpf_err_t	LPF_ERR_RPC_FAILED

Detailed Description

Some aspects are implementation defined. See, e.g., lpf_mpirpc_open.

Typedef Documentation

lpf_rpc_server_t

typedef lpf_init_t lpf_rpc_server_t

Represents an RPC server connection.

A valid instance of this type can be created via a successful call to e.g. lpf_mpirpc_open(). LPF_RPC_SERVER_NONE is an invalid initializer constant for this type. A valid instance is freed (and thus made invalid) by placing a call to e.g. lpf_mpirpc_close_server().

lpf_rpc_query_t

typedef lpf_args_t lpf_rpc_query_t

Represents a query that is to be sent over an RPC server connection.

A valid instance of this type can only be created via a successful call to lpf_rpc_query_create. LPF_RPC_QUERY_NONE is an invalid initializer constant for this type. A valid instance is freed (and thus made invalid) by placing a call to lpf_rpc_query_destroy.

Function Documentation

lpf_mpirpc_open()

lpf_err_t lpf_mpirpc_open	(	const char *const	hostname,
		const char *const	portname,
		const int	timeout,
		lpf_rpc_server_t *const	server
	)

Opens a connection to an RPC server.

Parameters

[in]	hostname	The name of the host to connect to.
[in]	portname	The name of the port to connect to.
[in]	timeout	How long to wait for a successful connection (in ms.)
[out]	server	The open connection to the RPC server.

Returns

LPF_SUCCESS If the connection was opened successfully.

LPF_SUCCESS If hostname or portname was empty, or if timeout was zero. In either of these cases, the call to this function shall have no other effect than returning SUCCESS.

LPF_ERR_OUT_OF_MEMORY In case not enough memory was available to successfully open up a connection.

LPF_ERR_FATAL In case the connection failed. In this case, the LPF enters an undefined state and should no longer be relied on during the remaining life time of this RPC client process.

lpf_mpirpc_close_server()

lpf_err_t lpf_mpirpc_close_server

(

const lpf_rpc_server_t

server

)

Closes an RPC server connection.

Parameters

[in]

server

A valid server connection created using a (successful) call to lpf_mpirpc_open.

Warning

Supplying an invalid connection will yield undefined behaviour.

Returns

LPF_SUCCESS When the connection is successfully closed.

LPF_ERR_FATAL In case closing the connection failed. In this case, the LPF enters an undefined state and should no longer be relied on during the remaining life time of this RPC client process.

lpf_rpc_query_create()

lpf_err_t lpf_rpc_query_create	(	const void *const	payload,
		const size_t	payload_size,
		const size_t	response_size,
		lpf_rpc_query_t *const	query
	)

Takes a user's payload for an RPC server query and reserves room for the server's response.

Parameters

[in]	payload	The query contents.
[in]	payload_size	The size (in bytes) of the query payload.
[in]	response_size	The (maximum) size (in bytes) the server can return in response to the query.
[out]	query	Where to store the resulting query object.

Note

It is allowed for payload to be equal to NULL and payload_size to be equal to zero (as long as the server knows how to interpret such an ‘empty’ request, of course).

Likewise, it is also allowed for response_size to be empty.

Returns

LPF_ERR_OUT_OF_MEMORY If there is not enough memory available to construct query. In this case it will be as though the call to this function has never happened (other than returning this exit code).

LPF_SUCCESS On successful creation of the query.

lpf_rpc_query_destroy()

lpf_err_t lpf_rpc_query_destroy

(

lpf_rpc_query_t

query

)

Releases all resources corresponding to a valid instance of type lpf_rpc_query_t.

Parameters

[in]

query

The query which to destroy. This must be a valid instance of type lpf_rpc_query_t.

On function exit, query shall be invalid.

Returns

LPF_SUCCESS This function always succeeds.

Warning

This function's behaviour is undefined when an invalid query is provided.

lpf_rpc_send_query()

lpf_err_t lpf_rpc_send_query	(	lpf_rpc_query_t	query,
		lpf_rpc_server_t	server,
		void **const	response
	)

Execute the query at the given RPC server.

Parameters

[in]	query	A valid query instance.
[in]	server	A valid server connection.
[out]	response	Where to store a pointer to the memory area which contains the server's response. This memory area will be guaranteed valid until the query is destroyed, overwritten, or subject to a new call to this function.

Warning

Passing an invalid query or connection will result in UB.

Note

After a successful call to this function, the same query remains valid and can thus be re-submitted to the server to obtain new responses. Whether such new responses can differ from each other is application- defined.

Returns

LPF_SUCCESS When the query successfully executed and an answer (if requested) was sent back successfully as well.

LPF_ERR_RPC_FAILED A non-fatal error occurred while communicating with the RPC server or the RPC server returned an error. The response output will not be set. Simply retrying the query is allowed but its effectiveness is application-defined.

LPF_ERR_OUT_OF_MEMORY When the connection or query failed due to out of memory conditions.

LPF_ERR_FATAL In case a fatal error occurred during querying. In this case, the LPF enters an undefined state and should no longer be relied on during the remaining life time of this RPC client process.

Variable Documentation

LPF_RPC_SERVER_NONE

const lpf_rpc_server_t LPF_RPC_SERVER_NONE

extern

An (invalid) initializer instance of lpf_rpc_server_t.

LPF_RPC_QUERY_NONE

const lpf_rpc_query_t LPF_RPC_QUERY_NONE

extern

An (invalid) initializer instance of lpf_rpc_query_t.

LPF_ERR_RPC_FAILED

const lpf_err_t LPF_ERR_RPC_FAILED

extern

Signals a failed RPC called. Retry is possible.