1 # ==================================================================================
2 # Copyright (c) 2019 Nokia
3 # Copyright (c) 2018-2019 AT&T Intellectual Property.
5 # Licensed under the Apache License, Version 2.0 (the "License");
6 # you may not use this file except in compliance with the License.
7 # You may obtain a copy of the License at
9 # http://www.apache.org/licenses/LICENSE-2.0
11 # Unless required by applicable law or agreed to in writing, software
12 # distributed under the License is distributed on an "AS IS" BASIS,
13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 # See the License for the specific language governing permissions and
15 # limitations under the License.
16 # ==================================================================================
18 # Mnemonic: helpers.py
19 # Abstract: This is a collection of extensions to the RMR base package
20 # which are likely to be convenient for Python programs.
22 from ricxappframe.rmr import rmr
25 def rmr_rcvall_msgs(mrc, pass_filter=None, timeout=0):
27 Assembles an array of all messages which can be received without blocking
28 (but see the timeout parameter). Effectively drains the message queue if
29 RMR is started in mt-call mode, or draining any waiting TCP buffers. If
30 the pass_filter parameter is supplied, it is treated as one or more
31 message types to accept (pass through). Using the default, an empty list,
32 results in capturing all messages. If the timeout parameter is supplied
33 and is not zero, this call may block up to that number of milliseconds
34 waiting for a message to arrive. Using the default, zero, results in
35 non-blocking no-wait behavior.
40 Pointer to the RMR context
42 pass_filter: list (optional)
43 The message type(s) to capture.
45 timeout: int (optional)
46 The number of milliseconds to wait for a message to arrive.
50 List of message summaries (dict), one for each message received; may be empty.
54 mbuf = rmr.rmr_alloc_msg(mrc, 4096) # allocate and reuse a single buffer for RMR
57 mbuf = rmr.rmr_torcv_msg(mrc, mbuf, timeout) # first call may have non-zero timeout
58 timeout = 0 # reset so subsequent calls do not wait
59 summary = rmr.message_summary(mbuf)
60 if summary[rmr.RMR_MS_MSG_STATUS] != "RMR_OK": # ok indicates msg received, stop on all other states
63 if pass_filter is None or len(pass_filter) == 0 or summary[rmr.RMR_MS_MSG_TYPE] in pass_filter: # no filter, or passes; capture it
64 new_messages.append(summary)
66 rmr.rmr_free_msg(mbuf) # free the single buffer to avoid leak
70 def rmr_rcvall_msgs_raw(mrc, pass_filter=None, timeout=0):
72 Same as rmr_rcvall_msgs, but answers tuples with the raw sbuf.
73 Useful if return-to-sender (rts) functions are required.
78 Pointer to the RMR context
80 pass_filter: list (optional)
81 The message type(s) to capture.
83 timeout: int (optional)
84 The number of milliseconds to wait for a message to arrive.
89 List of tuples [(S, sbuf),...] where S is a message summary (dict), and sbuf is the raw message; may be empty.
90 The caller MUST call rmr.rmr_free_msg(sbuf) when finished with each sbuf to prevent memory leaks!
96 mbuf = rmr.rmr_alloc_msg(mrc, 4096) # allocate a new buffer for every message
97 mbuf = rmr.rmr_torcv_msg(mrc, mbuf, timeout) # first call may have non-zero timeout
98 timeout = 0 # reset so subsequent calls do not wait
99 summary = rmr.message_summary(mbuf)
100 if summary[rmr.RMR_MS_MSG_STATUS] != "RMR_OK":
101 rmr.rmr_free_msg(mbuf) # free the failed-to-receive buffer
104 if pass_filter is None or len(pass_filter) == 0 or mbuf.contents.mtype in pass_filter: # no filter, or passes; capture it
105 new_messages.append((summary, mbuf)) # caller is responsible for freeing the buffer
107 rmr.rmr_free_msg(mbuf) # free the filtered-out message buffer