Header LALGSL.h

Detailed Description

Provides macros for integrating the GSL error handler with the LAL status structure.

Author

Creighton, J. D. E.

Synopsis

#include <lal/LALGSL.h>

This header provides macros and functions for tracking and reporting the runtime status of a GSL calls. The intent is simultaneously to standardize the error reporting, and to make the reporting as transparent as possible to people coding individual routines.

Please always use these macros when making a GSL call within LAL. This will ensure that the LAL functions always have the same behaviour and will also ensure that the LAL functions are reenterant and threadsafe (when LAL is configured appropriately).

GSL function calls

The behaviour of GSL functions depends on the error handler that has been assigned. In order that LAL functions always have the same behaviour, it is necessary to use a LAL-specific GSL error handler. This error handler populates a LAL status structure with the GSL error message and code so that GSL functions behave much the same way as LAL functions. After the GSL functions are called, the error handler needs to be restored to the original handler so that the program calling the LAL routine has the same error handler after the LAL function was called as it did before the LAL function was called.

This module provides a simple set of macros and the default LAL GSL error handler. The macros provide a standard way to assign the LAL GSL error handler before a GSL function call and to restore the original handler after the call.

Note that changing the GSL error handler is not a thread-safe action. Therefore it is necessary to block other threads from performing GSL function calls while one thread has changed the handler. These macros ensure that such blocking is done for GSL function calls within other LAL routines if LAL is configured with the –enable-pthread-lock flag. See below for instructions on how to make other GSL function calls outside LAL thread-safe when used with LAL.

ATTATCHSTATUSPTR( status );
CALLGSL( gsl_function( x ), status );
CHECKSTATUSPTR( status );
DETATCHSTATUSPTR( status );

Note that the LAL function must attach (and detach) a status pointer as if a LAL routine were called. Note also that you need to use the CHECKSTATUSPTR macro to check the status of the call. The equivalent to the TRY macro for GSL functions is the TRYGSL macro, which is used as follows:

ATTATCHSTATUSPTR( status );
TRYGSL( gsl_function( x ), status );
DETATCHSTATUSPTR( status );

Prototypes
void	LALGSLErrorHandler (UNUSED const char *reason, const char *file, int line, int my_gsl_error)
	LAL GSL error handler. More...

Files
file	LALGSLTest.c

Function Documentation

LALGSLErrorHandler()

void LALGSLErrorHandler	(	UNUSED const char *	reason,
		const char *	file,
		int	line,
		int	my_gsl_error
	)

LAL GSL error handler.

Synopsis

extern LALStatus *lalGSLGlobalStatusPtr;
#include <lal/LALConfig.h>
#ifdef LAL_PTHREAD_LOCK
#include <pthread.h>
extern pthread_mutex_t lalGSLPthreadMutex;
#endif

Description

The function LALGSLErrorHandler() is the standard GSL error handler for GSL functions called within LAL. Its function is to take the GSL error code and information and translate them into equivalent aspects of the LAL status structure. The status structure that is currently identified by lalGSLGlobalStatusPtr is populated. This global variable is to be set to the current status pointer prior to invocation of the GSL function. In addition, the GSL error handler must be set to the LAL GSL error handler prior to the invocation of the GSL function. Both of these tasks can be done with the macros provided in the header Header LALGSL.h. However, doing so is not thread-safe. Thus the macros use the mutex lalGSLPthreadMutex to block other threads from making GSL calls from within LAL functions while one thread has set the GSL error handler and global status pointer. This mutex must also be used to block any non-LAL GSL function calls from other threads or else they may be called with the LAL GSL error handler in effect.

Definition at line 70 of file LALGSL.c.