SAI-Overview-B.02.01 SA Forum Extended Training Materials Service Availability Interface Lesson 1.

SAI-Overview-B.02.01

SA Forum Extended Training Materials

Service Availability InterfaceLesson 1

Copyright© 2006 Service Availability™ Forum, Inc 2

Contents

This lesson provides material that is common to all of the areas of the Application Interface Specification. In particular, it addresses:• Naming Conventions

• Programming / Usage Model

• Library Lifecycle API

• Error Codes

• Memory Allocation and Deallocation

• Version Mechanism

• Track API

• Name Types and Object Names


Application Interface Specification The Application Interface Specification (AIS) is a

set of open standard interface specifications for high service availability in carrier-grade telecommunication systems and networks

It defines Application Program Interfaces (APIs) between the applications and the service availability middleware for:• AIS Availability Management Framework

• AIS Services– Cluster Membership Service– Checkpoint Service– Event Service– Message Service– Lock Service– Log Service– Notification Service– Information Model Management Service


AIS Naming Conventions The AIS is broken down into interface areas An interface area consists of a set of self-contained

APIs that can be provided as a single library with its associated header file(s)

Each interface area is assigned an interface area tag that identifies the functions pertaining to that area• Amf Availability Management Framework• Clm Cluster Membership Service• Ckpt Checkpoint Service• Evt Event Service• Msg Message Service• Lck Lock Service• Log Log Service• Ntf Notification Service• Imm Information Model Management Service


AIS Naming Conventions

Global Function Declarations

sa<Area><Object><Action><Tag>(arguments)

• <Area> Interface area tag

• <Object> Name or abbreviation of object or service

• <Action> Name or abbreviation of action

• <Tag> Tag for the function such as Async or Callback

Example: saEvtChannelOpenAsync()

Global Variable Declarations<type> sa<Area><Variable Name>

Example: SaNameT saAmfComponentName



Type Declarations

typedef <...> Sa<Area><TypeName>T

Example: typedef SaUint32T SaCkptHandleT

Macro Declarations

#define SA_<AREA>_<MACRO NAME> <macro definition>

Example: #define SA_EVT_HIGHEST_PRIORITY 0

• The names of macros use only uppercase letters and the digits 0-9

• They use underscores to separate words and improve readability


AIS Naming Conventions Enumeration Type Declarations typedef enum {

SA_<AREA>_<ENUMERATION_NAME1> [= <value>],

SA_<AREA>_<ENUMERATION_NAME2> [= <value>],

....

SA_<AREA>_<ENUMERATION_NAMEn> [= <value>]

} <enumeration type name>;

Example:

typedef enum {

SA_CKPT_SECTION_VALID = 1,

SA_CKPT_SECTION_CORRUPTED = 2

} SaCkptSectionStateT;

• The names of enumeration elements use only uppercase letters and the digits 0-9

• They use underscores to separate words and improve readability



Some Pre-Defined Types and Constants

typedef SaUint64T SaSizeT Used to specify sizes of objects

typedef SaUint64T SaOffsetT Used to specify offsets in data areas

typedef SaInt64T SaTimeT Used to specify time values (nanoseconds granularity)

Depending on the case, it can be interpreted as an absolute time or a time duration

#define SA_TIME_UNKNOWN 0x8000000000000000

Unknown time value

#define SA_TIME_BEGIN 0x0000000000000000

Smallest timestamp

#define SA_TIME_END 0x7FFFFFFFFFFFFFFF

Largest timestamp

#define SA_TIME_MAX Interpreted as an infinite duration


AIS Programming / Usage Model The AIS specifies the interface between a process (uni-threaded or multi-threaded) and a library that implements the interface

The term process, as used in the AIS, can be regarded as being equivalent to a process defined by the POSIX standard

The term area server is used to represent the server that provides services for a specification area (Amf, Clm, Ckpt, Msg, etc)

Private Interface

UML Diagram

Availability Management Framework Package

Server for<Area> Service

Communicationmethod unspecified- could be remote or

local

Internal (Private)Interface

communication

Application InterfaceImplementation Library

Designed to accommodateunthreaded process model-can be used with threaded

-process model as well

SA ForumApplication

Interface

Process


AIS Programming / Usage Model The area implementation libraries may be implemented in

one or several physical libraries

• However, a process is required to initialize, register and obtain an operating system selection object separately for each area implementation library

• Thus, from a programming standpoint, it is useful to view these libraries as separate libraries

It is expected that the area server and the area implementation library are packaged together and are designed to be released as a set; however, this does not preclude other packaging options

The area server and the area implementation library may reside on the same or different computers


AIS Programming / Usage Model

The AIS employs both the synchronous and the asynchronous programming models • The synchronous model is generally easier for

programmers to understand and use

• However, there are applications where the number of simultaneous outstanding requests precludes having an independent thread of execution for each request

• Moreover, some applications require direct control of scheduling within a process

• To support such applications, some of the APIs of the AIS are based on the asynchronous model


AIS Library Lifecycle API for Areas sa<Area>Initialize() function

SaAisErrorT sa<Area>Initialize(

/* OUT */ Sa<Area>HandleT *<area>Handle,

/* IN */ const Sa<Area>CallbacksT *<area>Callbacks,

/* IN/OUT */ SaVersionT *version);

Initializes the area service for the invoking process and registers the callbacks whose function pointers are provided in *<area>Callbacks

Any API call, including sa<Area>Dispatch(), can be called from any callback function

Supports several invocations of initialization functions per process and area

Returns <area>Handle, which can be used in subsequent calls

As an input parameter, version indicates the version of the particular area service that the process requires. As an output parameter, the version actually supported by the particular area service is delivered


AIS Library Lifecycle API for Areas

sa<Area>Finalize() function

SaAisErrorT sa<Area>Finalize(

/* IN */ Sa<Area>HandleT <area>Handle);

Closes the association, represented by the <area>Handle parameter, between the invoking process and the area service

Releases resources, cancels pending callbacks, etc

A finalize call is needed for each area initialization


AIS Library Lifecycle API for Areas

sa<Area>SelectionObjectGet() function

SaAisErrorT sa<Area>SelectionObjectGet(

/* IN */ Sa<Area>HandleT <area>Handle,

/* OUT */ SaSelectionObjectT *selectionObject);

Obtains the operating system handle, selectionObject, associated with the handle <area>Handle. This call is used to detect pending callbacks

With POSIX, the selection object is simply a file descriptor, provided by the operating system, and selectionObject is a pointer to the file descriptor

The selectionObject is valid until sa<Area>Finalize() is invoked on <area>Handle


AIS Library Lifecyle API for Areas sa<Area>Dispatch() function

SaAisErrorT sa<Area>Dispatch(

/* IN */ SaClmHandleT <area>Handle,

/* OUT */ SaDispatchFlagsT dispatchFlags);

The sa<Area>Dispatch() function invokes, in the context of the calling thread, pending callbacks for the handle, designated by <area>Handle, as specified by the dispatchFlags parameter (see the next slide)

When the process detects, using a selection object, that invocations are pending for a callback function, and it is ready to process them, it calls the sa<Area>Dispatch() function


AIS Dispatch Flags

SaDispatchFlagsT type

SA_DISPATCH_ONE Invokes a single pending callback in the context of the calling thread, if there is a pending callback, and then returns from the dispatch

SA_DISPATCH_ALL Invokes all of the pending callbacks in the context of the calling thread, if there are any pending callbacks, before returning from dispatch

SA_DISPATCH_BLOCKING One or more threads calling dispatch remain within dispatch and execute callbacks as they become pending. The thread or threads do not return from dispatch until the corresponding finalize function is executed by one thread of the process


AIS Error Codes

Some of the Error Codes Defined by the AIS

SA_AIS_ERR_LIBRARY An unexpected problem occurred in the library (such as corruption)

SA_AIS_ERR_VERSION Version parameter is not compatible with the version of the implementation of the AMF or AIS Service

SA_AIS_ERR_INIT A callback function required for the API was not supplied in a previous call of sa<Area>Initialize()

SA_AIS_ERR_TIMEOUT An implementation-dependent timeout or the timeout specified in the API call occurred before the call could complete

SA_AIS_ERR_INVALID_PARAM Parameter is not set correctly

SA_AIS_ERR_NO_MEMORY Either the library or the provider of the service is out of memory and cannot provide the service

SA_AIS_ERR_BUSY Resource is already in use


AIS Programming / Usage Model1. The process within the component

invokes the sa<Area>Initialize() function to provide a set of callbacks for use by the library in calling back the component

2. The sa<Area>Initialize() function returns an interface handle to the invoking process

3. The process invokes the sa<Area>SelectionObjectGet() function to obtain a selection object, which is an operating system dependent object, e.g., a file descriptor

4. The interface returns a selection object to the process, allowing the process to wait until an invocation to a callback function is pending for it

5. The process waits on the selection object

ProcessApplication Interface

Implementation LibraryServer for

<Area> Service

Command

sa<Area>Initialize()

sa<Area>Dispatch()

Invoke proper callbackto perform Command

Return Handle

Return Selection Object

sa<Area>SelectionObjectGet()

wait complete

sa<Area>Response()

Wait on Selection Object

Communicationby private interface


AIS Programming / Usage Model6. The area server sends a command

over its "private" interface to the library

7. The library "awakes" the selection object, thereby awaking the process

8. The process invokes the sa<Area>Dispatch() function

9. The library invokes the appropriate callback function of the process corresponding to the command received from the area server. The callback function parameters inform the process of the specific details of the command issued by the area server or the information provided by the area server

10. Once the process completes processing the callback, it responds by invoking a function of the area interface. In some cases, more than one response invocation, or no response, is necessary

ProcessApplication Interface

Implementation LibraryServer for

<Area> Service

Command

sa<Area>Initialize()

sa<Area>Dispatch()

Invoke proper callbackto perform Command

Return Handle

Return Selection Object

sa<Area>SelectionObjectGet()

wait complete

sa<Area>Response()

Wait on Selection Object

Communicationby private interface


AIS in a POSIX Environment

AIS functions must be thread-safe, so that they can be invoked concurrently by different threads of a process

Async-signal safety (invocation from a signal handler) is not required for AIS functions

Rules to be observed by an application programmer• Avoid using any AIS function within a signal handler• Do not assume that AIS functions are interruptible by signals• Do not assume that AIS functions are thread cancellation points• Do not assume that AIS functions are fork-safe

– If a process using AIS functions forks a child process, that calls AIS functions, the child process should exec() a new program immediately after being forked; this new program can then use AIS functions


Memory Allocation and Deallocation Rule 1: Memory dynamically allocated by one entity

(service user or service area library) is deallocated by that same entity with the exception given in Rule 2

Rule 2: The area service library allocates the buffer and the service user deallocates the buffer in cases where• It is difficult for the service user to predict how much memory

will be needed and, thus, to provide a buffer of the appropriate size

• It results in excessive copying and, thus, adversely impacts performance

Each area service providing a function that allocates memory for a service user must provide a function that the user can call to deallocate the allocated memory


Memory Allocation and Deallocation Example Use of Rule 2: typedef struct{ char *buf; SaInt32T len; } SaXxxBufferT; SaAisErrorT saXxxReceive(SaXxxHandleT handle, SaXXXBufferT buffer); SaAisErrorT saXxxReceiveDataFree(SaXXXHandleT handle, void *buffer);

SaXxx BufferT msg; SaInt32T myLen; msg.buf = NULL; error = saXxxReceive(handle, msg); if (error != SA_AIS_OK) {/* handle error */} if (msg.buf != NULL) { /* process message */ myLen = msg.len; /* area service sets length */ process_message(msg.buf, myLen); saXxxReceiveDataFree(handle, msg.buf); msg.buf = NULL; };


AIS Version Mechanism SaVersionT structure

SaUint8T releaseCode

A single ASCII capital letter [A-Z]All specifications and implementations with the same releaseCode are backward compatible Infrequent changes are expected

SaUint8T majorVersion

A number in the range [01..255] An area implementation with a given majorVersion complies to the

specification bearing the same releaseCode and majorVersion New majorVersion numbers are expected at most once or twice a year for

the first few years, becoming less frequent as time goes on

SaUint8T minorVersion

A number in the range [01..255] Successive updates of an area implementation, complying to

an area interface specification bearing the same releaseCode and majorVersion, have increasing minorVersion numbers, which are used to indicate enhancements like better performance or bug fixes

Different values of the minorVersion must not impact compatibility, and are not used to check whether required and supported versions are compatible


Version Parameter for Initialize

sa<Area>Initialize() in the case that the implementation supports the required releaseCode and a major version >= the required majorVersion• SA_AIS_OK is returned by sa<Area>Initialize()

• The version parameter is set by sa<Area>Initialize() to:– releaseCode = Required release code

– majorVersion = Greatest value of the major version that this implementation can support for the required releaseCode

– minorVersion = Greatest value of the minor version that this implementation can support for the required value of releaseCode and the returned value of majorVersion


Version Parameter for Initialize sa<Area>Initialize() in the case that the implementation does not

support the required releaseCode or a major version >= the required majorVersion

• SA_AIS_ERR_VERSION is returned by sa<Area>Initialize()

• The version parameter is set by sa<Area>Initialize() to: if (implementation supports the required releaseCode)

releaseCode = required releaseCode

else {

if (implementation supports releaseCode greater than the required releaseCode)

releaseCode = the least value of the supported release codes that is greater than the required releaseCode

else

releaseCode = the greatest value of the supported release codes that is less than the required releaseCode

}

majorVersion = greatest value of the major versions that this implementation can support for the returned releaseCode

minorVersion = greatest value of the minor versions that this implementation can support for the returned values of releaseCode and majorVersion


Backward Compatibility To achieve backward compatibility with the AIS

B.02.01 specification in the future, the SA Forum will follow the rules below • A function / type definition never changes for a given release

• Changes in a function / type definition (adding a new argument to a function or adding a new field to a data structure) force the definition of a new function / type name

– A new function/type name is constructed from the original name in AIS B.02.01 with a suffix indicating the version where the function / type changed, as, for example, in saAmfComponentRegister_3()

– Exception: New enum or flag values can be added to an existing enum or flag typedef without changing the type name as long as the size of the enum or flag typedef does not change

– AIS implementers must ensure that they respect the version numbers provided by the application when it initializes the library and do not expose new enum values to applications using older versions


AIS Track API Some area services provide groups of entities and allow the

applications to track those groups as the groups change dynamically Example: Nodes joining or leaving a cluster (i.e., a group of nodes)

Similar functionality for tracking in different area services • Start tracking an object (a group)

• Callback notification about an object change

• Stop tracking an object

Format: sa<Area><Object>Track[<Func>]() • <Area> denotes the area service

• <Object> denotes the tracked object

• <Func> denotes one of the track functions

A tracked object is identified by an area service handle and an object name • The object name is omitted if the object can be identified by only the

area service handle

• Thus, the objectName parameter is marked “if needed” in the APIs


AIS Track Flags

SA_TRACK_CURRENT Information about all entities in the group is returned immediately, either in a notification buffer as indicated by the caller, or by a single subsequent notification callback

SA_TRACK_CHANGES The notification callback is invoked each time at least one change occurs in the membership of the group or one attribute of at least one entity in the group changes. Information about all entities (both entities for which a change occurred and entities for which no change occurred) is passed to the notification

SA_TRACK_CHANGES_ONLY The notification callback is invoked each time at least one change occurs in the membership of the group or one attribute of at least one entity in the group changes. Only information about entities that changed is passed in the notification callback


AIS Track FunctionsSaAisErrorT sa<Area><Object>Track(


/* IN */ SaNameT *objectName, /* if needed */

/* IN */ SaUin8T trackFlags,

/* IN/OUT */ Sa<Area><Object>NotificationBufferT

*notificationBuffer);

Tracks the object in a way determined by the trackFlags parameter

If the flag SA_TRACK_CURRENT is set in the trackFlags parameter, initial status information of the tracked object is retrieved. If the notificationBuffer parameter is not NULL, this information is passed in the given buffer; otherwise, it is passed asynchronously via the callback notification API

NotificationBuffer:

typedef struct{

/* Optional fields specific to the service */

SaUint32T numberOfItems;

Sa<Area><Object>NotificationT *items;

} Sa<Area><Object>NotificationBufferT;

If items is NULL, the area service will allocate the buffer, and it is the responsibility of the calling process to free it

Status changes of the tracked object are always passed asynchronously through the callback notification API; however, if only the SA_TRACK_CURRENT is sent in the trackFlags parameter, a one-time status request is made. No subsequent status changes are notified, unless they have been requested in a preceding sa<Area><Object>Track() call


AIS Track Functionstypedef void (*Sa<Area><Object>TrackCallbackT)(

/* IN */ SaNameT *objectName, /* if needed */

/* IN */ Sa<Area><Object>NotificationBufferT *notificationBuffer,

/* IN */ SaUint32T numberOfMembers,

/* IN */ SaErrorT error);

The notificationBuffer contains the information of the tracked object according to the trackFlags parameter in the sa<Area><Object>Track() call. The notificationBuffer is allocated by the area service, and it cannot be accessed outside the callback routine

The numberOfMembers parameter contains the number of members in the group represented by the tracked object

SaAisErrorT sa<Area><Object>TrackStop(


/* IN */ SaNameT *objectName /* if needed */);

Stops tracking an object. No more callback notifications about object status changes will be sent to the process

This call is needed only if there was a preceding invocation to sa<Area><Object>Track() that used SA_TRACK_CHANGES or SA_TRACK_CHANGES_ONLY


AIS Name Type The SaNameT type represents object names in

AIS APIs

It allows for both human readable and other representations• Human readable representations include ASCII and

multi-byte character representations such as UTF-8

SaNameT structure

#define SA_MAX_NAME_LENGTH 256 typedef struct {

SaUint16T length;

SaUint8T value[SA_MAX_NAME_LENGTH];

} SaNameT;


AIS Name Type In the SaNameT structure, the length field refers to

the number of octets (bytes) used by the representation of the name in the name field

If the C character string representation is used, • The value field contains the characters in the string without

the terminating null character

• The length field contains the number of those characters

SaNameT example usageSaNameT myName;

myName.length = strlen(“fred”);

memcpy(myName.value, “fred”, myName.length);

error = saXxxCreateObject(myName, yyy, zzz);


AIS Object Names AIS runtime APIs use LDAP Distinguished Names

(DNs) to name objects• These LDAP DNs follow UTF-8 encoding conventions described

in IETF RFC 2253 (http://www.ietf.org/rfc/rfc2253.txt)

• The scope of these names is limited to a cluster. Hence, the names do not include a Relative Distinguished Name (RDN) that identifies the cluster

• Multi-valued RDNs are not supported

• LDAP names are encoded in SaNameT by using its UTF-8 representation without a terminating null character

The Information Model and System Management APIs also use LDAP DNs to name objects


AIS Object NamesRelative Distinguished Names for the AIS Services

Format: safApp = saf<Area>Service[:<varAppName>] where

• saf<Area>Service has the values defined in the table below

• <varAppName> is a string used to differentiate multiple implementations of the same serviceAIS Service safApp

Availability Management Framework safAmfService

Cluster Membership Service safCkptService

Checkpoint Service safClmService

Event Service safEvtService

Message Service safMsgService

Lock Service safLckService

Notification Service safNtfService

Log Service safLogService

Information Model Management Service safImmService


Summary

In this lesson you have learned about the following topics that provide the basis of the Application Interface Specification• Naming Conventions

• Programming/Usage Model

• Library Lifecycle API

• Error Codes

• Memory Allocation and Deallocation

• Version Mechanism

• Track API

• Name Types and Object Names

SAI-Overview-B.02.01 SA Forum Extended Training Materials Service Availability Interface Lesson 1.

Documents

Transcript of SAI-Overview-B.02.01 SA Forum Extended Training Materials Service Availability Interface Lesson 1.