TclMP: C interface for MPIs
The MPI Tcl Type
When TclMP is loaded into the interpreter, the MPI type is already registered in the interpreter as a valid Tcl data type.
All calculations within TclMP are based upon LibGMP. The documentation of LibGMP contains detailed information on how to work with the internal data types of it.
These Functions exist to access it (include mpi.h):
Tcl_Obj*Tcl_NewMPIObj(mpz_t inmp)
Tcl_Obj*Tcl_NewMPINullObj()
mpz_t*Tcl_GetMPIFromObj(Tcl_Interp*interp,Tcl_Obj*objptr)
void Tcl_SetMPIObj(Tcl_Obj*objptr,mpz_t inmp)
- inmp - a LibGMP MPI (mpz_t) to be copied into the object
- interp - the Tcl interpreter
- objptr - pointer to the Tcl Object concerned
Tcl_NewMPIObj creates a new MPI Tcl Object and copies the MPI from its argument into the new object. Tcl_NewMPINullObject creates a new MPI object and initializes it with 0. Tcl_SetMPIObj changes the Tcl MPI object to reflect the number in its inmp argument.
Tcl_GetMPIFromObj returns a pointer to the internal representation of the Tcl MPI object. If you manipulate the MPI you must make sure the string representation of the object is invalidated, using Tcl_InvalidateStringRep.
Extensions
All MPI functions that are visible from Tcl are created through a meta-script in the src/mpi subdirectory. Each of these scripts includes mkop.tcl first. This file defines two functions: op and finish.
op name args descr decl code
- name - is the name of the new function (it will end up as ::mpi::name)
- args - are the arguments it takes
- descr - is a short description that is registered with ::mpi::info
- decl - is some space for C level variable declarations, do not write code in there, since op will generate more declarations after those you entered
- code - is the C code that should return your result
The arguments to the function you define are automatically converted into MPIs - if an argument is named a, it will be available as mpz_t*mpa. If you do not wish an argument to be interpreted than prefix it with an asterisk (*). If you do so: if the argument can be a number and you convert it using another internal representation (eg. with Tcl_GetIntFromObj), make sure you call Tcl_GetMPIFromObj again for all other MPIs, because Tcl shares Objects between literals and the pointer will be invalid after that transformation.
In the C code you can use two paths of exit: the macro ERR(x) takes a static string, sets it as result and returns with TCL_ERROR. The local variable ret (Tcl_Obj*) must otherwise be set to a valid Tcl Object that you wish to return.
finish initname
The finish function creates the code to initialize and register all functions that were created with op to the Tcl Interpreter.
After you have written your script you need to:
- register its C-output in Makefile.am in the src directory (if your script is mpi/mympi.tcl then the output will be mpi/mympi.c)
- enter your init function in the init function of mpi/mpi.c
- enter #include mympi.inf in the definition of the info function in mpi/mpi.c
- recompile...
Internal Storage
In the Tcl_Obj structure MPIs are stored in the internalRep.otherValuePtr pointer. The internal functions handle all conversion, allocation, and freeing of this pointer, so you normally don't need to access it directly.