FORTRAN Interface
With any change to the user API of Zoltan, the Fortran interface should
be modified to reflect the change. This section contains information about
the implementation of the Fortran interface which should cover most situations.
If you have questions or need assistance, contact william.mitchell@nist.gov.
If changes are made to functions that are called by zdrive,
then the changes should also be made to
zfdrive. Changes to the
Fortran interface can be tested by building and running zfdrive,
if the changes are in functions called by zfdrive.
The zfdrive program
works the same way as zdrive
except that it is restricted to the
Chaco
examples and simpler input files.
Any changes in the interface should also be reflected in the Fortran
API definitions in the Zoltan User's Guide.
Structures
All structures in the API have a corresponding user-defined type in the
Fortran interface. If a new structure is added, then modifications will
be required to fort/fwrap.fpp and fort/cwrap.c. In these
files, search for Zoltan_Struct
and "do like it does."
An explanation of how structures are handled may help. The Fortran user-defined
type for the structure simply contains the address of the structure, i.e.,
the C pointer returned by a call to create the structure. Note that the
user does not have access to the components of the structure, and can only
pass the structure to functions. Within the Fortran structure, the
address is stored in a variable of type(Zoltan_PTR), which is a character
string containing one character for each byte of the address. This gives
the best guarantee of portability under the Fortran and C standards. Also,
to insure portability of passing character strings, the character string
is converted to an array of integers before passing it between Fortran
and C. The process of doing this is most easily seen by looking at Zoltan_Destroy,
which has little else to clutter the code.
Modifications to an existing Zoltan
interface function
If the argument list or return type of a user-callable function in Zoltan
changes, the same changes must be made in the Fortran interface routines.
This involves changes in two files: fort/fwrap.fpp and fort/cwrap.c.
In these files, search for the function name with the prefix Zoltan_ omitted,
and modify the argument list, argument declarations, return type, and call
to the C library function as appropriate. When adding a new argument, if
there is not already an argument of the same type, look at another
function that does have an argument of that type for guidance.
Removing a Zoltan interface function
If a user callable function is removed from the Zoltan library, edit fort/fwrap.fpp
and fort/cwrap.c to remove all references to that function.
Adding a new Zoltan interface function
Adding a new function involves changes to the two files fort/fwrap.fpp
and fort/cwrap.c. Perhaps the easiest way to add a new function
to these files is to pick some existing function, search for all occurrences
of it, and use that code as a guide for the implementation of the interface
for the new function. Zoltan_LB_Point_Assign
is a nice minimal function to use as an example. Use a case insensitive
search on the name of the function without the Zoltan_LB_ prefix, for example
point_assign.
Here are the items in fwrap.fpp:
-
public statement: The name of the function should be included in the list
of public entities.
-
interface for the C wrapper: Copy one of these and modify the function
name, argument list and declarations for the new function. The name is
of the form Zfw_LB_Point_Assign (fw stands for Fortran wrapper).
-
generic interface: This assigns the function name to be a generic name
for one or more module procedures.
-
module procedure(s): These are the Fortran-side wrapper functions. Usually
there is one module procedure of the form Zf90_LB_Point_Assign. If
one argument can have more than one type passed to it (for example, it
is type void in the C interface), then there must be one module procedure
for each type that can be passed. These are distinguished by appending
a digit to the end of the module procedure name. If n arguments can have
more than one type, then n digits are appended. See Zoltan_LB_Free_Part
for example. Generally the module procedure just calls the C-side wrapper
function, but in some cases it may need to coerce data to a different
type (e.g., Zoltan_Struct),
or may actually do real work (e.g., Zoltan_LB_Free_Part).
Here are the items in cwrap.c:
-
name mangling: These are macros to convert the function name from the case
sensitive C name (for example, Zfw_LB_Point_Assign) to the mangled
name produced by the Fortran compiler. There are four of these for each
function:
-
lowercase (zfw_lb_point_assign),
-
uppercase (ZFW_LB_POINT_ASSIGN),
-
lowercase with underscore (zfw_lb_point_assign_), and
-
lower case with double underscore (zfw_point_assign__ but the
second underscore is appended only if the name already contains an underscore,
which will always be the case for names starting with Zfw_).
-
C-side wrapper function: Usually this just calls the Zoltan library function
after coercing the form of the data (for example, constructing the pointer
to Zoltan_Struct and call-by-reference
to call-by-value conversions).
Query functions
If a query function is added, deleted or changed, modifications must be
made to fort/fwrap.fpp and fort/cwrap.c, similar to the modifications
for interface functions, and possibly also include/zoltan.h and zz/zz_const.h.
Here are the places query functions appear in fwrap.fpp:
-
public statement for the ZOLTAN_FN_TYPE
argument: These are identical to the C enumerated type.
-
definition of the ZOLTAN_FN_TYPE
arguments: There are two groups of these, one containing subroutines (void
functions) and one containing functions (int functions). Put the new symbol
in the right category. The value assigned to the new symbol must agree
exactly with where the symbol appears in the order of the enumerated type.
Here are the places query functions appear in cwrap.c:
-
reverse wrappers: These are the query functions that are actually called
by the Zoltan library routines when the query function was registered from
Fortran. They are just wrappers to call the registered Fortran routine,
coercing argument types as necessary. Look at Zoltan_Num_Edges_Fort_Wrapper
for an example.
-
Zfw_Set_Fn: This has a switch based on the value of the ZOLTAN_FN_TYPE
argument to set the Fortran query function and wrapper in the Zoltan_Struct.
In zz/zz_const.h, if a new field is added to the structures for
a new query function, it should be added in both C and Fortran forms. In
include/zoltan.h, if a new typedef for a query function is added,
it should be added in both C and Fortran forms. See these files for examples.
Enumerated types and defined constants
Enumerated types and defined constants that the application uses as the
value for an arguments must be placed in fwrap.fpp with the same
value. See ZOLTAN_OK
for an example.
[Table of Contents | Next:
C++ Interface | Previous:
Migration Tools | Privacy and Security]