Skip to main content
`Ctrl`+`K`

# PetscCallBack

Calls a user provided PETSc callback function and then checks the resulting error code, if it is non-zero it calls the error handler and returns from the current function with the error code.

## Synopsis

    #include <petscsys.h>
    void PetscCallBack(const char *functionname, PetscFunction(args))

Not Collective; No Fortran Support

## Input Parameters

- functionname - the name of the function being called, this can be a string with spaces that describes the meaning of the callback

- PetscFunction - user provided callback function that returns an error code

## Example Usage

      PetscCallBack("XXX callback to do something", a->callback(...));

## Notes

`PetscUseTypeMethod()` and `PetscTryTypeMethod()` are the preferred API for this functionality. But when the callback functions are associated with a `DMSNES` or `DMTS` this API must be used.

Once the error handler is called the calling function is then returned from with the given error code. Experienced users can set the error handler with `PetscPushErrorHandler()`.

`PetscCallBack()` should only be called in PETSc when a call is being made to a user provided call-back routine.

## Developer Note

It would be good to provide a new API for when the callbacks are associated with `DMSNES` or `DMTS` so this routine could be used less

## See Also

`SETERRQ()`, `PetscCheck()`, `PetscCall()`, `PetscAssert()`, `PetscTraceBackErrorHandler()`, `PetscCallMPI()` `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ`, `CHKERRA()`, `CHKERRMPI()`, `PetscCall()`, `PetscUseTypeMethod()`, `PetscTryTypeMethod()`

## Level

developer

## Location

include/petscerror.h

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