PetscCtxRt#

indicates an argument that returns a pointer to a C struct (or Fortran derived type) which is generally an application context

Notes#

A PETSc object (in C or Fortran) can be used as a PETSc context

This should not be used for functions that return pointers to arrays of unknown type. Thus it is used for, for example, KSPGetApplicationContext() but not used for DMNetworkGetComponent()

A PETSc object (in C or Fortran) can be used as a PETSc context

It is also used for functions that destroy an application context. For example, the destroy function passed to DMSetApplicationContextDestroy() which has a prototype of PetscCtxDestroyFn()

This typedef is not part of the PETSc public API and should only be used in PETSc source code.

For pointers to arrays of unknown type and for functions that return PETSc internal objects that are opaque to users, such as KSPMonitorDynamicToleranceCreate() a void ** should be used.

Fortran Notes#

A Fortran code that calls a function with a PetscCtxRt argument must declare the variable ctx with

   type(AppType), pointer :: ctx

where AppType is a Fortran derived type.

If one passes a PETSc function with a PetscCtxRt argument as an argument in Fortran one must use the function named suffixed with Cptr, for example KSPConvergedDefaultDestroyCptr, see src/ksp/ksp/tutorials/ex1f.F90.

Developer Notes#

C++ compilers generate a warning or error if one passes a pointer to a pointer to a specific type (instead of void), for example,

   extern calledfunction(void **);
   SomeCtx *ctx;
   calledfunction(&ctx);   << warning that it is passing a pointer to a pointer to a SomeCtx instead of a void **

By using the common practice of prototyping the function as

   extern calledfunction(void *);

the warning message is averted.

PetscCtxRt is used instead of void * in PETSc code to enhance the clarity of the PETSc source code since void * serves so many different roles. The getAPI() code processor also uses the variable type to generate correct bindings for other languages.

The Fortran C stub and Fortran interface definition generated for functions with a PetscCtxRt argument are the C function name suffixed with Cptr, for example KSPConvergedDefaultDestroyCptr. The Fortran user API is a macro with the original C funtion name, for example, KSPConvergedDefaultDestroy that calls the KSPConvergedDefaultDestroyCptr version and then calls c_f_pointer() to handle the equivalent of a void** cast to the users Fortran derived type argument.

Level#

developer

Location#

include/petscsys.h

Examples#

src/snes/tutorials/ex58.c

Index of all Sys routines
Table of Contents for all manual pages
Index of all manual pages