Skip to main content
`Ctrl`+`K`

# 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 function 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.

## See Also

Setting Routines and Contexts, `PetscCtx`, `PetscCtxDestroyFn()`, `PeOp`, `PeNS`, `PetscInitialize()`, `DMGetApplicationContext()`, `DMSetApplicationContextDestroy()`

## 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