RMR Python Bindings

Overview

The xapp python framework package includes a python subpackage called rmr. This subpackage (ricxappframe.rmr) is a CTYPES wrapper around the RMR shared library. Most Xapp users will never use this subpackage natively; however python apps that need access to the low-level RMR API can use it.

Usage of this python package requires that the RMR shared-object library is installed in a system library that is included in the directories found by default, usually something like /usr/local/lib.

The RMR library man pages are available here: RMR Man Pages

RMR API

Wraps all RMR functions, but does not have a reference to the shared library.

ricxappframe.rmr.rmr.RMR_MAX_RCV_BYTES = None

Typical size message to receive; size is not limited

ricxappframe.rmr.rmr.RMRFL_MTCALL = None

Multi-threaded initialization flag

ricxappframe.rmr.rmr.RMRFL_NONE = None

Empty flag

ricxappframe.rmr.rmr.RMR_OK = None

State constant for OK

ricxappframe.rmr.rmr.RMR_ERR_NOENDPT = None

State constant for no endpoint based on msg type

ricxappframe.rmr.rmr.RMR_ERR_RETRY = None

State constant for retry

ricxappframe.rmr.rmr.RMR_ERR_TIMEOUT = None

State constant for timeout

class ricxappframe.rmr.rmr.rmr_mbuf_t[source]

Mirrors public members of type rmr_mbuf_t from RMR header file src/common/include/rmr.h

typedef struct {
int state; // state of processing
int mtype; // message type
int len; // length of data in the payload (send or received)
unsigned char* payload; // transported data
unsigned char* xaction; // pointer to fixed length transaction id bytes
int sub_id; // subscription id
int tp_state; // transport state (a.k.a errno)

these things are off limits to the user application

void* tp_buf; // underlying transport allocated pointer
void* header; // internal message header (whole buffer: header+payload)
unsigned char* id; // if we need an ID in the message separate from the xaction id
int flags; // various MFL (private) flags as needed
int alloc_len; // the length of the allocated space (hdr+payload)
} rmr_mbuf_t;
RE PAYLOADs type below, see the documentation for c_char_p:
class ctypes.c_char_p
Represents the C char * datatype when it points to a zero-terminated string. For a general character pointer that may also point to binary data, POINTER(c_char) must be used. The constructor accepts an integer address, or a bytes object.
ricxappframe.rmr.rmr.rmr_init(uproto_port: ctypes.c_char_p, max_msg_size: int, flags: int) → ctypes.c_void_p[source]

Prepares the environment for sending and receiving messages. Refer to RMR C documentation for method:

extern void* rmr_init(char* uproto_port, int max_msg_size, int flags)

This function raises an exception if the returned context is None.

Parameters:
uproto_port: c_char_p

Pointer to bytes built from the port number as a string; e.g., b‘4550’

max_msg_size: integer

Maximum message size to receive

flags: integer

RMR option flags

Returns:
c_void_p:

Pointer to RMR context

ricxappframe.rmr.rmr.rmr_ready(vctx: ctypes.c_void_p) → int[source]

Checks if a routing table has been received and installed. Refer to RMR C documentation for method:

extern int rmr_ready(void* vctx)
Parameters:
vctx: ctypes c_void_p

Pointer to RMR context

Returns:
1 for yes, 0 for no
ricxappframe.rmr.rmr.rmr_close(vctx: ctypes.c_void_p)[source]

Closes the listen socket. Refer to RMR C documentation for method:

extern void rmr_close(void* vctx)
Parameters:
vctx: ctypes c_void_p

Pointer to RMR context

Returns:
None
ricxappframe.rmr.rmr.rmr_set_stimeout(vctx: ctypes.c_void_p, rloops: int) → int[source]

Sets the configuration for how RMR will retry message send operations. Refer to RMR C documentation for method:

extern int rmr_set_stimeout(void* vctx, int rloops)
Parameters:
vctx: ctypes c_void_p

Pointer to RMR context

rloops: int

Number of retry loops

Returns:
0 on success, -1 on failure
ricxappframe.rmr.rmr.rmr_alloc_msg(vctx: ctypes.c_void_p, size: int, payload=None, gen_transaction_id=False, mtype=None, meid=None, sub_id=None, fixed_transaction_id=None)[source]

Allocates and returns a buffer to write and send through the RMR library. Refer to RMR C documentation for method:

extern rmr_mbuf_t* rmr_alloc_msg(void* vctx, int size)

Optionally populates the message from the remaining arguments.

TODO: on next API break, clean up transaction_id ugliness. Kept for now to preserve API.

Parameters:
vctx: ctypes c_void_p

Pointer to RMR context

size: int

How much space to allocate

payload: bytes

if not None, attempts to set the payload

gen_transaction_id: bool

if True, generates and sets a transaction ID. Note, option fixed_transaction_id overrides this option

mtype: bytes

if not None, sets the sbuf’s message type

meid: bytes

if not None, sets the sbuf’s meid

sub_id: bytes

if not None, sets the sbuf’s subscription id

fixed_transaction_id: bytes

if not None, used as the transaction ID. Note, this overrides the option gen_transaction_id

Returns:
c_void_p:

Pointer to rmr_mbuf structure

ricxappframe.rmr.rmr.rmr_realloc_payload(ptr_mbuf: ctypes.c_void_p, new_len: int, copy=False, clone=False)[source]

Allocates and returns a message buffer large enough for the new length. Refer to RMR C documentation for method:

extern rmr_mbuf_t* rmr_realloc_payload(rmr_mbuf_t*, int, int, int)
Parameters:
ptr_mbuf: c_void_p

Pointer to rmr_mbuf structure

new_len: int

Length

copy: bool

Whether to copy the original paylod

clone: bool

Whether to clone the original buffer

Returns:
c_void_p:

Pointer to rmr_mbuf structure

ricxappframe.rmr.rmr.rmr_free_msg(ptr_mbuf: ctypes.c_void_p)[source]

Releases the message buffer. Refer to RMR C documentation for method:

extern void rmr_free_msg(rmr_mbuf_t* mbuf )
Parameters:
ptr_mbuf: c_void_p

Pointer to rmr_mbuf structure

Returns:
None
ricxappframe.rmr.rmr.rmr_payload_size(ptr_mbuf: ctypes.c_void_p) → int[source]

Gets the number of bytes available in the payload. Refer to RMR C documentation for method:

extern int rmr_payload_size(rmr_mbuf_t* mbuf)
Parameters:
ptr_mbuf: c_void_p

Pointer to rmr_mbuf structure

Returns:
int:

Number of bytes available

ricxappframe.rmr.rmr.rmr_send_msg(vctx: ctypes.c_void_p, ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t) → ricxappframe.rmr.rmr.LP_rmr_mbuf_t[source]

Sends the message according to the routing table and returns an empty buffer. Refer to RMR C documentation for method:

extern rmr_mbuf_t* rmr_send_msg(void* vctx, rmr_mbuf_t* mbuf)
Parameters:
vctx: ctypes c_void_p

Pointer to RMR context

ptr_mbuf: c_void_p

Pointer to rmr_mbuf structure

Returns:
ctypes c_void_p:

Pointer to rmr_mbuf structure

ricxappframe.rmr.rmr.rmr_rcv_msg(vctx: ctypes.c_void_p, ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t) → ricxappframe.rmr.rmr.LP_rmr_mbuf_t[source]

Waits for a message to arrive, and returns it. Refer to RMR C documentation for method:

extern rmr_mbuf_t* rmr_rcv_msg(void* vctx, rmr_mbuf_t* old_mbuf)
Parameters:
vctx: ctypes c_void_p

Pointer to RMR context

ptr_mbuf: c_void_p

Pointer to rmr_mbuf structure

Returns:
ctypes c_void_p:

Pointer to rmr_mbuf structure

ricxappframe.rmr.rmr.rmr_torcv_msg(vctx: ctypes.c_void_p, ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t, ms_to: int) → ricxappframe.rmr.rmr.LP_rmr_mbuf_t[source]

Waits up to the timeout value for a message to arrive, and returns it. Refer to RMR C documentation for method:

extern rmr_mbuf_t* rmr_torcv_msg(void* vctx, rmr_mbuf_t* old_mbuf, int ms_to)
Parameters:
vctx: ctypes c_void_p

Pointer to RMR context

ptr_mbuf: c_void_p

Pointer to rmr_mbuf structure

ms_to: int

Time out value in milliseconds

Returns:
ctypes c_void_p:

Pointer to rmr_mbuf structure

ricxappframe.rmr.rmr.rmr_rts_msg(vctx: ctypes.c_void_p, ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t, payload=None, mtype=None) → ricxappframe.rmr.rmr.LP_rmr_mbuf_t[source]

Sends a message to the originating endpoint and returns an empty buffer. Refer to RMR C documentation for method:

extern rmr_mbuf_t* rmr_rts_msg(void* vctx, rmr_mbuf_t* mbuf)
additional features beyond c-rmr:
if payload is not None, attempts to set the payload if mtype is not None, sets the sbuf’s message type
Parameters:
vctx: ctypes c_void_p

Pointer to an RMR context

ptr_mbuf: ctypes c_void_p

Pointer to an RMR message buffer

payload: bytes

Payload

mtype: bytes

Message type

Returns:
ctypes c_void_p:

Pointer to rmr_mbuf structure

ricxappframe.rmr.rmr.rmr_call(vctx: ctypes.c_void_p, ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t) → ricxappframe.rmr.rmr.LP_rmr_mbuf_t[source]

Sends a message, waits for a response and returns it. Refer to RMR C documentation for method:

extern rmr_mbuf_t* rmr_call(void* vctx, rmr_mbuf_t* mbuf)
Parameters:
ptr_mbuf: ctypes c_void_p

Pointer to an RMR message buffer

Returns:
ctypes c_void_p:

Pointer to rmr_mbuf structure

ricxappframe.rmr.rmr.rmr_set_meid(ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t, byte_str: bytes) → int[source]

Sets the managed entity field in the message and returns the number of bytes copied. Refer to RMR C documentation for method:

extern int rmr_bytes2meid(rmr_mbuf_t* mbuf, unsigned char const* src, int len);

Caution: the meid length supported in an RMR message is 32 bytes, but C applications expect this to be a nil terminated string and thus only 31 bytes are actually available.

Raises: exceptions.MeidSizeOutOfRang

Parameters:
ptr_mbuf: ctypes c_void_p

Pointer to rmr_mbuf structure

byte_tr: bytes

Managed entity ID value

Returns:
int:

number of bytes copied

ricxappframe.rmr.rmr.rmr_get_meid(ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t) → bytes[source]

Gets the managed entity ID (meid) from the message header. This is a python-friendly version of RMR C method:

extern unsigned char* rmr_get_meid(rmr_mbuf_t* mbuf, unsigned char* dest);
Parameters:
ptr_mbuf: ctypes c_void_p

Pointer to rmr_mbuf structure

Returns:
bytes:

Managed entity ID

ricxappframe.rmr.rmr.rmr_get_src(ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t, dest: ctypes.c_char_p) → ctypes.c_char_p[source]

Copies the message-source information to the buffer. Refer to RMR C documentation for method:

extern unsigned char* rmr_get_src(rmr_mbuf_t* mbuf, unsigned char* dest);
Parameters:
ptr_mbuf: ctypes POINTER(rmr_mbuf_t)

Pointer to rmr_mbuf structure

dest: ctypes c_char_p

Pointer to a buffer to receive the message source

Returns:
string:

message-source information

ricxappframe.rmr.rmr.rmr_set_vlevel(new_level: ctypes.c_int)[source]

Sets the verbosity level which determines the messages RMR writes to standard error. Refer to RMR C documentation for method:

void rmr_set_vlevel( int new_level )
Parameters:
new_level: int

New logging verbosity level, an integer in the range 0 (none) to 5 (debug).

ricxappframe.rmr.rmr.rmr_wh_call(vctx: ctypes.c_void_p, whid: ctypes.c_int, ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t, call_id: ctypes.c_int, max_wait: ctypes.c_int) → ricxappframe.rmr.rmr.LP_rmr_mbuf_t[source]

Sends a message buffer (msg) using a wormhole ID (whid) and waits for a response. Refer to RMR C documentation for method:

rmr_mbuf_t* rmr_wh_call( void* vctx, rmr_whid_t whid, rmr_mbuf_t* mbuf, int call_id, int max_wait )
Parameters:
vctx: ctypes c_void_p

Pointer to RMR context

whid: c_int

Wormhole ID returned by rmr_wh_open

ptr_mbuf: ctypes POINTER(rmr_mbuf_t)

Pointer to rmr_mbuf structure

call_id: c_int

number in the range of 2..255 to identify the caller

max_wait: c_int

number of milliseconds to wait for a reply

Returns:
ctypes c_void_p:

Pointer to rmr_mbuf structure

ricxappframe.rmr.rmr.rmr_wh_close(vctx: ctypes.c_void_p, whid: ctypes.c_int)[source]

Closes the wormhole associated with the wormhole id. Refer to RMR C documentation for method:

void rmr_close( void* vctx, rmr_whid_t whid )
Parameters:
vctx: ctypes c_void_p

Pointer to RMR context

whid: c_int

Wormhole ID returned by rmr_wh_open

ricxappframe.rmr.rmr.rmr_wh_open(vctx: ctypes.c_void_p, target: ctypes.c_char_p) → ctypes.c_int[source]

Creates a direct link for sending to another RMR based process. Refer to RMR C documentation for method:

rmr_whid_t rmr_wh_open( void* vctx, char* target )
Parameters:
vctx: ctypes c_void_p

Pointer to RMR context

target: str

name/IP and port combination of the target process; e.g., “localhost:6123”

Returns:
c_int:

Wormhole ID

ricxappframe.rmr.rmr.rmr_wh_send_msg(vctx: ctypes.c_void_p, whid: ctypes.c_int, ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t) → ricxappframe.rmr.rmr.LP_rmr_mbuf_t[source]

Sends a message buffer (msg) using a wormhole ID (whid). Refer to RMR C documentation for method:

rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg )
Parameters:
vctx: ctypes c_void_p

Pointer to RMR context

whid: c_int

Wormhole ID returned by rmr_wh_open

ptr_mbuf: ctypes POINTER(rmr_mbuf_t)

Pointer to rmr_mbuf structure

Returns:
ctypes POINTER(rmr_mbuf_t):

Pointer to rmr_mbuf structure

ricxappframe.rmr.rmr.rmr_wh_state(vctx: ctypes.c_void_p, whid: ctypes.c_int) → ctypes.c_int[source]

Gets the state of the connection associated with the given wormhole (whid). Refer to RMR C documentation for method:

int rmr_wh_state( void* vctx, rmr_whid_t whid )
Parameters:
vctx: ctypes c_void_p

Pointer to RMR context

whid: c_int

Wormhole ID returned by rmr_wh_open

Returns:
c_int:

State of the connection

ricxappframe.rmr.rmr.get_payload(ptr_mbuf: ctypes.c_void_p) → bytes[source]

Gets the binary payload from the rmr_buf_t*.

Parameters:
ptr_mbuf: ctypes c_void_p

Pointer to an rmr message buffer

Returns:
bytes:

the message payload

ricxappframe.rmr.rmr.get_xaction(ptr_mbuf: ctypes.c_void_p) → bytes[source]

Gets the transaction ID from the rmr_buf_t*.

Parameters:
ptr_mbuf: ctypes c_void_p

Pointer to an rmr message buffer

Returns:
bytes:

the transaction id

ricxappframe.rmr.rmr.message_summary(ptr_mbuf: ctypes.c_void_p) → dict[source]

Builds a dict with the contents of an RMR message.

Parameters:
ptr_mbuf: ctypes c_void_p

Pointer to an RMR message buffer

Returns:
dict:

Message content as key-value pairs; keys are defined as RMR_MS_* constants.

ricxappframe.rmr.rmr.set_payload_and_length(byte_str: bytes, ptr_mbuf: ctypes.c_void_p)[source]

Sets an rmr payload and content length.

Parameters:
byte_str: bytes

the bytes to set the payload to

ptr_mbuf: ctypes c_void_p

Pointer to an rmr message buffer

Returns:
None
ricxappframe.rmr.rmr.generate_and_set_transaction_id(ptr_mbuf: ctypes.c_void_p)[source]

Generates a UUID and sets the RMR transaction id to it

Parameters:
ptr_mbuf: ctypes c_void_p

Pointer to an rmr message buffer

ricxappframe.rmr.rmr.set_transaction_id(ptr_mbuf: ctypes.c_void_p, tid_bytes: bytes)[source]

Sets an RMR transaction id TODO: on next API break, merge these two functions. Not done now to preserve API.

Parameters:
ptr_mbuf: ctypes c_void_p

Pointer to an rmr message buffer

tid_bytes: bytes

bytes of the desired transaction id

ricxappframe.rmr.rmr.get_src(ptr_mbuf: ctypes.c_void_p) → str[source]

Gets the message source (likely host:port)

Parameters:
ptr_mbuf: ctypes c_void_p

Pointer to an rmr message buffer

Returns:
string:

message source

RMR Helper API

ricxappframe.rmr.helpers.rmr_rcvall_msgs(mrc, pass_filter=None, timeout=0)[source]

Assembles an array of all messages which can be received without blocking (but see the timeout parameter). Effectively drains the message queue if RMR is started in mt-call mode, or draining any waiting TCP buffers. If the pass_filter parameter is supplied, it is treated as one or more message types to accept (pass through). Using the default, an empty list, results in capturing all messages. If the timeout parameter is supplied and is not zero, this call may block up to that number of milliseconds waiting for a message to arrive. Using the default, zero, results in non-blocking no-wait behavior.

Parameters:
mrc: ctypes c_void_p

Pointer to the RMR context

pass_filter: list (optional)

The message type(s) to capture.

timeout: int (optional)

The number of milliseconds to wait for a message to arrive.

Returns:
List of message summaries (dict), one for each message received; may be empty.
ricxappframe.rmr.helpers.rmr_rcvall_msgs_raw(mrc, pass_filter=None, timeout=0)[source]

Same as rmr_rcvall_msgs, but answers tuples with the raw sbuf. Useful if return-to-sender (rts) functions are required.

Parameters:
mrc: ctypes c_void_p

Pointer to the RMR context

pass_filter: list (optional)

The message type(s) to capture.

timeout: int (optional)

The number of milliseconds to wait for a message to arrive.

Returns:
list of tuple:

List of tuples [(S, sbuf),…] where S is a message summary (dict), and sbuf is the raw message; may be empty. The caller MUST call rmr.rmr_free_msg(sbuf) when finished with each sbuf to prevent memory leaks!