helpers.py

   1 # vim: ts=4 sw=4 expandtab:
   2 # ==================================================================================
   3 #       Copyright (c) 2019 Nokia
   4 #       Copyright (c) 2018-2019 AT&T Intellectual Property.
   5 #
   6 #   Licensed under the Apache License, Version 2.0 (the "License");
   7 #   you may not use this file except in compliance with the License.
   8 #   You may obtain a copy of the License at
   9 #
  10 #          http://www.apache.org/licenses/LICENSE-2.0
  11 #
  12 #   Unless required by applicable law or agreed to in writing, software
  13 #   distributed under the License is distributed on an "AS IS" BASIS,
  14 #   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15 #   See the License for the specific language governing permissions and
  16 #   limitations under the License.
  17 # ==================================================================================
  18
  19 #   Mnemonic:   helpers.py
  20 #   Abstract:   This is a colleciton of extensions to the RMR base package
  21 #               which are likely to be convenient for python programmes.
  22 #   Date:       26 September 2019
  23 # ---------------------------------------------------------------------------
  24
  25 from ricxappframe.rmr import rmr
  26
  27
  28 def rmr_rcvall_msgs(mrc, pass_filter=[]):
  29     """
  30     Assemble an array of all messages which can be received without
  31     blocking.  Effectively draining the message queue if RMR is started
  32     in mt-call mode, or draining any waiting TCP buffers.  If the
  33     pass_filter parameter is supplied it is treated as one or more message
  34     types to accept (pass through). Using the default, an empty list, results
  35     in messages with any type being captured.
  36
  37     Parameters
  38     ----------
  39         mrc: ctypes c_void_p
  40             Pointer to the RMR context
  41
  42         pass_filter: list (optional)
  43             The message type(s) to capture.
  44
  45     Returns
  46     -------
  47         list of dict
  48         List of message summaries, one for each message captured.
  49     """
  50
  51     new_messages = []
  52     mbuf = rmr.rmr_alloc_msg(mrc, 4096)  # allocate buffer to have something for a return status
  53
  54     while True:
  55         mbuf = rmr.rmr_torcv_msg(mrc, mbuf, 0)  # set the timeout to 0 so this doesn't block!!
  56
  57         summary = rmr.message_summary(mbuf)
  58         if summary["message status"] != "RMR_OK":  # ok indicates msg received, stop on all other states
  59             break
  60
  61         if len(pass_filter) == 0 or summary["message type"] in pass_filter:  # no filter, or passes; capture it
  62             new_messages.append(summary)
  63
  64     rmr.rmr_free_msg(mbuf)  # must free message to avoid leak
  65     return new_messages
  66
  67
  68 def rmr_rcvall_msgs_raw(mrc, pass_filter=[]):
  69     """
  70     Same as rmr_rcvall_msgs, but the raw sbuf is also returned.
  71     Useful, for example, if rts is to be used.
  72
  73     Parameters
  74     ----------
  75         mrc: ctypes c_void_p
  76             Pointer to the RMR context
  77
  78         pass_filter: list (optional)
  79             The message type(s) to capture.
  80
  81     Returns
  82     -------
  83     list of tuple:$
  84        List of tuples [(S, sbuf),...] where S is a message summary and sbuf is the raw message$
  85        the caller is responsible for calling rmr.rmr_free_msg(sbuf) for each sbuf afterwards to prevent memory leaks.
  86     """
  87
  88     new_messages = []
  89
  90     while True:
  91         mbuf = rmr.rmr_alloc_msg(mrc, 4096)  # allocate buffer to have something for a return status
  92         mbuf = rmr.rmr_torcv_msg(mrc, mbuf, 0)  # set the timeout to 0 so this doesn't block!!
  93         summary = rmr.message_summary(mbuf)
  94         if summary["message status"] != "RMR_OK":
  95             break
  96
  97         if len(pass_filter) == 0 or mbuf.contents.mtype in pass_filter:  # no filter, or passes; capture it
  98             new_messages.append((summary, mbuf))
  99         else:
 100             rmr.rmr_free_msg(mbuf)
 101
 102     return new_messages