.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. SPDX-License-Identifier: CC-BY-4.0
.. Copyright (C) 2020 AT&T Intellectual Property
Framework Overview
==================
This package is a framework for writing RAN Intelligent Controller
(RIC) Xapps in python. The framework reduces the amount of code
required in an Xapp by providing common features needed by all
Python-based Xapps including communication with the RIC message router
(RMR) and the Shared Data Layer (SDL).
The framework was designed to suport many types of Xapps, including
applications that are purely reactive to RMR messages, and general
applications that initiate actions according to other criteria.
For complete documentation see the ReadTheDocs site for
`xapp-frame-py <https://docs.o-ran-sc.org/projects/o-ran-sc-ric-plt-xapp-frame-py>`_.
Reactive Xapps
--------------
A reactive Xapp acts on messages that are delivered (pushed) via RMR.
The Xapp only takes action upon receipt of an RMR message. The Xapp
never takes action at another time.
This type of application is constructed by creating callback functions
and registering them with the framework by message type. When an RMR
message arrives, the appropriate callback is invoked based on the
message type. An Xapp may define and register a separate callback for
each expected message type. Every Xapp must define a default callback
function, which is invoked when a message arrives for which no
type-specific callback was registered. An analogy of this is AWS
Lambda: "execute this code every time an event comes in" (the code to
execute can depend on the type of event).
General Xapps
-------------
A general Xapp acts according to its own criteria, which may include
receipt of RMR messages.
This type of application is constructed by creating a single function
that is invoked by the framework after initialization. Typically that
function contains a `while (something)` event loop. When the function
returns, the Xapp stops. In this usage, the Xapp must fetch its own
data, either from RMR, SDL or other source. The framework does less
work for a general application compared to a reactive application; the
framework only sets up an RMR thread and an SDL connection before
invoking the client-provided function.
Threading in the Framework
--------------------------
RMR interactions are processed in a thread started by the framework.
This implementation detail is documented here for transparency, but
most users will not have to worry about this.
In both types of Xapp, the framework launches a separate thread whose
only job is to read from RMR and deposit all messages (and their
summaries) into a thread-safe queue. When the client Xapp reads from
RMR using the framework (this read is done by the framework itself in
the RMR Xapp, but by the client in a general Xapp), the read is done
from the framework-managed queue. The framework is implemented this
way so that a long-running client function (e.g., consume) will not
block RMR reads. This is important because RMR is *not* a persistent
message bus; if an RMR client does not read fast enough, messages can
be lost. So in this framework the client code is not in the same
thread as the RMR reads, to ensure that long-running client code will
not cause message loss.
In the case of RMR Xapps, there are currently 3 potential threads; the
thread that reads from RMR directly, and the user can optionally have
the RMR queue read run in a thread, returning execution back to the
user thread. The default is only two threads however, where `.run`
does not return back execution and the user code is finished at that
point.
Healthchecks
------------
The framework provides a default RMR healthcheck probe handler for
reactive Xapps. When an RMR healthcheck message arrives, this handler
checks that the RMR thread is healthy (of course the Xapp cannot even
reply if the thread is not healthy!), and that the SDL connection is
healthy. The handler responds accordingly via RMR. The Xapp can
override this probe handler by registering a new callback for the
healthcheck message type.
The framework provides no healthcheck handler for general Xapps. Those
applications must handle healthcheck probe messages appropriately when
they read their RMR mailboxes.
There is no http service in the framework, so there is no support for
HTTP-based healthcheck probes, such as what a deployment manager like
Kubernetes may use.
Examples
--------
Two sample Xapps using this framework are provided in the `examples`
directory of the
`git repository <https://gerrit.o-ran-sc.org/r/gitweb?p=ric-plt/xapp-frame.git;a=tree>`_.
The first, `ping`, is a general Xapp
that defines a main function that reads its RMR mailbox in addition to
other work. The second, `pong`, is a reactive Xapp that only takes
action when a message is received.
To run a demonstration, build the Docker images for both examples
using the supplied Dockerfiles. Then start the Pong container (the
listener) followed by the Ping container (the sender). The Ping
application sends a message, the pong application receives the message
and use RMR's return-to-sender feature to reply. Ping then reads its
own mailbox and demonstrates other functionality.
Raw data
{
"_id": null,
"home_page": "https://gerrit.o-ran-sc.org/r/admin/repos/ric-plt/xapp-frame-py",
"name": "ricxappframe",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "RIC xapp",
"author": "O-RAN Software Community",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/99/7d/ef6b34acf4590e1061be15b93dbedbf4e52ab99f9988db7dd2c7c5785d18/ricxappframe-3.2.1.tar.gz",
"platform": null,
"description": ".. This work is licensed under a Creative Commons Attribution 4.0 International License.\n.. SPDX-License-Identifier: CC-BY-4.0\n.. Copyright (C) 2020 AT&T Intellectual Property\n\nFramework Overview\n==================\n\nThis package is a framework for writing RAN Intelligent Controller\n(RIC) Xapps in python. The framework reduces the amount of code\nrequired in an Xapp by providing common features needed by all\nPython-based Xapps including communication with the RIC message router\n(RMR) and the Shared Data Layer (SDL).\n\nThe framework was designed to suport many types of Xapps, including\napplications that are purely reactive to RMR messages, and general\napplications that initiate actions according to other criteria.\n\nFor complete documentation see the ReadTheDocs site for\n`xapp-frame-py <https://docs.o-ran-sc.org/projects/o-ran-sc-ric-plt-xapp-frame-py>`_.\n\nReactive Xapps\n--------------\n\nA reactive Xapp acts on messages that are delivered (pushed) via RMR.\nThe Xapp only takes action upon receipt of an RMR message. The Xapp\nnever takes action at another time.\n\nThis type of application is constructed by creating callback functions\nand registering them with the framework by message type. When an RMR\nmessage arrives, the appropriate callback is invoked based on the\nmessage type. An Xapp may define and register a separate callback for\neach expected message type. Every Xapp must define a default callback\nfunction, which is invoked when a message arrives for which no\ntype-specific callback was registered. An analogy of this is AWS\nLambda: \"execute this code every time an event comes in\" (the code to\nexecute can depend on the type of event).\n\nGeneral Xapps\n-------------\n\nA general Xapp acts according to its own criteria, which may include\nreceipt of RMR messages.\n\nThis type of application is constructed by creating a single function\nthat is invoked by the framework after initialization. Typically that\nfunction contains a `while (something)` event loop. When the function\nreturns, the Xapp stops. In this usage, the Xapp must fetch its own\ndata, either from RMR, SDL or other source. The framework does less\nwork for a general application compared to a reactive application; the\nframework only sets up an RMR thread and an SDL connection before\ninvoking the client-provided function.\n\nThreading in the Framework\n--------------------------\n\nRMR interactions are processed in a thread started by the framework.\nThis implementation detail is documented here for transparency, but\nmost users will not have to worry about this.\n\nIn both types of Xapp, the framework launches a separate thread whose\nonly job is to read from RMR and deposit all messages (and their\nsummaries) into a thread-safe queue. When the client Xapp reads from\nRMR using the framework (this read is done by the framework itself in\nthe RMR Xapp, but by the client in a general Xapp), the read is done\nfrom the framework-managed queue. The framework is implemented this\nway so that a long-running client function (e.g., consume) will not\nblock RMR reads. This is important because RMR is *not* a persistent\nmessage bus; if an RMR client does not read fast enough, messages can\nbe lost. So in this framework the client code is not in the same\nthread as the RMR reads, to ensure that long-running client code will\nnot cause message loss.\n\nIn the case of RMR Xapps, there are currently 3 potential threads; the\nthread that reads from RMR directly, and the user can optionally have\nthe RMR queue read run in a thread, returning execution back to the\nuser thread. The default is only two threads however, where `.run`\ndoes not return back execution and the user code is finished at that\npoint.\n\nHealthchecks\n------------\n\nThe framework provides a default RMR healthcheck probe handler for\nreactive Xapps. When an RMR healthcheck message arrives, this handler\nchecks that the RMR thread is healthy (of course the Xapp cannot even\nreply if the thread is not healthy!), and that the SDL connection is\nhealthy. The handler responds accordingly via RMR. The Xapp can\noverride this probe handler by registering a new callback for the\nhealthcheck message type.\n\nThe framework provides no healthcheck handler for general Xapps. Those\napplications must handle healthcheck probe messages appropriately when\nthey read their RMR mailboxes.\n\nThere is no http service in the framework, so there is no support for\nHTTP-based healthcheck probes, such as what a deployment manager like\nKubernetes may use.\n\nExamples\n--------\n\nTwo sample Xapps using this framework are provided in the `examples`\ndirectory of the\n`git repository <https://gerrit.o-ran-sc.org/r/gitweb?p=ric-plt/xapp-frame.git;a=tree>`_.\nThe first, `ping`, is a general Xapp\nthat defines a main function that reads its RMR mailbox in addition to\nother work. The second, `pong`, is a reactive Xapp that only takes\naction when a message is received.\n\nTo run a demonstration, build the Docker images for both examples\nusing the supplied Dockerfiles. Then start the Pong container (the\nlistener) followed by the Ping container (the sender). The Ping\napplication sends a message, the pong application receives the message\nand use RMR's return-to-sender feature to reply. Ping then reads its\nown mailbox and demonstrates other functionality.\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Xapp and RMR framework for Python",
"version": "3.2.1",
"split_keywords": [
"ric",
"xapp"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "ed3e4b9cc1915d96c5d67f7fd3e61a3a",
"sha256": "941eef948081817215410faf765a209f547bebd0e882b63d94489a7946586247"
},
"downloads": -1,
"filename": "ricxappframe-3.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ed3e4b9cc1915d96c5d67f7fd3e61a3a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 138060,
"upload_time": "2022-12-12T12:31:07",
"upload_time_iso_8601": "2022-12-12T12:31:07.814710Z",
"url": "https://files.pythonhosted.org/packages/1f/0b/d73756503ede78e37482eba3411b46cd2c5d2d22b12c3eae49371081f1e7/ricxappframe-3.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "1cb51ea3c52c47fd31bef0fb6f9a3330",
"sha256": "dc07f9754071a5395bb766560add6c8420eb89efecdb818d8bf8d333a247c885"
},
"downloads": -1,
"filename": "ricxappframe-3.2.1.tar.gz",
"has_sig": false,
"md5_digest": "1cb51ea3c52c47fd31bef0fb6f9a3330",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 93481,
"upload_time": "2022-12-12T12:31:09",
"upload_time_iso_8601": "2022-12-12T12:31:09.522528Z",
"url": "https://files.pythonhosted.org/packages/99/7d/ef6b34acf4590e1061be15b93dbedbf4e52ab99f9988db7dd2c7c5785d18/ricxappframe-3.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-12 12:31:09",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "ricxappframe"
}
JSON