User Guide

This document explains how to develop an Xapp using the RIC Xapp framework. Information for maintainers of this framework is in the Developer Guide.

Xapp writers should use the public classes and methods from the Xapp Python framework package as documented below.

Class RMRXapp

Application writers should extend this class to implement a reactive Xapp; also see class Xapp.

class ricxappframe.xapp_frame.RMRXapp(default_handler, rmr_port=4562, rmr_wait_for_ready=True, use_fake_sdl=False, post_init=None)

Represents an Xapp that reacts only to RMR messages; i.e., when messages are received, the Xapp does something. When run is called, the xapp framework waits for RMR messages, and calls the appropriate client-registered consume callback on each.

Parameters:

default_handler: function

A function with the signature (summary, sbuf) to be called when a message type is received for which no other handler is registered.

default_handler argument summary: dict

The RMR message summary, a dict of key-value pairs

default_handler argument sbuf: ctypes c_void_p

Pointer to an RMR message buffer. The user must call free on this when done.

rmr_port: integer (optional, default is 4562)

Initialize RMR to listen on this port

rmr_wait_for_ready: boolean (optional, default is True)

Wait for RMR to signal ready before starting the dispatch loop

use_fake_sdl: boolean (optional, default is False)

Use an in-memory store instead of the real SDL service

post_init: function (optional, default None)

Run this function after the app initializes and before the dispatch loop starts; its signature should be post_init(self)

register_callback(handler, message_type)

registers this xapp to call handler(summary, buf) when an rmr message is received of type message_type

Parameters:

handler: function

a function with the signature (summary, sbuf) to be called when a message of type message_type is received

summary: dict

the rmr message summary

sbuf: ctypes c_void_p

Pointer to an rmr message buffer. The user must call free on this when done.

message:type: int

the message type to look for

Note if this method is called multiple times for a single message type, the “last one wins”.

run(thread=False)

This function should be called when the reactive Xapp is ready to start. After start, the Xapp’s handlers will be called on received messages.

Parameters:

thread: bool (optional, default is False)

If False, execution is not returned and the framework loops forever. If True, a thread is started to run the queue read/dispatch loop and execution is returned to caller; the thread can be stopped by calling the .stop() method.

stop()

Sets the flag to end the dispatch loop.

Class Xapp

Application writers should extend this class to implement a general Xapp; also see class RMRXapp.

class ricxappframe.xapp_frame.Xapp(entrypoint, rmr_port=4562, rmr_wait_for_ready=True, use_fake_sdl=False)

Represents a generic Xapp where the client provides a function for the framework to call, which usually contains a loop-forever construct.

Parameters:

entrypoint: function

This function is called when the Xapp class’s run method is invoked. The function signature must be just function(self)

rmr_port: integer (optional, default is 4562)

Initialize RMR to listen on this port

rmr_wait_for_ready: boolean (optional, default is True)

Wait for RMR to signal ready before starting the dispatch loop

use_fake_sdl: boolean (optional, default is False)

Use an in-memory store instead of the real SDL service

run()

This function should be called when the general Xapp is ready to start.

Class SDLWrapper

Application writers may instantiate this class directly to communicate with the SDL service.

class ricxappframe.xapp_sdl.SDLWrapper(use_fake_sdl=False)

This is a wrapper around the SDL Python interface.

We do not embed the below directly in the Xapp classes because this SDL wrapper is useful for other python apps, for example A1 Mediator uses this verbatim. Therefore, we leave this here as a separate object so it can be used outside of xapps.

This class optionally uses msgpack for binary (de)serialization: see https://msgpack.org/index.html

set(ns, key, value, usemsgpack=True)

Stores a key-value pair, optionally serializing the value to bytes using msgpack.

TODO: discuss whether usemsgpack should default to True or False here. This seems like a usage statistic question (that we don’t have enough data for yet). Are more uses for an xapp to write/read their own data, or will more xapps end up reading data written by some other thing? I think it’s too early to know.

Parameters:

ns: string

SDL namespace

key: string

SDL key

value:

Object or byte array to store. See the usemsgpack parameter.

usemsgpack: boolean (optional, default is True)

Determines whether the value is serialized using msgpack before storing. If usemsgpack is True, the msgpack function packb is invoked on the value to yield a byte array that is then sent to SDL. Stated differently, if usemsgpack is True, the value can be anything that is serializable by msgpack. If usemsgpack is False, the value must be bytes.

get(ns, key, usemsgpack=True)

Gets the value for the specified namespace and key, optionally deserializing stored bytes using msgpack.

Parameters:

ns: string

SDL namespace

key: string

SDL key

usemsgpack: boolean (optional, default is True)

If usemsgpack is True, the byte array stored by SDL is deserialized using msgpack to yield the original object that was stored. If usemsgpack is False, the byte array stored by SDL is returned without further processing.

Returns:

Value

See the usemsgpack parameter for an explanation of the returned value type. Answers None if the key is not found.

find_and_get(ns, prefix, usemsgpack=True)

Gets all key-value pairs in the specified namespace with keys that start with the specified prefix, optionally deserializing stored bytes using msgpack.

Parameters:

ns: string

SDL namespace

prefix: string

the key prefix

usemsgpack: boolean (optional, default is True)

If usemsgpack is True, every byte array stored by SDL is deserialized using msgpack to yield the original value that was stored. If usemsgpack is False, every byte array stored by SDL is returned without further processing.

Returns:

Dictionary of key-value pairs

Each key has the specified prefix. See the usemsgpack parameter for an explanation of the returned value types. Answers an empty dictionary if no keys matched the prefix.

delete(ns, key)

Deletes the key-value pair with the specified key in the specified namespace.

Parameters:

ns: string

SDL namespace

key: string

SDL key

healthcheck()

Checks if the sdl connection is healthy.

Returns:

bool