Compliance with LAL Specifications

We suggest that the functions within the shared object library loaded by wrapperAPI conform to the LAL specification. Each function should have return type void and four arguments:

a status structure
an input structure
an output structure
a parameter structure

For functions where the current return value is output, e.g. IndexFilters, the output should be part of the output structure. Example: the function TemplateFilters would become

void TemplateFilters (Status *status, Input *data, Output *results, TemplateFiltersParams *params)

where the TemplateFiltersParams structure would be

typedef struct
tagTemplateFiltersParams
{
   INT4 beginTemplate;
   INT4 endTemplate;
   MPI_Comm *comm;
}
TemplateFiltersParams

The main reason for this is:

The functions within the shared libraries will be part of LAL. It is therefore desirable to have them conform to the LAL standard, primarily for consistency within that software development effort. (In our opinion, the distributed nature of the development effort makes this extremely important.)

We realize that return type void will break the current wrapperAPI requirements in which functions have integer return values. One possible solution to this is described below.

Error handling and logging

While discussing this possible change at UWM, we identified a problem with the current baseline requirements for the shared library functions:

There appears to be no way for the LDAS system to handle the information in the LAL status structure which will be vital for the scientists developing the shared libraries to debug the code if/when problems arise.

In our opinion, this issue provides further motivation for moving over to the LAL calling standard for the five functions in the shared object libraries since *status can then be parsed at the wrapperAPI level. We have a suggestion for how this might be done.

Possible solution for return values and error handling

LDAS would contain an additional function (which we can help write)

CHAR statusMessage[1024] = "";
CHAR statusError[];

INT4 CheckLALStatusPtr (Status *status, CHAR *statusMessage, CHAR *statusError)

that would be executed after each call to a function in the shared library.

CheckLALStatusPtr would parse the LAL status structure. It would return

0 if status was nominal (i.e. no error in function).
-1 if a warning occurred and a warning message stored in statusMessage.
1 if an error occurred, an error message in statusMessage and parsed version of the contents of the LAL status structure in statusError.

statusMessage would be used in the same way as the current message variables to log short messages and statusError would be logged in the event of an error for the developer of the library.

If this method were used, the pseudo code for wrapperAPI would be as follows. (Note: in this psuedo-code, only TemplateFilters() is fully LAL compliant. The other functions also need to be made fully compliant.)

/ wrapperAPI pseudo-code
extern "C" {
#include "wrapperInterface.h"
} // On every node in MPI_COMM_WORLD perform:
{
parseCommandLineOptions();
loadDynamicSharedObjects();
FilterInit( status, initParams );
errorTestInit( CheckLALStatusPtr( status, initMessage, initError ) );
IndexFilters( status, totalTemplates );
errorTestIndex( CheckLALStatusPtr( status, indexMessage, indexError ) );
LBComm = createLoadBalanceCommunicator();
}
// On every node in Load Balance Communicator perform:
{
while ( notFinished() ) {
ConditionData( status, data );
errorTestDC( CheckLALStatusPtr( status, conditionMessage, conditionError ) );
TemplateFilters( status, data, result, tfParams );
errorTestTF( CheckLALStatusPtr( status, filterMessage, filterError ) );
// run on master node only
{
masterNodeGathersResults();
masterNodeCalculatesLoad();
masterNodeInformsLDASmpiAPI();
masterSendsResultsToResultAPI();
}
// On every node in MPI_COMM_WORLD perform:
{ LBComm = createLoadBalanceCommunicator(); }
} /* end of while loop */ // On every node in MPI_COMM_WORLD perform:
{
FreeFilters ( status );
errorTestFree( CheckLALStatusPtr( status, freeMessage, freeError ) );
MPI_Finish;
}

Page created on: Tue Apr 11 21:15:48 CDT 2000 by duncan
Last modified: Tue Apr 11 23:04:43 CDT 2000 by duncan