Sample Thread Framework Application

A Sample Thread Framework Application

EDD framework is a layer on the top of the thread framework. This layer provides basic functionality of the EDD which allows the application to use its API to monitor th e connections to NEP, receive data from the NEP and send data to NEP.

The design of the EDD framework in this section is an example of using thread framework. EDD Data Architecture.

Many other features used by EDD such as logging diagnostic messages, generating events and retrieving configuration variables are described in document -- MT-Safe Common Class Library, which is part of the framework also.

Essentially, the framework maintains one thread for each connection to NEP. A dedicated thread is generated at startup time to listen connecting requests initiated by NEP. These threads are generated from the classes inherited from ASC_ThreadAppl. Typically, the EDD application should subclass from these two classes to build the application specific classes. This is to be demonstrated in the section describing DCE API.

The classes used in this framework are:

EDD Connection Listening
Connection Handler Class

EDD connection listening class

This EDD_Listen class provides the functionality of listening to incoming connecting requests from NEP and generating the connection handler threads to handle connections to NEP. This is very similar to a server spawning a thread to handle a request. The object created from this class is attached to a DCE thread.

This class provides functionality to handle connection request both the UNIX domain socket and Internet domain socket. Once a request is accepted, the listener spawns an EDD_ConnHandler thread to handle the connection.

This is an abstract class that you must subclass from. The main reason for subclassing this class is to provide a method to instantiate connection handler objects, since you must subclass EDD_ConnHandler to build the application.

The following is the class definition.

Synopsis

class EDD_Listener : public ASC_ThreadAppl 
{
public:
EDD_Listener(char* Listener);
// This is the entry point which is called when the
// thread is up. It, in turn, calls function to 
// monitor the listening socket.
int threadMain(void **Rtn);
// This function has to be redefined by the 
// application to generate connection handler. 
// Usually, a new command is used to create a
// new connection handler object.
virtual EDD_ConnHandler *genConnHandler(const

ConnStartInfo &ConnInfo) = 0;

protected:
Diagnosis *m_Diag;
Event *m_Event;
Config m_Config;
private:
// This function is called by threadMain to 
// initialize the listening socket.
void initListener(void);
// This function retrieves listening file descriptor.
void getListenFileDes(int SocketFamily, char *IPAddr,

  int Port);

// Constructs listening socket for UNIX domain.
int unixDomainSocket(char *PathName);
// Constructs listening socket for internet domain.
int inetDomainSocket(char *HostIPAddr, short Port);
// This function accepts a request to establish a 
// socket connection to NEP. 
int newConnection(void);
// The following two connections are used by
// newConnection to establish a socket connection to NEP.
int unixSocketConnect(int SocketID);
int inetSocketConnect(int SocketID);
int m_FileDes;
};

Public methods

int threadMain(void **Rtn);

This function is invoked when the thread is up. It initializes the listening channel and then blocks the thread on UNIX system call accept(). The thread is woken up when a request is coming. Upon accepting the request, the thread spawns a connection handler thread to handle it. Most functions in the private section are directly or indirectly used by this function.

virtual EDD_ConnHandler *genConnHandler(const ConnStartInfo &ConnInfo) = 0;

This function is used to generate a connection handler thread. ConnInfo is passed to the new thread object to transfer the file descriptor. It returns the pointer to the new thread. The user has to redefine this function. Refer to the DCE API section for examples.

The following is the flow of the control:

ThreadMain() calls initListener().
initListener calls either unixDomainSocket or inetDomainSocket depending on the configuration.
Once the listening channel is established, newConnection is called to establish listening channel.
newConnection invokes either unixSocketConnect or inetSocketConnect to wait for the requests.
Once a connection is established, a connection handler is spawned to handle the connection.

Connection handler class

This is an abstract class that you derive the application from. You must redefine some member functions which are invoked for different transactions (see the Transaction chapter for detail). For example, when the NEP requests to establish a connection to a network element or a remove server, the member function connectReq is called. You redefine this function to establish the connection to network elements.

After the object of the class is created, it attaches to a thread. The object then invokes the readSocket member function which blocks the thread to wait for data coming from NEP. Based on the header information in data read, the object invokes proper functions redefined by the application to handle requests.

The following describes those member functions.

Synopsis

class EDD_ConnHandler : public ASC_ThreadAppl 
{
public:
EDD_ConnHandler(char *ConnectionName);
~EDD_ConnHandler(void){}
// This is the entry point of the thread.
int threadMain(void **Rtn);
// This function is called when the thread is just up, 
// so that the user may use this function to perform
// their own initializetion.
virtual void applInitialize(void) = 0;
// The user may use the following two functions to 
// save the application specific data. setApplData 
// calls the user defined deleteApplData internally
// to make sure that there is no memory leak.
void setApplData(void *ApplData);
void *getApplData(void) { return m_ApplData; }
// The user has to redefine this function to delete 
// the data that was saved using setApplData(). 
virtual void deleteApplData(void *ApplData) = 0;
// Redefine this function to clean up the application
// data. This function is called whenever the thread 
// is terminated.
virtual void cleanup(void) = 0;
// This function is called whenever NEP requests a
// connection to a remote server or network element. 
// The connection to the NEP is closed if this 
// function returns ASC_Fail.
virtual int connectReq(void) = 0;
// The user uses this function to retrieve connection
// parameters stored in tbl_comm_param of SARM database.
const char *getConnParam(const char *ParamLabel);
// This function is called whenever NEP requests to send
// data or perform some operation on remote server. The
// application has to redefine this one to provide 
// the service.
virtual int processDataReq(const unsigned char *Data,

  const int Len) = 0;

// This one allows the user to pass data to NEP.
int sendDataToNEP(const unsigned char *Data,

const int Len);

// This function is called whenever NEP requests to 
// close a connection to a remote server or network
// element. The connection to the NEP is closed 
// whenever this function is returned. 
virtual void disconnectReq(void) = 0;
// This function is provided for the user to close the
// connection to NEP whenever it detects that connection
// to remote server is gone.
void disconnectACK(void);
virtual void sendKeyReq(void *data, int len) = 0;
void setFileDes(const int FileDes){ m_FileDes=FileDes; }
const int getFileDes(void) { return m_FileDes; }
// These three objects are used by DCE routines to 
// log diagnostic messages and events and also 
// get configuration variables.
Diagnosis *m_Diag;
Event *m_Event;
Config m_Config;
protected:
private:
// send ACK and NACK to NEP
void connectACK(void);
void connectNACK(void);
// Retrieve EDD header
int getEddHeader(int &Len, int &Type);
// Build a EDD header to data to be sent to NEP.
int buildEddHeader(unsigned char **Buf, const

unsigned char *data, const int DataLen,
const int DataType);

// Retrive connection data. The data contains 
// parameters saved in  tbl_comm_param of SARM dB.
const char* getConnectionData(const int ExpectedLen);
// These two functions read and write to sockets 
// connect to NEP.
int readSocket(unsigned char *Buffer, const

int ExpectedLen);

int writeSocket(const unsigned char *Buffer, const

int Length);

// This function configures the socket.
int tuneFileDes(void);
char *m_ConnParam;
int m_DataType;
int m_FileDes;
void *m_ApplData;
};

Description

EDD_ConnHandler(pthread_t &ThreadID, EDD_ApplInit *ApplObj);

The constructor obtains the file descriptor from ApplObj. The file descriptor identifies the connection to be handled.

void threadMain(EDD_ApplInit *ApplObj);

This is the main routine that waits for a request coming from the message queue. After it receives a request, it invokes a corresponding transaction member function. It also manages to send connection ACK/NACK, disconnection ACK and terminates the thread when a connection is relinquished.

virtual void applInitialize(EDD_ApplInit *ApplObj){}

You can redefine this function to perform the application initialization. This function is invoked when the thread is just up.

virtual int connectReq(void) = 0;

You must redefine this function. It is invoked from threadMain whenever the NEP requests a connection to a network element or a remote server. Typically, you call getConnectParam to retrieve the connection parameters defined in tbl_comm_param and then establish the connection. This function returns ASC_Succeed, if a connection is established successfully, otherwise, it returns ASC_Fail. When it returns ASC_Fail, the connection to NEP is removed and the thread is terminated.

char *getConnectParam(char *ParamLabel);

This function is provided to retrieve the connection parameters defined in tbl_comm_param. The ParamLabel is defined in tbl_comm_param. It returns a pointer to the value of the parameter or a 0 if the parameter is not defined.

virtual int processDataReq(void *Data, int Len) = 0;

You must redefine this function. It is invoked whenever the NEP requests to send data to or perform some operation on a network element or a remote server. The argument Data points to data coming from NEP and Len is the length of the data in byte. This function returns ASC_Fail, if it detects that the connection to the network element is unavailable. This event triggers the thread to close the connection to the NEP and exit.

void sendDataToNEP(void *Data, int Len);

You can use this function to send data back to the NEP. Typically, you forward the data coming from a network element or remote server to the NEP.

virtual void disconnectReq(void) = 0;

You must redefine this function. It is invoked whenever NEP requests to close the connection to a network element which is handled by this object. Once this function returns, the thread closes the connection to NEP and exits.

void setApplData(void *ApplData){ m_ApplData=ApplData; }
void *getApplData(void) { return m_ApplData; }
virtual void deleteApplData(void *ApplData) = 0;

You call these three functions to save the data specific to the application. Typically, this data is used between two calls to processDataReq or the data needed by the application during the thread life time. It is the application's responsibility to coordinate the use of this data field for different purposes.

You must redefine the deleteApplData function, since setApplData and the destructor calls this function to delete the application data. If you delete the data from outside of this function, you must set m_ApplData to 0.

void cleanup(void);

This function cleans up all spaces allocated for the application to execute RPCs.

Three public member attributes are used by the framework and the application to log diagnostic messages, generate events and retrieve configuration variables.

All functions in the private section are used to handle the connections to NEP.