src/sidecars/listener/README

   1
   2 --------------------------------------------------------------------------------
   3
   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
  20
  21 MC Listener
  22
  23 This directory contains the source for the a simple message listener which
  24 writes messages received via RMR into a fifo (named pipe) for an external
  25 process to consume.
  26
  27 Fifos are named MT_xxxxxxxx where the Xs are replaced with the message
  28 type with up to 7 leading zeros (e.g. MT_00000002).  The data written
  29 to a pipe has the form:
  30         <8 bytes><n bytes>
  31
  32 Where the first 8 bytes are the ASCII representation of the length of
  33 the message (n) (the 8th byte is a zero allowing the bytes to be
  34 treated as a C string if desired.  The next n bytes are the unchanged
  35 payload which was received.  No RMR header information (e.g. source,
  36 meid, etc.) is communicated.
  37
  38 If the listener is executed with the timestamp extension enabled, then
  39 the leading 'header' is enhanced such that the time the message was
  40 received by the listener is added.  Additionally, a leading delimiter
  41 is added to make synchronisation possible. The timestamp is also an
  42 ASCII string of the form 1570110224356 (milliseconds past the epoch).
  43 The enhanced header has the format:
  44
  45         <delimeter><length-bytes><time-bytes>
  46
  47 The <delimeter> is a series of 4 bytes which should always be: '@MCL'.
  48 It is intended to be used to sequence "frames" in the pipe should there be
  49 write errors which result in missing data.  If the application reading from
  50 a pipe does not see this delimeter, then it should read byte by byte from
  51 the pipe until it does in order to synchronise with the stream.
  52
  53 The <length-bytes> are as descrbed previously: 8 byte ASCII string (nil
  54 terminated).
  55
  56 The <time-bytes> is an ASCII string (nil terminated) with a length of 16
  57 bytes.
  58
  59 The entire header will require 28 bytes.
  60
  61
  62 There are multiple docker files; *.df.
  63         mcl_runime.df -- builds an image with the runtime mc_listener binary
  64         mcl_dev.df    -- builds a development image that can be used to
  65                                          interactively build and test the library and mc_listener
  66                                          application.
  67
  68 Unit testing
  69 A very small set of unit tests are provided for the library functions in
  70 mcl.c.  Because of the nature of the fanout function, which blocks waiting
  71 on RMR messages, it is not possible to unit test that bit of code.
  72
  73 FIFO Reader
  74 The pipe_reader programme is a simple application which uses the mcl.c
  75 library functions to open and read from a single pipe.  If the -e option
  76 is given it will expect that data in the FIFO has extended headers. Use
  77 the -? option (or -h) to generate a full usage statement.