Support functions and data structures

Data Structures
struct	tclmpi_comm
struct	tclmpi_dblint
struct	tclmpi_intint
struct	tclmpi_req

Macros
#define	TCLMPI_LABEL_SIZE   32
#define	TCLMPI_TOZERO   -4
#define	TCLMPI_ABORT   -3
#define	TCLMPI_ERROR   -2
#define	TCLMPI_INVALID   -1
#define	TCLMPI_NONE   0
#define	TCLMPI_AUTO   1
#define	TCLMPI_INT   2
#define	TCLMPI_INT_INT   3
#define	TCLMPI_DOUBLE   4
#define	TCLMPI_DOUBLE_INT   5
#define	TCLMPI_CONV_CHECK(type, in, out, assign)

Typedefs
typedef struct tclmpi_comm	tclmpi_comm_t
typedef struct tclmpi_dblint	tclmpi_dblint_t
typedef struct tclmpi_intint	tclmpi_intint_t
typedef struct tclmpi_req	tclmpi_req_t

Functions
static const char *	mpi2tcl_comm (MPI_Comm comm)
static MPI_Comm	tcl2mpi_comm (const char *label)
static const char *	tclmpi_add_comm (MPI_Comm comm)
static int	tclmpi_del_comm (const char *label)
static int	tclmpi_get_op (const char *opstr, MPI_Op *op)
static const char *	tclmpi_add_req ()
static tclmpi_req_t *	tclmpi_find_req (const char *label)
static int	tclmpi_del_req (tclmpi_req_t *req)
static int	tclmpi_datatype (const char *type)
static int	tclmpi_errcheck (Tcl_Interp *interp, int ierr, Tcl_Obj *obj)
static int	tclmpi_commcheck (Tcl_Interp *interp, MPI_Comm comm, Tcl_Obj *obj0, Tcl_Obj *obj1)
static int	tclmpi_typecheck (Tcl_Interp *interp, int type, Tcl_Obj *obj0, Tcl_Obj *obj1)

Variables
static tclmpi_comm_t *	first_comm = NULL
static tclmpi_comm_t *	last_comm = NULL
static int	tclmpi_comm_cntr = 0
static MPI_Comm	MPI_COMM_INVALID
static tclmpi_req_t *	first_req = NULL
static int	tclmpi_req_cntr = 0
static int	tclmpi_conv_handler = TCLMPI_ERROR
static char	tclmpi_errmsg [MPI_MAX_ERROR_STRING]

Detailed Description

Macro Definition Documentation

TCLMPI_ABORT

#define TCLMPI_ABORT   -3

abort on problems

TCLMPI_AUTO

#define TCLMPI_AUTO   1

the tcl native data type (string)

TCLMPI_CONV_CHECK

#define TCLMPI_CONV_CHECK	(		type,
			in,
			out,
			assign
	)

Value:

    if (Tcl_Get##type##FromObj(interp, in, out) != TCL_OK) {                                   \
        if (tclmpi_conv_handler == TCLMPI_TOZERO) {                                            \
            Tcl_ResetResult(interp);                                                           \
            assign = 0;                                                                        \
        } else if (tclmpi_conv_handler == TCLMPI_ABORT) {                                      \
            fprintf(stderr, "Error on data element %d: %s\n", i, Tcl_GetStringResult(interp)); \
            MPI_Abort(comm, i);                                                                \
        } else {                                                                               \
            return TCL_ERROR;                                                                  \
        }                                                                                      \
    }

Data conversion with with error handling

Parameters

type	Tcl data type for calling Tcl_Get<Type>FromObj()
in	pointer to input object for conversion
out	pointer to output storage for conversion
assign	target to assign a zero to for TCLMPI_TOZERO

This macro enables consistent handling of data conversions. It also queries the tclmpi_conv_handler variable to jump to the selected conversion error behavior. For TCLMPI_ERROR (the default) a Tcl error is raised and TclMPI returns to the calling function. For TCLMPI_ABORT and error message is written to stderr and parallel execution on the current communicator is terminated via MPI_Abort(). For TCLMPI_TOZERO the error is silently ignored and the data element handed in as assign parameter is set to zero.

TCLMPI_DOUBLE

#define TCLMPI_DOUBLE   4

floating point data type

TCLMPI_DOUBLE_INT

#define TCLMPI_DOUBLE_INT   5

data type for double/integer pair

TCLMPI_ERROR

#define TCLMPI_ERROR   -2

flag problems as Tcl errors

TCLMPI_INT

#define TCLMPI_INT   2

data type for integers

TCLMPI_INT_INT

#define TCLMPI_INT_INT   3

data type for pairs of integers

TCLMPI_INVALID

#define TCLMPI_INVALID   -1

not ready to handle data

TCLMPI_LABEL_SIZE

#define TCLMPI_LABEL_SIZE   32

Size of stringbuffer for tclmpi labels

TCLMPI_NONE

#define TCLMPI_NONE   0

no data type assigned

TCLMPI_TOZERO

#define TCLMPI_TOZERO   -4

convert problematic data items to zero

Typedef Documentation

tclmpi_comm_t

typedef struct tclmpi_comm tclmpi_comm_t

Linked list entry type for managing MPI communicators

tclmpi_dblint_t

typedef struct tclmpi_dblint tclmpi_dblint_t

Data type for maxloc/minloc reductions with a double and an integer

tclmpi_intint_t

typedef struct tclmpi_intint tclmpi_intint_t

Data type for maxloc/minloc reductions with two integers

tclmpi_req_t

typedef struct tclmpi_req tclmpi_req_t

Linked list entry type for managing MPI requests

Function Documentation

mpi2tcl_comm()

static const char* mpi2tcl_comm ( MPI_Comm  comm )

static

Translate an MPI communicator to its Tcl label.

Parameters

comm	an MPI communicator

Returns

the corresponding string label or NULL.

This function will search through the linked list of known communicators until it finds the (first) match and then returns the string label to the calling function. If a NULL is returned, the communicator does not yet exist in the linked list.

tcl2mpi_comm()

static MPI_Comm tcl2mpi_comm ( const char *  label )

static

Translate a Tcl communicator label into the MPI communicator it represents.

Parameters

label

the Tcl name for the communicator

Returns

the matching MPI communicator or MPI_COMM_INVALID

This function will search through the linked list of known communicators until it finds the (first) match and then returns the string label to the calling function. If a NULL is returned, the communicator does not yet exist in the linked list.

tclmpi_add_comm()

static const char* tclmpi_add_comm ( MPI_Comm  comm )

static

Add an MPI communicator to the linked list of communicators, if needed.

Parameters

comm	an MPI communicator

Returns

the corresponding string label or NULL.

This function will first call mpi2tcl_comm in order to see, if the communicator handed in, is already listed and return that communicators Tcl label string. If it is not yet lists, a new entry is added to the linked list and a new label of the format "tclmpi::comm%d" assigned. The (global/static) variable tclmpi_comm_cntr is incremented every time to make the communicator label unique.

tclmpi_add_req()

static const char* tclmpi_add_req ( )

static

Allocate and add an entry to the request map linked list

Returns

the corresponding string label or NULL.

This function will allocate and initialize a new linked list entry for the translation between MPI requests and their string representation passed to Tcl scripts. The assigned label of the for "tclmpi::req%d" will be returned. The (global/static) variable tclmpi_req_cntr is incremented every time to make the communicator label unique.

tclmpi_commcheck()

static int tclmpi_commcheck ( Tcl_Interp *  interp, MPI_Comm  comm, Tcl_Obj *  obj0, Tcl_Obj *  obj1  )

static

convenience function to report an unknown communicator as Tcl error

Parameters

interp	current Tcl interpreter
comm	MPI communicator
obj0	Tcl object representing the current command name
obj1	Tcl object representing the communicator as Tcl name

Returns

TCL_ERROR if the communicator is MPI_COMM_INVALID or TCL_OK

tclmpi_datatype()

static int tclmpi_datatype ( const char *  type )

static

convert a string describing a data type to a numeric representation

tclmpi_del_comm()

static int tclmpi_del_comm ( const char *  label )

static

Remove an MPI communicator from the linked list of communicators

Parameters

label

the Tcl name for the communicator

Returns

TCL_OK if deletion was successful, else TCL_ERROR

This function will find the entry in the linked list that matches the Tcl label string, remove it and free the associated resources.

tclmpi_del_req()

static int tclmpi_del_req ( tclmpi_req_t *  req )

static

remove tclmpi_req_t entry from the request linked list

Parameters

req	a pointer to the request in question

Returns

TCL_OK on succes, TCL_ERROR on failure

This function will search through the linked list of known MPI requests until it finds the (first) match and then will remove it from the linked and free the allocated storage. If TCL_ERROR is returned, the request did not exist in the linked list.

tclmpi_errcheck()

static int tclmpi_errcheck ( Tcl_Interp *  interp, int  ierr, Tcl_Obj *  obj  )

static

convert MPI error code to Tcl error error message and append to result

Parameters

interp	current Tcl interpreter
ierr	MPI error number. return value of an MPI call.
obj	Tcl object representing the current command name

Returns

TCL_OK if the "error" is MPI_SUCCESS or TCL_ERROR

This is a convenience wrapper that will use MPI_Error_string() to convert any error code returned from MPI function calls to the respective error class and that into a string. This string is appended to the Tcl result vector of the current command. Should be called after each MPI call. Since we change error handlers on all communicators to not result in fatal errors, we have to generate Tcl errors instead (which can be caught).

tclmpi_find_req()

static tclmpi_req_t* tclmpi_find_req ( const char *  label )

static

translate Tcl representation of an MPI request to request itself.

Parameters

label

the Tcl name for the communicator

Returns

a pointer to the matching tclmpi_req_t structure

This function will search through the linked list of known MPI requests until it finds the (first) match and then returns a pointer to this data. If NULL is returned, the communicator does not exist in the linked list.

tclmpi_get_op()

static int tclmpi_get_op ( const char *  opstr, MPI_Op *  op  )

static

Translate TclMPI strings to MPI constants for reductions

Parameters

opstr	string constant describing the operator
op	pointer to location for storing the MPI constant

Returns

TCL_OK if the string was recognized else TCL_ERROR

This is a convenience function to consistently convert TclMPI string constants representing reduction operators to their corresponding MPI counterparts.

tclmpi_typecheck()

static int tclmpi_typecheck ( Tcl_Interp *  interp, int  type, Tcl_Obj *  obj0, Tcl_Obj *  obj1  )

static

convenience function to report an unknown data type as Tcl error

Parameters

interp	current Tcl interpreter
type	TclMPI data type
obj0	Tcl object representing the current command name
obj1	Tcl object representing the data type as Tcl name

Returns

TCL_ERROR if the communicator is TCLMPI_NONE or TCL_OK

Variable Documentation

first_comm

tclmpi_comm_t* first_comm = NULL

static

First element of the communicator map list

first_req

tclmpi_req_t* first_req = NULL

static

First element of the list of generated requests

last_comm

tclmpi_comm_t* last_comm = NULL

static

Last element of the communicator map list

MPI_COMM_INVALID

MPI_Comm MPI_COMM_INVALID

static

Additional global communicator to detect unlisted communicators

tclmpi_comm_cntr

int tclmpi_comm_cntr = 0

static

Communicator counter. Incremented to get unique strings

tclmpi_conv_handler

int tclmpi_conv_handler = TCLMPI_ERROR

static

Selects what to do when a data element in a list cannot be successfully converted to the desired data type. Default is to throw a Tcl error.

tclmpi_errmsg

char tclmpi_errmsg[MPI_MAX_ERROR_STRING]

static

buffer for error messages.

tclmpi_req_cntr

int tclmpi_req_cntr = 0

static

Request counter. Incremented to get unique strings