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 processingint mtype; // message typeint len; // length of data in the payload (send or received)unsigned char* payload; // transported dataunsigned char* xaction; // pointer to fixed length transaction id bytesint sub_id; // subscription idint tp_state; // transport state (a.k.a errno)these things are off limits to the user applicationvoid* tp_buf; // underlying transport allocated pointervoid* header; // internal message header (whole buffer: header+payload)unsigned char* id; // if we need an ID in the message separate from the xaction idint flags; // various MFL (private) flags as neededint 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
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!