docs/overview.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. Copyright (C) 2020 AT&T Intellectual Property
   4
   5 Framework Overview
   6 ==================
   7
   8 This package is a framework for writing RAN Intelligent Controller
   9 (RIC) Xapps in python. The framework reduces the amount of code
  10 required in an Xapp by providing common features needed by all
  11 Python-based Xapps including communication with the RIC message router
  12 (RMR) and the Shared Data Layer (SDL).
  13
  14 The framework was designed to suport many types of Xapps, including
  15 applications that are purely reactive to RMR messages, and general
  16 applications that initiate actions according to other criteria.
  17
  18 For complete documentation see the ReadTheDocs site for
  19 `xapp-frame-py <https://docs.o-ran-sc.org/projects/o-ran-sc-ric-plt-xapp-frame-py>`_.
  20
  21 Reactive Xapps
  22 --------------
  23
  24 A reactive Xapp acts on messages that are delivered (pushed) via RMR.
  25 The Xapp only takes action upon receipt of an RMR message. The Xapp
  26 never takes action at another time.
  27
  28 This type of application is constructed by creating callback functions
  29 and registering them with the framework by message type.  When an RMR
  30 message arrives, the appropriate callback is invoked based on the
  31 message type.  An Xapp may define and register a separate callback for
  32 each expected message type.  Every Xapp must define a default callback
  33 function, which is invoked when a message arrives for which no
  34 type-specific callback was registered.  An analogy of this is AWS
  35 Lambda: "execute this code every time an event comes in" (the code to
  36 execute can depend on the type of event).
  37
  38 General Xapps
  39 -------------
  40
  41 A general Xapp acts according to its own criteria, which may include
  42 receipt of RMR messages.
  43
  44 This type of application is constructed by creating a single function
  45 that is invoked by the framework after initialization.  Typically that
  46 function contains a `while (something)` event loop.  When the function
  47 returns, the Xapp stops.  In this usage, the Xapp must fetch its own
  48 data, either from RMR, SDL or other source.  The framework does less
  49 work for a general application compared to a reactive application; the
  50 framework only sets up an RMR thread and an SDL connection before
  51 invoking the client-provided function.
  52
  53 Threading in the Framework
  54 --------------------------
  55
  56 RMR interactions are processed in a thread started by the framework.
  57 This implementation detail is documented here for transparency, but
  58 most users will not have to worry about this.
  59
  60 In both types of Xapp, the framework launches a separate thread whose
  61 only job is to read from RMR and deposit all messages (and their
  62 summaries) into a thread-safe queue.  When the client Xapp reads from
  63 RMR using the framework (this read is done by the framework itself in
  64 the RMR Xapp, but by the client in a general Xapp), the read is done
  65 from the framework-managed queue.  The framework is implemented this
  66 way so that a long-running client function (e.g., consume) will not
  67 block RMR reads.  This is important because RMR is *not* a persistent
  68 message bus; if an RMR client does not read fast enough, messages can
  69 be lost.  So in this framework the client code is not in the same
  70 thread as the RMR reads, to ensure that long-running client code will
  71 not cause message loss.
  72
  73 In the case of RMR Xapps, there are currently 3 potential threads; the
  74 thread that reads from RMR directly, and the user can optionally have
  75 the RMR queue read run in a thread, returning execution back to the
  76 user thread.  The default is only two threads however, where `.run`
  77 does not return back execution and the user code is finished at that
  78 point.
  79
  80 Healthchecks
  81 ------------
  82
  83 The framework provides a default RMR healthcheck probe handler for
  84 reactive Xapps.  When an RMR healthcheck message arrives, this handler
  85 checks that the RMR thread is healthy (of course the Xapp cannot even
  86 reply if the thread is not healthy!), and that the SDL connection is
  87 healthy.  The handler responds accordingly via RMR.  The Xapp can
  88 override this probe handler by registering a new callback for the
  89 healthcheck message type.
  90
  91 The framework provides no healthcheck handler for general Xapps. Those
  92 applications must handle healthcheck probe messages appropriately when
  93 they read their RMR mailboxes.
  94
  95 There is no http service in the framework, so there is no support for
  96 HTTP-based healthcheck probes, such as what a deployment manager like
  97 Kubernetes may use.
  98
  99 Examples
 100 --------
 101
 102 Two sample Xapps using this framework are provided in the `examples`
 103 directory of the
 104 `git repository <https://gerrit.o-ran-sc.org/r/gitweb?p=ric-plt/xapp-frame.git;a=tree>`_.
 105 The first, `ping`, is a general Xapp
 106 that defines a main function that reads its RMR mailbox in addition to
 107 other work.  The second, `pong`, is a reactive Xapp that only takes
 108 action when a message is received.
 109
 110 To run a demonstration, build the Docker images for both examples
 111 using the supplied Dockerfiles.  Then start the Pong container (the
 112 listener) followed by the Ping container (the sender).  The Ping
 113 application sends a message, the pong application receives the message
 114 and use RMR's return-to-sender feature to reply.  Ping then reads its
 115 own mailbox and demonstrates other functionality.