Other Changes Developers Must Make When Using Threadsafe SK API

Message Registration

In the standard SwitchKit library, several functions that resulted in messages being sent to the LLC had to be issued only once during the life of the application. If the LLC were to be disconnected from the application or the LLC were restarted, the SwitchKit API took care of resending the messages to the LLC. The following functions are automatically resent (effectively, the SwitchKit API calls the function internally for the application) whenever a connection to an LLC is re-established:

• sk_appGroupRegister()

• sk_watchChannelGroup()

• sk_ignoreChannelGroup()

• sk_clearChannelGroup()

• sk_msgRegister()

• sk_pplComponentRegister()

• sk_pplTCAPRegister()

• sk_monitorChannel()

• sk_unmonitorChannel()

• sk_broadcastLoad()

• sk_registerAsRedundantApp()

• sk_deregisterAsRedundantApp()

Automatic Resending of Messages Disabled

When using the optional Threadsafe SwitchKit library, the automatic resending of messages feature is disabled. Instead, an application should register an LLC connection handler using the skts_setLLCConnectionHandler(). This connection handler is called any time the connection to the LLC is lost or re-established. When the handler is called, there is an indication of why the handler is called (SK_LLC_CONN_CREATED or SK_LLC_CONN_DESTROYED). When the indication is SK_LLC_CONN_CREATED, all initialization functions should be called, with the exception of skts_enableThreadSafeLib(), skts_setLLCConnectionHandler(), skts_createConnection() and any of the functions which establish handlers. A modified version of threadsafe example program (Modified Threadsafe Sample Code) is presented below. You will notice the following changes:

• Writing of a new handler function (llcConnectionHandler()) that is called whenever the connection state of an application to an LLC changes.

• The relocation of calls to registration functions, skts_msgRegister() (previously identified as step 3) and skts_watchChannelGroup() ( previously identified as step 4) from the main() function to the LLC connection handler. This way, the functions will be called each time the application establishes a connection with the LLC.

• In the main() function, code was added to define the LLC connection handler using the skts_setLLCConnectionHandler() function.

All other registrations for messages should take place in the LLC connection handler including registration for PPL component specific notification and registration for TCAP messages.

Modified Threadsafe Sample Code

The sample code follows. The changes are highlighted in bold.

// This is the LLC Connection handler which will be called any

// time the state of a connection to an LLC changes.

void llcConnectionHandler(int aConID, // conn ID of LLC

int aConState, // new connection state for LLC

void *aTag) { // tag specified when hdlr defined

if (aConState == SK_LLC_CONN_CREATED) {

// This handler will be called with this state

// any time a connection is established to an LLC.

// This includes the first time we establish a

// connection to the LLC, LLC switchover, recovery

// from temporary loss of connection, etc.

...

// (3) Register for unsolicited messages
status = skts_msgRegister(

SK_PPLEIS | SK_DS0S, // registration mask

aConID); // connection ID

if (status != OK) {
cout << "Error registering for messages from LLC"

<< endl;

// Continue to initialize. No point returning.
}

// (4) Register for new calls from a the specified

// channel group

status = skts_watchChannelGroupOnConnection(

"inboundChannelGroup", / / group name

aConID); // connection ID

}

if (status != OK) {
cout << "Error registering for messages from LLC"

<< endl;

// Continue to initialize. No point returning.
}

...

}

else if (aConState == SK_LLC_CONN_DESTROYED) {

// This handler will be called with this state

// any time a connection to an LLC is lost.

// This includes the temporary loss which occurs

// as part of LLC switchover in a redundant system

// Here you may want disable the sending of messages

// to the LLC the application just disconnected from.

// all attempts to send will fail until the connection

// is reestablished.

...

}

main(int argc, int argv) {

...

// (0) Initialize the threadsafe library.

// This function will initialize some global process level data and

// enable the detection of the mixing of Threadsafe with non Thread-

// safe functions. This function MUST be called first. Failure to call

// this function first or at all will result in unexpected behavior.

skts_enableThreadSafeAPI();

// (0.5) Set up the LLC connection handler

(void)sk_setLLCConnectionHandler(

NULL, // a user-defined value passed to hdlr func.

llcConnectionHandler); // LLC connection hdlr func.

// (1) Establish connections to LLC’s

int status = skts_createConnection(

1, // connection ID

-1, // application ID (allow LLC to select one)
0, // isForcedFlag (set to 0)
"host1", // primary LLC host name
1312, // primary LLC port number (1312 is default)
"host2", // redundant LLC hostname
1312); // redundant LLC port number (1312 is default)

if (status != 1)
{
cout << "Error has occurred creating connection to LLC" << endl;
return (-1);
}

...

// (2) Define Handler Functions – returns OK always

// (2a) Default Handler

(void)skts_setDefaultHandler(someTag, // tag for hdlr

someDefaultHandlerFunc); // handler func

// (2b) Group Handler to register for inbound calls

(void)skts_setGroupHandler("inboundChannelGroup", // group name

NULL, // tag

someGroupHandlerFunc); // handler func

...

...

// (5) SwitchKit receive loop

while(1) {

char *buffer; // where msg will be return if not handled

int size; // size of msg returned

void *data; // needed for function call. Not used by API.

int retConID; // conn ID of LLC the message was received from

status = skts_rcvAndDispatchAutoStorage(

&buffer, // contains packed msg if msg not handled

&size, // size of message returned

-1, // timeout - wait forever

&data, // Not currently used.
&retConID); // connection ID on which msg was rcvd

if (status != OK) {

// The code here is exactly the same as in

// Sample Code 1 and is excluded for brevity.

...

} // end if

} // end while

...

}

Linking a Multi-threaded Application

The ThreadSafe SwitchKit API library makes use of the Adaptive Communication Environment (ACE) library from the University of Washington, St. Louis (http://www.cs.wustl.edu/~schmidt/ACE.html) to provide the event dispatching and synchronization constructs. Any application using the threadsafe library must link with the ACE library provided as part of the distribution. In addition, the location of the ACE shared library must be reflected in the LD_LIBRARY_PATH so that the operating system can find the ACE library when the application is invoked.