src/bindings/rmr-python/README.md

   1 # rmr-python
   2
   3 # Summary, Limitations
   4 This is a CTYPES wrapper around the C rmr library. It requires you have rmr installed.
   5
   6 That is, it is not a native re-implementation of the rmr library. This seems to come with pros and cons. On the positive side, wrapping the library was much less work; we only need to wrap the function signatures.
   7 Keeping up with the rmr spec is thus also less work, as when new functions are added into the C lib, we only need to again wrap the function signatures.
   8
   9 The downside is this seems to be Linux only currently. This wrapper immediately SIGABRT's on Mac, and no one yet seems to know why.
  10 The other downside is that there are currently some functionality that needs to be "exported" from the C library for this to be fully operational. For example, CTYPES does not have access to C header files, and important
  11 constants are defined in the C header files. Also, the C lib uses "errno" to propogate some error conditions, and those are not available "in-band" yet.
  12
  13 It could be questioned whether this was a good decision, or whether we should have natively reimplemented the API with the nano nng python bindings: https://pypi.org/project/pynng/
  14
  15 ## Not Yet Implemented
  16 At the time of this writing (March 28 2019) The following C functions are not yet implemented in this library (do we need them?):
  17
  18     1. `extern void rmr_free_msg`
  19     2. `extern rmr_mbuf_t* rmr_mtosend_msg`
  20     3. `extern rmr_mbuf_t* rmr_call` (this has some problems AFAIU from Scott)
  21     4. `extern rmr_mbuf_t* rmr_rcv_specific`
  22     5. `extern int rmr_get_rcvfd`
  23
  24 # Higher order library
  25
  26 There is/was somewhat of a debate about what belongs here, and the current answer is that this is mostly a pure wrapper around the C rmr library (though it does come with one convenience function called `message_summary` which is quite useful)
  27
  28 There are some higher order send functions, for example functions that send and expect an ACK back of a specific message type, that might be useful to you, here: https://gitlab.research.att.com/tommy/ric-ons-a1-gevent/blob/master/a1/a1rmr.py
  29
  30 # Unit Testing
  31
  32     tox
  33     open htmlcov/index.html
  34
  35 # Installation
  36
  37 ## Prequisites
  38
  39 If rmr is *not* compiled on your system, see the below instructions for downloading and compiling rmr. This library expects that the rmr .so files are compiled and available.
  40
  41 ## From PyPi
  42 (TODO: This is going to have to change to some LF PYPI or some public PYPI, soon.)
  43
  44     pip install --trusted-host nexus01.research.att.com --extra-index-url https://nexus01.research.att.com:8443/repository/solutioning01-mte2-pypi/simple rmr==version.you.want
  45
  46 ## From Source
  47 (TODO: this has to be moved to LF)
  48
  49     git clone git@gitlab.research.att.com:tommy/rmr-python.git
  50     cd rmr-python
  51     pip install .
  52
  53 # Examples
  54
  55 See the `examples` directory.
  56
  57 # Compiling rmr (if not already done on your system)
  58 (Note, you may or may not need sudo in your final command, depending on permissions to `/usr/local`. I need it)
  59
  60     git clone https://gerrit.oran-osc.org/r/ric-plt/lib/rmr
  61     cd rmr
  62     mkdir .build; cd .build; cmake ..; sudo make install