Common RPC Functions

Common RPC Functions — Generic RPC functions used by various producer components

Synopsis


#include <monitor/producer/rpc_common.h>


#define     PROD_RPC_MODULE_RPC
#define     PROD_RPC_APP_RPC
#define     PROD_RPC_MONITOR_LOCAL
#define     PROD_RPC_MONITOR_MAIN
            prod_rpc_handle;
enum        prod_rpc_state;
enum        prod_rpc_flags;
int         (*prod_rpc_marshal_func)        (mon_buffer *buf,
                                             prod_rpc_op op,
                                             void *args);
int         (*prod_rpc_process_func)        (prod_rpc_handle *rpc,
                                             uint32_t cmd_id,
                                             void *args);
            prod_rpc_cmd_desc;
#define     PROD_RPC_CMD_ENTRY              (cmd, data)
#define     PROD_RPC_CMD_ENTRY_COMMON       (cmd, data)
            prod_rpc_ctx;
enum        prod_rpc_op;
void        (*prod_rpc_cb)                  (prod_rpc_handle *rpc,
                                             const char *service);
enum        prod_rpc_cmd_base;
enum        prod_rpc_cmd;
void        prod_rpc_set_aux                (prod_rpc_handle *rpc,
                                             void *user_data,
                                             GDestroyNotify user_data_done);
#define     PROD_RPC_REPLY
int         prod_rpc_call                   (prod_rpc_handle *rpc,
                                             prod_rpc_cmd cmd,
                                             prod_rpc_marshal_func encode,
                                             void *args,
                                             prod_rpc_marshal_func decode,
                                             void *result);
int         prod_rpc_call_void              (prod_rpc_handle *rpc,
                                             prod_rpc_cmd cmd,
                                             prod_rpc_marshal_func encode,
                                             void *args);
int         prod_rpc_call_void_fd           (prod_rpc_handle *rpc,
                                             prod_rpc_cmd cmd,
                                             prod_rpc_marshal_func encode,
                                             void *args,
                                             int fd);
int         prod_rpc_call_async             (prod_rpc_handle *rpc,
                                             prod_rpc_cmd cmd,
                                             prod_rpc_marshal_func encode,
                                             void *args,
                                             prod_rpc_marshal_func decode,
                                             void *result,
                                             mon_ctx *ctx);
int         prod_rpc_reply                  (prod_rpc_handle *rpc,
                                             uint32_t cmd_id,
                                             prod_rpc_marshal_func encode,
                                             void *reply);
void        prod_rpc_event                  (int fd,
                                             mon_io_events events,
                                             void *ptr);
int         prod_rpc_cmd_shmem              (prod_rpc_handle *rpc,
                                             uint32_t cmd_id,
                                             void *ptr);
void        prod_rpc_flush_shmem            (prod_rpc_handle *rpc);

int         prod_rpc_read                   (prod_rpc_handle *rpc);
uint32_t    prod_rpc_next_id                (prod_rpc_handle *rpc);
int         prod_rpc_check_access           (prod_rpc_handle *rpc,
                                             const char *user,
                                             const char *group);
int         prod_rpc_shmem_config           (mon_cfg_node *cfg);

int         prod_rpc_register               (const char *service,
                                             const prod_rpc_cmd_desc *cmds,
                                             unsigned int num_cmds,
                                             prod_rpc_cb cb);
void        prod_rpc_unregister             (const char *service);
void        prod_rpc_done                   (prod_rpc_handle *rpc);
void        prod_rpc_ref                    (prod_rpc_handle *rpc);
void        prod_rpc_close                  (prod_rpc_handle *rpc);

#define     PROD_RPC_GRIDLOG_RPC
#define     PROD_GRIDLOG_MAX
enum        prod_gridlog_level;

Description

Details

PROD_RPC_MODULE_RPC

#define PROD_RPC_MODULE_RPC	"Module RPC"

The service name string for the module RPC handler.

PROD_RPC_APP_RPC

#define PROD_RPC_APP_RPC	"Application RPC"

The service name string for the application RPC handler.

PROD_RPC_MONITOR_LOCAL

#define PROD_RPC_MONITOR_LOCAL	"lm"

The base name of the local monitor configuration file.

PROD_RPC_MONITOR_MAIN

#define PROD_RPC_MONITOR_MAIN	"mm"

The base name of the main monitor configuration file.

prod_rpc_handle

typedef struct {
	/* Connection ID for logging and debugging */
	unsigned int		id;

	prod_rpc_state		state;
	prod_rpc_flags		flags;
	int			fd;
	mon_buffer		rbuf;
	mon_buffer		wbuf;

	int			recv_fd;

	const prod_rpc_cmd_desc	*cmds;
	unsigned int		num_cmds;

	uint32_t		idgen;
	int			refcnt;
	GList			*pending_cmds;

	mon_shm_desc		*shmem;
	size_t			last_wakeup_offset;
	unsigned int		msgs_processed;

	mon_ipc_creds		creds;

	void			*user_data;
	GDestroyNotify		user_data_done;
} prod_rpc_handle;

Defines the structure used for RPC calls.

unsigned int `id`;	numerical id used for logging.
prod_rpc_state `state`;	the state of the RPC connection (see prod_rpc_state).
prod_rpc_flags `flags`;	flags for the RPC connection (see prod_rpc_flags).
int `fd`;	the file descriptor used for communication.
mon_buffer `rbuf`;	the receive buffer.
mon_buffer `wbuf`;	the send buffer.
int `recv_fd`;	holds the last received file descriptor.
const prod_rpc_cmd_desc *`cmds`;	a table of prod_rpc_cmd_desc entries describing the RPC commands that may be received from the peer.
unsigned int `num_cmds`;	number of elements in the `cmds` table.
uint32_t `idgen`;	the next command ID.
int `refcnt`;	reference count.
GList *`pending_cmds`;	list of commands that have not been completed yet.
mon_shm_desc *`shmem`;	pointer to the shared memory segment to use for `RPC_CMD_DATA` messages.
size_t `last_wakeup_offset`;	value of the shared ringbuffer's head offset when the last wakeup message was sent to the peer.
unsigned int `msgs_processed`;	number of RPC_CMD_DATA messages sent through this RPC connection.
mon_ipc_creds `creds`;	peer credentials.
void *`user_data`;	user-supplied auxiliary data.
GDestroyNotify `user_data_done`;	function that is called when `user_data` is no longer needed.

enum prod_rpc_state

typedef enum {
	/* There is no open communication socket */
	PROD_RPC_STATE_CLOSED,
	/* After connect, before GO */
	PROD_RPC_STATE_HANDSHAKE,
	/* Aftet GO */
	PROD_RPC_STATE_READY
} prod_rpc_state;

The state of an RPC connection.

`PROD_RPC_STATE_CLOSED`	the connection is closed.
`PROD_RPC_STATE_HANDSHAKE`	initial handshake in progress.
`PROD_RPC_STATE_READY`	the connection is ready for sending commands.

enum prod_rpc_flags

typedef enum {
	/* Do writes synchronously */
	PROD_RPC_F_SYNC		= (1 << 0),
	/* Shmem parsing is scheduled */
	PROD_RPC_F_SHMEM	= (1 << 1),
	/* Inside shmem parsing */
	PROD_RPC_F_SHMEM_PARSE	= (1 << 2)
} prod_rpc_flags;

Flags for an RPC connection.

`PROD_RPC_F_SYNC`	perform all writes synchronously
`PROD_RPC_F_SHMEM`	set if shared memory processing is scheduled
`PROD_RPC_F_SHMEM_PARSE`	flag used internally to prevent infinite recursion

prod_rpc_marshal_func ()

int         (*prod_rpc_marshal_func)        (mon_buffer *buf,
                                             prod_rpc_op op,
                                             void *args);

Prototype for an RPC command encoding/decoding function.

`buf` :	the source/destination buffer.
`op` :	the requested operation (see prod_rpc_op).
`args` :	the in/out arguments.
Returns :	0 if successful or an error code.

prod_rpc_process_func ()

int         (*prod_rpc_process_func)        (prod_rpc_handle *rpc,
                                             uint32_t cmd_id,
                                             void *args);

Prototype for RPC function handlers.

`rpc` :	a prod_rpc_handle.
`cmd_id` :	the command's sequence id.
`args` :	pointer to the decoded argument structure.
Returns :	0 if successful or an error code. If an error is returned, the RPC connection is closed.

prod_rpc_cmd_desc

typedef struct {
	uint32_t		cmd;
	unsigned int		argsize;
	prod_rpc_marshal_func	marshal;
	prod_rpc_process_func	process;
	const char		*name;
} prod_rpc_cmd_desc;

Descriptor for RPC commands that may be received on a connection.

uint32_t `cmd`;	a prod_rpc_cmd.
unsigned int `argsize`;	size needed to hold the decoded arguments. If 0, the command takes no arguments.
prod_rpc_marshal_func `marshal`;	marshal funcion for decoding the arguments.
prod_rpc_process_func `process`;	function that performs the command.
const char *`name`;	the name of the command to print in debugging messages.

PROD_RPC_CMD_ENTRY()

#define     PROD_RPC_CMD_ENTRY(cmd, data)

Convenience macro to populate a prod_rpc_cmd_desc table. It assumes local naming for the process function.

`cmd` :	the RPC command code, without the PROD_RPC_ prefix
`data` :	identifier used when generating the name of the argument structure, the name of the marshal function and the name of the process function. Normally the same as `cmd` but all lowercase.

PROD_RPC_CMD_ENTRY_COMMON()

#define     PROD_RPC_CMD_ENTRY_COMMON(cmd, data)

Convenience macro to populate a prod_rpc_cmd_desc table. It assumes global naming for the process function.

`cmd` :	the RPC command code, without the PROD_RPC_ prefix
`data` :	identifier used when generating the name of the argument structure, the name of the marshal function and the name of the process function. Normally the same as `cmd` but all lowercase.

prod_rpc_ctx

typedef struct {
	prod_rpc_handle		*rpc;
	prod_rpc_cmd		cmd;
	uint32_t		id;
	prod_rpc_marshal_func	decode;
	void			*result;
	mon_ctx			*ctx;
} prod_rpc_ctx;

Structure holding state information for RPC commands executing asynchronously.

prod_rpc_handle *`rpc`;	the prod_rpc_handle the command is executing on.
prod_rpc_cmd `cmd`;	the command's code.
uint32_t `id`;	the command's sequence number.
prod_rpc_marshal_func `decode`;	function to decode the command's result.
void *`result`;	pointer where to store the decoded result.
mon_ctx *`ctx`;	a mon_ctx execution context.

enum prod_rpc_op

typedef enum {
	PROD_RPC_ENCODE,
	PROD_RPC_DECODE,
	PROD_RPC_DESTROY
} prod_rpc_op;

Encoding/decoding operation to perform.

`PROD_RPC_ENCODE`	encode the arguments of an RPC command.
`PROD_RPC_DECODE`	decode the arguments of an RPC command.
`PROD_RPC_DESTROY`	free the arguments of an RPC command.

prod_rpc_cb ()

void        (*prod_rpc_cb)                  (prod_rpc_handle *rpc,
                                             const char *service);

Prototype for a function to be called when a new RPC connection is established.

`rpc` :	the newly created prod_rpc_handle.
`service` :	the name of the service this handle belongs to. This is the same name that was given to `prod_rpc_register()`.

enum prod_rpc_cmd_base

typedef enum {
	PROD_RPC_BASE_GENERIC	= 0,
	PROD_RPC_BASE_CORE	= 1000,
	PROD_RPC_BASE_MODULE	= 2000
} prod_rpc_cmd_base;

Constants describing the ranges of different RPC command categories.

`PROD_RPC_BASE_GENERIC`	commands defined in public producer headers.
`PROD_RPC_BASE_CORE`	commands used internally by the producer.
`PROD_RPC_BASE_MODULE`	commands used by individual modules. Different modules may use the same numeric command code for different purposes.

enum prod_rpc_cmd

typedef enum {
	/* Sensor, actuator, application: no operation (wake-up event) */
	PROD_RPC_CMD_NOP = PROD_RPC_BASE_GENERIC,
	/* Sensor & actuator: connect to the producer */
	PROD_RPC_CMD_CONNECT,
	/* Sensor, actuator, application: request shared memory segment */
	PROD_RPC_CMD_SHMEM,
	/* Sensor, actuator, application: flush the shared memory buffer */
	PROD_RPC_CMD_FLUSH,
	/* Producer: command status */
	PROD_RPC_CMD_STATUS
} prod_rpc_cmd;

Generic RPC commands.

`PROD_RPC_CMD_NOP`	no operation (but wake up the other end).
`PROD_RPC_CMD_CONNECT`	command to connect to a receiver module inside the producer.
`PROD_RPC_CMD_SHMEM`	request for negotiating a shared memory area.
`PROD_RPC_CMD_FLUSH`	flush the contents of the shared memory area.
`PROD_RPC_CMD_STATUS`	send the result of the last command.

prod_rpc_set_aux ()

void        prod_rpc_set_aux                (prod_rpc_handle *rpc,
                                             void *user_data,
                                             GDestroyNotify user_data_done);

Sets the auxiliary data associated with a prod_rpc_handle.

`rpc` :	a prod_rpc_handle.
`user_data` :	the auxiliary data pointer.
`user_data_done` :	function to call when the auxiliary data is no longer needed. This function should deallocate resources allocated to the auxiliary data if needed.

PROD_RPC_REPLY

#define PROD_RPC_REPLY		0x80000000

If this bit is set in an rpc command id code, this is a reply packet, not a command.

prod_rpc_call ()

int         prod_rpc_call                   (prod_rpc_handle *rpc,
                                             prod_rpc_cmd cmd,
                                             prod_rpc_marshal_func encode,
                                             void *args,
                                             prod_rpc_marshal_func decode,
                                             void *result);

Performs an RPC call and wait for its result.

`rpc` :	a prod_rpc_handle.
`cmd` :	the remote function code to call.
`encode` :	function to encode the arguments of the remote function.
`args` :	the arguments of the remote function.
`decode` :	function to decode the result of the remote function.
`result` :	where to store the result of the remote function.
Returns :	0 if successful or an error code.

prod_rpc_call_void ()

int         prod_rpc_call_void              (prod_rpc_handle *rpc,
                                             prod_rpc_cmd cmd,
                                             prod_rpc_marshal_func encode,
                                             void *args);

Performs an RPC call that returns no value.

`rpc` :	a prod_rpc_handle.
`cmd` :	the remote function code to call.
`encode` :	function to encode the arguments of the remote function.
`args` :	the arguments of the remote function.
Returns :	0 if successful or an error code.

prod_rpc_call_void_fd ()

int         prod_rpc_call_void_fd           (prod_rpc_handle *rpc,
                                             prod_rpc_cmd cmd,
                                             prod_rpc_marshal_func encode,
                                             void *args,
                                             int fd);

Performs an RPC call that returns no value, and passes a file descriptor along with the normal arguments of the call.

`rpc` :	a prod_rpc_handle.
`cmd` :	the remote function code to call.
`encode` :	function to encode the arguments of the remote function.
`args` :	the arguments of the remote function.
`fd` :	the file descriptor to pass to the remote function.
Returns :	0 if successful or an error code.

prod_rpc_call_async ()

int         prod_rpc_call_async             (prod_rpc_handle *rpc,
                                             prod_rpc_cmd cmd,
                                             prod_rpc_marshal_func encode,
                                             void *args,
                                             prod_rpc_marshal_func decode,
                                             void *result,
                                             mon_ctx *ctx);

Performs an asynchronous RPC call.

`rpc` :	a prod_rpc_handle.
`cmd` :	the remote function code to call.
`encode` :	function to encode the arguments of the remote function.
`args` :	the arguments of the remote function.
`decode` :	function to decode the result of the remote function.
`result` :	where to store the result of the remote function.
`ctx` :	a mon_ctx to be resumed when the command completes.
Returns :	0 if successful or an error code.

prod_rpc_reply ()

int         prod_rpc_reply                  (prod_rpc_handle *rpc,
                                             uint32_t cmd_id,
                                             prod_rpc_marshal_func encode,
                                             void *reply);

Sends a reply to an RPC command.

`rpc` :	a prod_rpc_handle.
`cmd_id` :	the command's sequence ID.
`encode` :	function to encode the reply.
`reply` :	the result value.
Returns :	0 or an error code.

prod_rpc_event ()

void        prod_rpc_event                  (int fd,
                                             mon_io_events events,
                                             void *ptr);

Handles I/O events for an RPC connection. This function can be installed as an I/O callback with mon_io_set_cb().

`fd` :	the file descriptor where the event occured.
`events` :	the events that occured.
`ptr` :	a prod_rpc_handle.

prod_rpc_cmd_shmem ()

int         prod_rpc_cmd_shmem              (prod_rpc_handle *rpc,
                                             uint32_t cmd_id,
                                             void *ptr);

Handles the PROD_RPC_CMD_SHMEM command. This function creates a new shared memory segment, and attaches it to rpc->shmem. After the peer has recevied the reply for the command, it will use this shared memory segment for sending PROD_RPC_CMD_DATA messages.

`rpc` :	a prod_rpc handle.
`cmd_id` :	the command's sequence ID.
`ptr` :	pointer to the RPC command arguments.
Returns :	0 if successful or an error code.

prod_rpc_flush_shmem ()

void        prod_rpc_flush_shmem            (prod_rpc_handle *rpc);

Flushes the contents of the shared memory ringbuffer. May be used on both the client and server side.

rpc : a prod_rpc handle.

prod_rpc_read ()

int         prod_rpc_read                   (prod_rpc_handle *rpc);

Reads and processes some data from a prod_rpc_handle. This function does a low-level read only once per invocation.

`rpc` :	a prod_rpc_handle.
Returns :	0 if successful or an error code.

prod_rpc_next_id ()

uint32_t    prod_rpc_next_id                (prod_rpc_handle *rpc);

Returns the next command id for an RPC connection.

`rpc` :	a prod_rpc_handle.
Returns :	the next command id.

prod_rpc_check_access ()

int         prod_rpc_check_access           (prod_rpc_handle *rpc,
                                             const char *user,
                                             const char *group);

Checks if an RPC connection should be accepted or not.

`rpc` :	a prod_rpc_handle.
`user` :	the required peer user. If it is `NULL`, the peer must have the same user id the monitoring system is running as.
`group` :	the required peer group. If it is `NULL`, the peer must have the same group id the monitoring system is running as.
Returns :	0 if the connection is authorized, `MON_ERR_AUTH_ERR` otherwise.

prod_rpc_shmem_config ()

int         prod_rpc_shmem_config           (mon_cfg_node *cfg);

Configures shared memory parameters that will be used by the RPC core.

`cfg` :	the mon_cfg_node section that contains the configuration.
Returns :	0 if successful or an error code.

prod_rpc_register ()

int         prod_rpc_register               (const char *service,
                                             const prod_rpc_cmd_desc *cmds,
                                             unsigned int num_cmds,
                                             prod_rpc_cb cb);

Registers an RPC service handler.

`service` :	the name of the service.
`cmds` :	the prod_rpc_cmd_desc table to use for accepted connections
`num_cmds` :	the length of the `cmds` table
`cb` :	callback function for new connections.
Returns :	0 if successful or an error code.

prod_rpc_unregister ()

void        prod_rpc_unregister             (const char *service);

Unregisters an RPC service handler.

service : the name of the service.

prod_rpc_done ()

void        prod_rpc_done                   (prod_rpc_handle *rpc);

Decrements the reference count of a prod_rpc_handle. If the reference count reaches zero, the RPC connection is destroyed.

rpc : a prod_rpc_handle.

prod_rpc_ref ()

void        prod_rpc_ref                    (prod_rpc_handle *rpc);

Increments the reference count of a prod_rpc_handle.

rpc : a prod_rpc_handle.

prod_rpc_close ()

void        prod_rpc_close                  (prod_rpc_handle *rpc);

Closes an RPC connection.

rpc : a prod_rpc_handle.

PROD_RPC_GRIDLOG_RPC

#define PROD_RPC_GRIDLOG_RPC	"Gridlog RPC"

The service name string for the logging service RPC handler.

PROD_GRIDLOG_MAX

#define PROD_GRIDLOG_MAX	PROD_GRIDLOG_CRITICAL

Max. severity level used by the logging service.

enum prod_gridlog_level

typedef enum {
	PROD_GRIDLOG_DEBUG,
	PROD_GRIDLOG_INFO,
	PROD_GRIDLOG_NOTICE,
	PROD_GRIDLOG_WARNING,
	PROD_GRIDLOG_ERROR,
	PROD_GRIDLOG_CRITICAL
} prod_gridlog_level;

Severity levels used by the logging service.

`PROD_GRIDLOG_DEBUG`	debugging information that is meaningful only if an error condition is suspected.
`PROD_GRIDLOG_INFO`	informational message that is generally not important during normal operation.
`PROD_GRIDLOG_NOTICE`	significant information that might be important during normal operation.
`PROD_GRIDLOG_WARNING`	warning message: an unusual condition occurred, but the service could recover.
`PROD_GRIDLOG_ERROR`	error message: some operation failed, but the service in general is still usable.
`PROD_GRIDLOG_CRITICAL`	critical condition affecting the general usability of the service.