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