Actual source code: petscerror.h

  1: /*
  2:     Contains all error handling interfaces for PETSc.
  3: */
  4: #pragma once

  6: #include <petscmacros.h>
  7: #include <petscsystypes.h>

  9: #if defined(__cplusplus)
 10:   #include <exception> // std::exception
 11: #endif

 13: /* SUBMANSEC = Sys */

 15: #define SETERRQ1(...) PETSC_DEPRECATED_MACRO(3, 17, 0, "SETERRQ", ) SETERRQ(__VA_ARGS__)
 16: #define SETERRQ2(...) PETSC_DEPRECATED_MACRO(3, 17, 0, "SETERRQ", ) SETERRQ(__VA_ARGS__)
 17: #define SETERRQ3(...) PETSC_DEPRECATED_MACRO(3, 17, 0, "SETERRQ", ) SETERRQ(__VA_ARGS__)
 18: #define SETERRQ4(...) PETSC_DEPRECATED_MACRO(3, 17, 0, "SETERRQ", ) SETERRQ(__VA_ARGS__)
 19: #define SETERRQ5(...) PETSC_DEPRECATED_MACRO(3, 17, 0, "SETERRQ", ) SETERRQ(__VA_ARGS__)
 20: #define SETERRQ6(...) PETSC_DEPRECATED_MACRO(3, 17, 0, "SETERRQ", ) SETERRQ(__VA_ARGS__)
 21: #define SETERRQ7(...) PETSC_DEPRECATED_MACRO(3, 17, 0, "SETERRQ", ) SETERRQ(__VA_ARGS__)
 22: #define SETERRQ8(...) PETSC_DEPRECATED_MACRO(3, 17, 0, "SETERRQ", ) SETERRQ(__VA_ARGS__)
 23: #define SETERRQ9(...) PETSC_DEPRECATED_MACRO(3, 17, 0, "SETERRQ", ) SETERRQ(__VA_ARGS__)

 25: /*MC
 26:    SETERRQ - Macro to be called when an error has been detected,

 28:    Synopsis:
 29: #include <petscsys.h>
 30:    PetscErrorCode SETERRQ(MPI_Comm comm,PetscErrorCode ierr,char *message,...)

 32:    Collective

 34:    Input Parameters:
 35: +  comm    - An MPI communicator, use `PETSC_COMM_SELF` unless you know all ranks of another communicator will detect the error
 36: .  ierr    - nonzero error code, see the list of standard error codes in include/petscerror.h
 37: -  message - error message

 39:   Level: beginner

 41:    Notes:
 42:    This is rarely needed, one should use `PetscCheck()` and `PetscCall()` and friends to automatically handle error conditions.
 43:    Once the error handler is called the calling function is then returned from with the given error code.

 45:    Experienced users can set the error handler with `PetscPushErrorHandler()`.

 47:    Fortran Note:
 48:    `SETERRQ()` may be called from Fortran subroutines but `SETERRA()` must be called from the
 49:    Fortran main program.

 51: .seealso: `PetscCheck()`, `PetscAssert()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`,
 52:           `PetscError()`, `PetscCall()`, `CHKMEMQ`, `CHKERRA()`, `PetscCallMPI()`, `PetscErrorCode`
 53: M*/
 54: #define SETERRQ(comm, ierr, ...) \
 55:   do { \
 56:     PetscErrorCode ierr_seterrq_petsc_ = PetscError(comm, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr, PETSC_ERROR_INITIAL, __VA_ARGS__); \
 57:     return ierr_seterrq_petsc_ ? ierr_seterrq_petsc_ : PETSC_ERR_RETURN; \
 58:   } while (0)

 60: /*
 61:     Returned from PETSc functions that are called from MPI, such as related to attributes
 62:       Do not confuse PETSC_MPI_ERROR_CODE and PETSC_ERR_MPI, the first is registered with MPI and returned to MPI as
 63:       an error code, the latter is a regular PETSc error code passed within PETSc code indicating an error was detected in an MPI call.
 64: */
 65: PETSC_EXTERN PetscMPIInt PETSC_MPI_ERROR_CLASS;
 66: PETSC_EXTERN PetscMPIInt PETSC_MPI_ERROR_CODE;

 68: /*MC
 69:    SETERRMPI - Macro to be called when an error has been detected within an MPI callback function

 71:    No Fortran Support

 73:    Synopsis:
 74: #include <petscsys.h>
 75:    PetscErrorCode SETERRMPI(MPI_Comm comm,PetscErrorCode ierr,char *message,...)

 77:    Collective

 79:    Input Parameters:
 80: +  comm    - An MPI communicator, use `PETSC_COMM_SELF` unless you know all ranks of another communicator will detect the error
 81: .  ierr    - nonzero error code, see the list of standard error codes in include/petscerror.h
 82: -  message - error message

 84:   Level: developer

 86:    Note:
 87:    This macro is FOR USE IN MPI CALLBACK FUNCTIONS ONLY, such as those passed to `MPI_Comm_create_keyval()`. It always returns the error code `PETSC_MPI_ERROR_CODE`
 88:   which is registered with `MPI_Add_error_code()` when PETSc is initialized.

 90: .seealso: `SETERRQ()`, `PetscCall()`, `PetscCallMPI()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ`, `PetscErrorCode`
 91: M*/
 92: #define SETERRMPI(comm, ierr, ...) return ((void)PetscError(comm, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr, PETSC_ERROR_INITIAL, __VA_ARGS__), PETSC_MPI_ERROR_CODE)

 94: /*MC
 95:    SETERRA - Fortran-only macro that can be called when an error has been detected from the main program

 97:    Synopsis:
 98: #include <petscsys.h>
 99:    PetscErrorCode SETERRA(MPI_Comm comm,PetscErrorCode ierr,char *message)

101:    Collective

103:    Input Parameters:
104: +  comm    - An MPI communicator, so that the error can be collective
105: .  ierr    - nonzero error code, see the list of standard error codes in include/petscerror.h
106: -  message - error message in the printf format

108:    Level: beginner

110:    Notes:
111:    This should only be used with Fortran. With C/C++, use `SETERRQ()`.

113:    `SETERRQ()` may be called from Fortran subroutines but `SETERRA()` must be called from the
114:     Fortran main program.

116: .seealso: `SETERRQ()`, `SETERRABORT()`, `PetscCall()`, `CHKERRA()`, `PetscCallAbort()`, `PetscErrorCode`
117: M*/

119: /*MC
120:    SETERRABORT - Macro that can be called when an error has been detected,

122:    Synopsis:
123: #include <petscsys.h>
124:    PetscErrorCode SETERRABORT(MPI_Comm comm,PetscErrorCode ierr,char *message,...)

126:    Collective

128:    Input Parameters:
129: +  comm    - An MPI communicator, so that the error can be collective
130: .  ierr    - nonzero error code, see the list of standard error codes in include/petscerror.h
131: -  message - error message in the printf format

133:    Level: beginner

135:    Notes:
136:    This function just calls `MPI_Abort()`.

138:    This should only be called in routines that cannot return an error code, such as in C++ constructors.

140:    Fortran Note:
141:    Use `SETERRA()` in Fortran main program and `SETERRQ()` in Fortran subroutines

143:    Developer Note:
144:    In Fortran `SETERRA()` could be called `SETERRABORT()` since they serve the same purpose

146: .seealso: `SETERRQ()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, `PetscCall()`, `CHKMEMQ`, `PetscErrorCode`
147: M*/
148: #define SETERRABORT(comm, ierr, ...) \
149:   do { \
150:     (void)PetscError(comm, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr, PETSC_ERROR_INITIAL, __VA_ARGS__); \
151:     MPI_Abort(comm, ierr); \
152:   } while (0)

154: /*MC
155:   PetscCheck - Check that a particular condition is true

157:   Synopsis:
158: #include <petscerror.h>
159:   void PetscCheck(bool cond, MPI_Comm comm, PetscErrorCode ierr, const char *message, ...)

161:   Collective; No Fortran Support

163:   Input Parameters:
164: + cond    - The boolean condition
165: . comm    - The communicator on which the check can be collective on
166: . ierr    - A nonzero error code, see include/petscerror.h for the complete list
167: - message - Error message in printf format

169:   Level: beginner

171:   Notes:
172:   Enabled in both optimized and debug builds.

174:   As a general rule, `PetscCheck()` is used to check "usage error" (for example, passing an incorrect value as a function argument),
175:   `PetscAssert()` is used to "check for bugs in PETSc" (for example, is a value in a PETSc data structure nonsensical).
176:   However, for functions that are called in a "hot spot", for example, thousands of times in a loop, `PetscAssert()` should be used instead
177:   of `PetscCheck()` since the former is compiled out in PETSc's optimization code.

179:   Calls `SETERRQ()` if the assertion fails, so can only be called from functions returning a
180:   `PetscErrorCode` (or equivalent type after conversion).

182:  .seealso: `PetscAssert()`, `SETERRQ()`, `PetscError()`, `PetscCall()`, `PetscCheckAbort()`, `PetscErrorCode`
183: M*/
184: #define PetscCheck(cond, comm, ierr, ...) \
185:   do { \
186:     if (PetscUnlikely(!(cond))) SETERRQ(comm, ierr, __VA_ARGS__); \
187:   } while (0)

189: /*MC
190:   PetscCheckAbort - Check that a particular condition is true, otherwise prints error and aborts

192:   Synopsis:
193: #include <petscerror.h>
194:   void PetscCheckAbort(bool cond, MPI_Comm comm, PetscErrorCode ierr, const char *message, ...)

196:   Collective; No Fortran Support

198:   Input Parameters:
199: + cond    - The boolean condition
200: . comm    - The communicator on which the check can be collective on
201: . ierr    - A nonzero error code, see include/petscerror.h for the complete list
202: - message - Error message in printf format

204:   Level: developer

206:   Notes:
207:   Enabled in both optimized and debug builds.

209:   Calls `SETERRABORT()` if the assertion fails, can be called from a function that does not return an
210:   error code, such as a C++ constructor. usually `PetscCheck()` should be used.

212: .seealso: `PetscAssertAbort()`, `PetscAssert()`, `SETERRQ()`, `PetscError()`, `PetscCall()`, `PetscCheck()`, `SETERRABORT()`, `PetscErrorCode`
213: M*/
214: #define PetscCheckAbort(cond, comm, ierr, ...) \
215:   do { \
216:     if (PetscUnlikely(!(cond))) SETERRABORT(comm, ierr, __VA_ARGS__); \
217:   } while (0)

219: /*MC
220:   PetscAssert - Assert that a particular condition is true

222:   Synopsis:
223: #include <petscerror.h>
224:   void PetscAssert(bool cond, MPI_Comm comm, PetscErrorCode ierr, const char *message, ...)

226:   Collective; No Fortran Support

228:   Input Parameters:
229: + cond    - The boolean condition
230: . comm    - The communicator on which the check can be collective on
231: . ierr    - A nonzero error code, see include/petscerror.h for the complete list
232: - message - Error message in `printf()` format

234:   Level: beginner

236:   Notes:
237:   Equivalent to `PetscCheck()` if debugging is enabled, and `PetscAssume(cond)` otherwise.

239:   See `PetscCheck()` for usage and behaviour.

241:   This is needed instead of simply using `assert()` because this correctly handles the collective nature of errors under MPI

243: .seealso: `PetscCheck()`, `SETERRQ()`, `PetscError()`, `PetscAssertAbort()`, `PetscErrorCode`
244: M*/
245: #if PetscDefined(USE_DEBUG)
246:   #define PetscAssert(cond, comm, ierr, ...) PetscCheck(cond, comm, ierr, __VA_ARGS__)
247: #else
248:   #define PetscAssert(cond, ...) PetscAssume(cond)
249: #endif

251: /*MC
252:   PetscAssertAbort - Assert that a particular condition is true, otherwise prints error and aborts

254:   Synopsis:
255: #include <petscerror.h>
256:   void PetscAssertAbort(bool cond, MPI_Comm comm, PetscErrorCode ierr, const char *message, ...)

258:   Collective; No Fortran Support

260:   Input Parameters:
261: + cond    - The boolean condition
262: . comm    - The communicator on which the check can be collective on
263: . ierr    - A nonzero error code, see include/petscerror.h for the complete list
264: - message - Error message in printf format

266:   Level: beginner

268:   Note:
269:   Enabled only in debug builds. See `PetscCheckAbort()` for usage.

271: .seealso: `PetscCheckAbort()`, `PetscAssert()`, `PetscCheck()`, `SETERRABORT()`, `PetscError()`
272: M*/
273: #if PetscDefined(USE_DEBUG)
274:   #define PetscAssertAbort(cond, comm, ierr, ...) PetscCheckAbort(cond, comm, ierr, __VA_ARGS__)
275: #else
276:   #define PetscAssertAbort(cond, comm, ierr, ...) PetscAssume(cond)
277: #endif

279: /*MC
280:   PetscCall - Calls a PETSc function and then checks the resulting error code, if it is
281:   non-zero it calls the error handler and returns from the current function with the error
282:   code.

284:   Synopsis:
285: #include <petscerror.h>
286:   void PetscCall(PetscFunction(args))

288:   Not Collective

290:   Input Parameter:
291: . PetscFunction - any PETSc function that returns an error code

293:   Level: beginner

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

299:   `PetscCall()` cannot be used in functions returning a datatype not convertible to
300:   `PetscErrorCode`. For example, `PetscCall()` may not be used in functions returning void, use
301:   `PetscCallAbort()` or `PetscCallVoid()` in this case.

303:   Example Usage:
304: .vb
305:   PetscCall(PetscInitiailize(...)); // OK to call even when PETSc is not yet initialized!

307:   struct my_struct
308:   {
309:     void *data;
310:   } my_complex_type;

312:   struct my_struct bar(void)
313:   {
314:     PetscCall(foo(15)); // ERROR PetscErrorCode not convertible to struct my_struct!
315:   }

317:   PetscCall(bar()) // ERROR input not convertible to PetscErrorCode
318: .ve

320:   It is also possible to call this directly on a `PetscErrorCode` variable
321: .vb
322:   PetscCall(ierr);  // check if ierr is nonzero
323: .ve

325:   Should not be used to call callback functions provided by users, `PetscCallBack()` should be used in that situation.

327:   `PetscUseTypeMethod()` or `PetscTryTypeMethod()` should be used when calling functions pointers contained in a PETSc object's `ops` array

329:   Fortran Notes:
330:     The Fortran function from which this is used must declare a variable PetscErrorCode ierr and ierr must be
331:     the final argument to the PETSc function being called.

333:     In the main program and in Fortran subroutines that do not have ierr as the final return parameter one
334:     should use `PetscCallA()`

336:   Example Fortran Usage:
337: .vb
338:   PetscErrorCode ierr
339:   Vec v

341:   ...
342:   PetscCall(VecShift(v,1.0,ierr))
343:   PetscCallA(VecShift(v,1.0,ierr))
344: .ve

346: .seealso: `SETERRQ()`, `PetscCheck()`, `PetscAssert()`, `PetscTraceBackErrorHandler()`, `PetscCallMPI()`,
347:           `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ`, `CHKERRA()`,
348:           `CHKERRMPI()`, `PetscCallBack()`, `PetscCallAbort()`, `PetscCallVoid()`
349: M*/

351: /*MC
352:    PetscCallA - Fortran-only macro that should be used in the main program to call PETSc functions instead of using
353:    PetscCall() which should be used in other Fortran subroutines

355:    Synopsis:
356: #include <petscsys.h>
357:    PetscErrorCode PetscCallA(PetscFunction(arguments,ierr))

359:    Collective

361:    Input Parameter:
362: .  PetscFunction(arguments,ierr) - the call to the function

364:   Level: beginner

366:    Notes:
367:    This should only be used with Fortran. With C/C++, use `PetscCall()` always.

369:    Use `SETERRA()` to set an error in a Fortran main program and `SETERRQ()` in Fortran subroutines

371: .seealso: `SETERRQ()`, `SETERRA()`, `SETERRABORT()`, `PetscCall()`, `CHKERRA()`, `PetscCallAbort()`
372: M*/

374: /*MC
375:   PetscCallBack - Calls a user provided PETSc callback function and then checks the resulting error code, if it is non-zero it calls the error
376:   handler and returns from the current function with the error code.

378:   Synopsis:
379: #include <petscerror.h>
380:   void PetscCallBack(const char *functionname,PetscFunction(args))

382:   Not Collective; No Fortran Support

384:   Input Parameters:
385: + functionname - the name of the function being called, this can be a string with spaces that describes the meaning of the callback
386: - PetscFunction - user provided callback function that returns an error code

388:   Example Usage:
389: .vb
390:   PetscCallBack("XXX callback to do something",a->callback(...));
391: .ve

393:   Level: developer

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

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

401: .seealso: `SETERRQ()`, `PetscCheck()`, `PetscCall()`, `PetscAssert()`, `PetscTraceBackErrorHandler()`, `PetscCallMPI()`
402:           `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ`, `CHKERRA()`, `CHKERRMPI()`, `PetscCall()`
403: M*/

405: /*MC
406:   PetscCallVoid - Like `PetscCall()` but for functions returning `void`

408:   Synopsis:
409: #include <petscerror.h>
410:   void PetscCall(PetscFunction(args))

412:   Not Collective; No Fortran Support

414:   Input Parameter:
415: . PetscFunction - any PETSc function that returns an error code

417:   Example Usage:
418: .vb
419:   void foo()
420:   {
421:     KSP ksp;

423:     PetscFunctionBeginUser;
424:     // OK, properly handles PETSc error codes
425:     PetscCallVoid(KSPCreate(PETSC_COMM_WORLD, &ksp));
426:     PetscFunctionReturn(PETSC_SUCCESS);
427:   }

429:   PetscErrorCode bar()
430:   {
431:     KSP ksp;

433:     PetscFunctionBeginUser;
434:     // ERROR, Non-void function 'bar' should return a value
435:     PetscCallVoid(KSPCreate(PETSC_COMM_WORLD, &ksp));
436:     // OK, returning PetscErrorCode
437:     PetscCall(KSPCreate(PETSC_COMM_WORLD, &ksp));
438:     PetscFunctionReturn(PETSC_SUCCESS);
439:   }
440: .ve

442:   Level: beginner

444:   Notes:
445:   Has identical usage to `PetscCall()`, except that it returns `void` on error instead of a
446:   `PetscErrorCode`. See `PetscCall()` for more detailed discussion.

448:   Note that users should prefer `PetscCallAbort()` to this routine. While this routine does
449:   "handle" errors by returning from the enclosing function, it effectively gobbles the
450:   error. Since the enclosing function itself returns `void`, its callers have no way of knowing
451:   that the routine returned early due to an error. `PetscCallAbort()` at least ensures that the
452:   program crashes gracefully.

454: .seealso: `PetscCall()`, `PetscErrorCode`
455: M*/
456: #if defined(PETSC_CLANG_STATIC_ANALYZER)
457: void PetscCall(PetscErrorCode);
458: void PetscCallBack(const char *, PetscErrorCode);
459: void PetscCallVoid(PetscErrorCode);
460: #else
461:   #define PetscCall(...) \
462:     do { \
463:       PetscErrorCode ierr_petsc_call_q_; \
464:       PetscStackUpdateLine; \
465:       ierr_petsc_call_q_ = __VA_ARGS__; \
466:       if (PetscUnlikely(ierr_petsc_call_q_ != PETSC_SUCCESS)) return PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_petsc_call_q_, PETSC_ERROR_REPEAT, " "); \
467:     } while (0)
468:   #define PetscCallBack(function, ...) \
469:     do { \
470:       PetscErrorCode ierr_petsc_call_q_; \
471:       PetscStackUpdateLine; \
472:       PetscStackPushExternal(function); \
473:       ierr_petsc_call_q_ = __VA_ARGS__; \
474:       PetscStackPop; \
475:       if (PetscUnlikely(ierr_petsc_call_q_ != PETSC_SUCCESS)) return PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_petsc_call_q_, PETSC_ERROR_REPEAT, " "); \
476:     } while (0)
477:   #define PetscCallVoid(...) \
478:     do { \
479:       PetscErrorCode ierr_petsc_call_void_; \
480:       PetscStackUpdateLine; \
481:       ierr_petsc_call_void_ = __VA_ARGS__; \
482:       if (PetscUnlikely(ierr_petsc_call_void_ != PETSC_SUCCESS)) { \
483:         ierr_petsc_call_void_ = PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_petsc_call_void_, PETSC_ERROR_REPEAT, " "); \
484:         (void)ierr_petsc_call_void_; \
485:         return; \
486:       } \
487:     } while (0)
488: #endif

490: /*MC
491:   CHKERRQ - Checks error code returned from PETSc function

493:   Synopsis:
494: #include <petscsys.h>
495:   void CHKERRQ(PetscErrorCode ierr)

497:   Not Collective

499:   Input Parameter:
500: . ierr - nonzero error code

502:   Level: deprecated

504:   Note:
505:   Deprecated in favor of `PetscCall()`. This routine behaves identically to it.

507: .seealso: `PetscCall()`
508: M*/
509: #define CHKERRQ(...) PetscCall(__VA_ARGS__)
510: #define CHKERRV(...) PetscCallVoid(__VA_ARGS__)

512: PETSC_EXTERN void PetscMPIErrorString(PetscMPIInt, char *);

514: /*MC
515:   PetscCallMPI - Checks error code returned from MPI calls, if non-zero it calls the error
516:   handler and then returns

518:   Synopsis:
519: #include <petscerror.h>
520:   void PetscCallMPI(MPI_Function(args))

522:   Not Collective

524:   Input Parameter:
525: . MPI_Function - an MPI function that returns an MPI error code

527:   Level: beginner

529:   Notes:
530:   Always returns the error code `PETSC_ERR_MPI`; the MPI error code and string are embedded in
531:   the string error message. Do not use this to call any other routines (for example PETSc
532:   routines), it should only be used for direct MPI calls. The user may configure PETSc with the
533:   `--with-strict-petscerrorcode` option to check this at compile-time, otherwise they must
534:   check this themselves.

536:   This routine can only be used in functions returning `PetscErrorCode` themselves. If the
537:   calling function returns a different type, use `PetscCallMPIAbort()` instead.

539:   Example Usage:
540: .vb
541:   PetscCallMPI(MPI_Comm_size(...)); // OK, calling MPI function

543:   PetscCallMPI(PetscFunction(...)); // ERROR, use PetscCall() instead!
544: .ve

546:   Fortran Notes:
547:     The Fortran function from which this is used must declare a variable `PetscErrorCode` ierr and ierr must be
548:     the final argument to the MPI function being called.

550:     In the main program and in Fortran subroutines that do not have ierr as the final return parameter one
551:     should use `PetscCallMPIA()`

553:   Fortran Usage:
554: .vb
555:   PetscErrorCode ierr or integer ierr
556:   ...
557:   PetscCallMPI(MPI_Comm_size(...,ierr))
558:   PetscCallMPIA(MPI_Comm_size(...,ierr)) ! Will abort after calling error handler

560:   PetscCallMPI(MPI_Comm_size(...,eflag)) ! ERROR, final argument must be ierr
561: .ve

563: .seealso: `SETERRMPI()`, `PetscCall()`, `SETERRQ()`, `SETERRABORT()`, `PetscCallAbort()`,
564:           `PetscCallMPIAbort()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`,
565:           `PetscError()`, `CHKMEMQ`
566: M*/

568: /*MC
569:   PetscCallMPIAbort - Like `PetscCallMPI()` but calls `MPI_Abort()` on error

571:   Synopsis:
572: #include <petscerror.h>
573:   void PetscCallMPIAbort(MPI_Comm comm, MPI_Function(args))

575:   Not Collective

577:   Input Parameters:
578: + comm         - the MPI communicator to abort on
579: - MPI_Function - an MPI function that returns an MPI error code

581:   Level: beginner

583:   Notes:
584:   Usage is identical to `PetscCallMPI()`. See `PetscCallMPI()` for detailed discussion.

586:   This routine may be used in functions returning `void` or other non-`PetscErrorCode` types.

588:   Fortran Note:
589:   In Fortran this is called `PetscCallMPIA()` and is intended to be used in the main program while `PetscCallMPI()` is
590:   used in Fortran subroutines.

592:   Developer Note:
593:   This should have the same name in Fortran.

595: .seealso: `PetscCallMPI()`, `PetscCallAbort()`, `SETERRABORT()`
596: M*/
597: #if defined(PETSC_CLANG_STATIC_ANALYZER)
598: void PetscCallMPI(PetscMPIInt);
599: void PetscCallMPIAbort(MPI_Comm, PetscMPIInt);
600: #else
601:   #define PetscCallMPI_Private(__PETSC_STACK_POP_FUNC__, __SETERR_FUNC__, __COMM__, ...) \
602:     do { \
603:       PetscMPIInt ierr_petsc_call_mpi_; \
604:       PetscStackUpdateLine; \
605:       PetscStackPushExternal("MPI function"); \
606:       { \
607:         ierr_petsc_call_mpi_ = __VA_ARGS__; \
608:       } \
609:       __PETSC_STACK_POP_FUNC__; \
610:       if (PetscUnlikely(ierr_petsc_call_mpi_ != MPI_SUCCESS)) { \
611:         char petsc_mpi_7_errorstring[2 * MPI_MAX_ERROR_STRING]; \
612:         PetscMPIErrorString(ierr_petsc_call_mpi_, (char *)petsc_mpi_7_errorstring); \
613:         __SETERR_FUNC__(__COMM__, PETSC_ERR_MPI, "MPI error %d %s", (int)ierr_petsc_call_mpi_, petsc_mpi_7_errorstring); \
614:       } \
615:     } while (0)

617:   #define PetscCallMPI(...)            PetscCallMPI_Private(PetscStackPop, SETERRQ, PETSC_COMM_SELF, __VA_ARGS__)
618:   #define PetscCallMPIAbort(comm, ...) PetscCallMPI_Private(PetscStackPopNoCheck(PETSC_FUNCTION_NAME), SETERRABORT, comm, __VA_ARGS__)
619: #endif

621: /*MC
622:   CHKERRMPI - Checks error code returned from MPI calls, if non-zero it calls the error
623:   handler and then returns

625:   Synopsis:
626: #include <petscerror.h>
627:   void CHKERRMPI(PetscErrorCode ierr)

629:   Not Collective

631:   Input Parameter:
632: . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h

634:   Level: deprecated

636:   Note:
637:   Deprecated in favor of `PetscCallMPI()`. This routine behaves identically to it.

639: .seealso: `PetscCallMPI()`
640: M*/
641: #define CHKERRMPI(...) PetscCallMPI(__VA_ARGS__)

643: /*MC
644:   PetscCallAbort - Checks error code returned from PETSc function, if non-zero it aborts immediately by calling `MPI_Abort()`

646:   Synopsis:
647: #include <petscerror.h>
648:   void PetscCallAbort(MPI_Comm comm, PetscErrorCode ierr)

650:   Collective

652:   Input Parameters:
653: + comm - the MPI communicator on which to abort
654: - ierr - nonzero error code, see the list of standard error codes in include/petscerror.h

656:   Level: intermediate

658:   Notes:
659:   This macro has identical type and usage semantics to `PetscCall()` with the important caveat
660:   that this macro does not return. Instead, if ierr is nonzero it calls the PETSc error handler
661:   and then immediately calls `MPI_Abort()`. It can therefore be used anywhere.

663:   As per `MPI_Abort()` semantics the communicator passed must be valid, although there is currently
664:   no attempt made at handling any potential errors from `MPI_Abort()`. Note that while
665:   `MPI_Abort()` is required to terminate only those processes which reside on comm, it is often
666:   the case that `MPI_Abort()` terminates *all* processes.

668:   Example Usage:
669: .vb
670:   PetscErrorCode boom(void) { return PETSC_ERR_MEM; }

672:   void foo(void)
673:   {
674:     PetscCallAbort(PETSC_COMM_WORLD,boom()); // OK, does not return a type
675:   }

677:   double bar(void)
678:   {
679:     PetscCallAbort(PETSC_COMM_WORLD,boom()); // OK, does not return a type
680:   }

682:   PetscCallAbort(MPI_COMM_NULL,boom()); // ERROR, communicator should be valid

684:   struct baz
685:   {
686:     baz()
687:     {
688:       PetscCallAbort(PETSC_COMM_SELF,boom()); // OK
689:     }

691:     ~baz()
692:     {
693:       PetscCallAbort(PETSC_COMM_SELF,boom()); // OK (in fact the only way to handle PETSc errors)
694:     }
695:   };
696: .ve

698:   Fortran Note:
699:   Use `PetscCallA()`.

701:   Developer Note:
702:   This should have the same name in Fortran as in C.

704: .seealso: `SETERRABORT()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`,
705:           `SETERRQ()`, `CHKMEMQ`, `PetscCallMPI()`, `PetscCallCXXAbort()`
706: M*/
707: #if defined(PETSC_CLANG_STATIC_ANALYZER)
708: void PetscCallAbort(MPI_Comm, PetscErrorCode);
709: void PetscCallContinue(PetscErrorCode);
710: #else
711:   #define PetscCallAbort(comm, ...) \
712:     do { \
713:       PetscErrorCode ierr_petsc_call_abort_; \
714:       PetscStackUpdateLine; \
715:       ierr_petsc_call_abort_ = __VA_ARGS__; \
716:       if (PetscUnlikely(ierr_petsc_call_abort_ != PETSC_SUCCESS)) { \
717:         ierr_petsc_call_abort_ = PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_petsc_call_abort_, PETSC_ERROR_REPEAT, " "); \
718:         (void)MPI_Abort(comm, (PetscMPIInt)ierr_petsc_call_abort_); \
719:       } \
720:     } while (0)
721:   #define PetscCallContinue(...) \
722:     do { \
723:       PetscErrorCode ierr_petsc_call_continue_; \
724:       PetscStackUpdateLine; \
725:       ierr_petsc_call_continue_ = __VA_ARGS__; \
726:       if (PetscUnlikely(ierr_petsc_call_continue_ != PETSC_SUCCESS)) { \
727:         ierr_petsc_call_continue_ = PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_petsc_call_continue_, PETSC_ERROR_REPEAT, " "); \
728:         (void)ierr_petsc_call_continue_; \
729:       } \
730:     } while (0)
731: #endif

733: /*MC
734:   CHKERRABORT - Checks error code returned from PETSc function. If non-zero it aborts immediately.

736:   Synopsis:
737: #include <petscerror.h>
738:   void CHKERRABORT(MPI_Comm comm, PetscErrorCode ierr)

740:   Not Collective

742:   Input Parameters:
743: + comm - the MPI communicator
744: - ierr - nonzero error code, see the list of standard error codes in include/petscerror.h

746:   Level: deprecated

748:   Note:
749:   Deprecated in favor of `PetscCallAbort()`. This routine behaves identically to it.

751: .seealso: `PetscCallAbort()`, `PetscErrorCode`
752: M*/
753: #define CHKERRABORT(comm, ...) PetscCallAbort(comm, __VA_ARGS__)
754: #define CHKERRCONTINUE(...)    PetscCallContinue(__VA_ARGS__)

756: /*MC
757:    CHKERRA - Fortran-only replacement for use of `CHKERRQ()` in the main program, which aborts immediately

759:    Synopsis:
760: #include <petscsys.h>
761:    PetscErrorCode CHKERRA(PetscErrorCode ierr)

763:    Not Collective

765:    Input Parameter:
766: .  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h

768:    Level: deprecated

770:    Note:
771:    This macro is rarely needed, normal usage is `PetscCallA()` in the main Fortran program.

773:    Developer Note:
774:    Why isn't this named `CHKERRABORT()` in Fortran?

776: .seealso: `PetscCall()`, `PetscCallA()`, `PetscCallAbort()`, `CHKERRQ()`, `SETERRA()`, `SETERRQ()`, `SETERRABORT()`
777: M*/

779: PETSC_EXTERN PetscBool petscwaitonerrorflg;
780: PETSC_EXTERN PetscBool petscindebugger;
781: PETSC_EXTERN PetscBool petscabortmpifinalize;

783: /*MC
784:    PETSCABORT - Call `MPI_Abort()` with an informative error code

786:    Synopsis:
787: #include <petscsys.h>
788:    PETSCABORT(MPI_Comm comm, PetscErrorCode ierr)

790:    Collective; No Fortran Support

792:    Input Parameters:
793: +  comm - An MPI communicator, so that the error can be collective
794: -  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h

796:    Level: advanced

798:    Notes:
799:    If the option `-start_in_debugger` was used then this calls `abort()` to stop the program in the debugger.

801:    if `PetscCIEnabledPortableErrorOutput` is set, which means the code is running in the PETSc test harness (make test),
802:    and `comm` is `MPI_COMM_WORLD` it strives to exit cleanly without calling `MPI_Abort()` and instead calling `MPI_Finalize()`.

804:    This is currently only used when an error propagates up to the C `main()` program and is detected by a `PetscCall()`, `PetscCallMPI()`,
805:    or is set in `main()` with `SETERRQ()`. Abort calls such as `SETERRABORT()`,
806:    `PetscCheckAbort()`, `PetscCallMPIAbort()`, and `PetscCallAbort()` always call `MPI_Abort()` and do not have any special
807:    handling for the test harness.

809:    Developer Note:
810:    Should the other abort calls also pass through this call instead of calling `MPI_Abort()` directly?

812: .seealso: `PetscError()`, `PetscCall()`, `SETERRABORT()`, `PetscCheckAbort()`, `PetscCallMPIAbort()`, `PetscCall()`, `PetscCallMPI()`,
813:           `PetscCallAbort()`, `MPI_Abort()`, `PetscErrorCode`
814: M*/
815: #if defined(PETSC_CLANG_STATIC_ANALYZER)
816: void PETSCABORT(MPI_Comm, PetscErrorCode);
817: #else
818:   #define PETSCABORT(comm, ...) \
819:     do { \
820:       PetscErrorCode ierr_petsc_abort_; \
821:       if (petscwaitonerrorflg) { ierr_petsc_abort_ = PetscSleep(1000); } \
822:       if (petscindebugger) { \
823:         abort(); \
824:       } else { \
825:         PetscMPIInt size_; \
826:         ierr_petsc_abort_ = __VA_ARGS__; \
827:         MPI_Comm_size(comm, &size_); \
828:         if (PetscCIEnabledPortableErrorOutput && (size_ == PetscGlobalSize || petscabortmpifinalize) && ierr_petsc_abort_ != PETSC_ERR_SIG) { \
829:           MPI_Finalize(); \
830:           exit(0); \
831:         } else if (PetscCIEnabledPortableErrorOutput && PetscGlobalSize == 1) { \
832:           exit(0); \
833:         } else { \
834:           MPI_Abort(comm, (PetscMPIInt)ierr_petsc_abort_); \
835:         } \
836:       } \
837:     } while (0)
838: #endif

840: #ifdef PETSC_CLANGUAGE_CXX
841:   /*MC
842:   PetscCallThrow - Checks error code, if non-zero it calls the C++ error handler which throws
843:   an exception

845:   Synopsis:
846: #include <petscerror.h>
847:   void PetscCallThrow(PetscErrorCode ierr)

849:   Not Collective

851:   Input Parameter:
852: . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h

854:   Level: beginner

856:   Notes:
857:   Requires PETSc to be configured with clanguage of c++. Throws a std::runtime_error() on error.

859:   Once the error handler throws the exception you can use `PetscCallVoid()` which returns without
860:   an error code (bad idea since the error is ignored) or `PetscCallAbort()` to have `MPI_Abort()`
861:   called immediately.

863: .seealso: `SETERRQ()`, `PetscCall()`, `SETERRABORT()`, `PetscCallAbort()`, `PetscTraceBackErrorHandler()`,
864:           `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ`
865: M*/
866:   #define PetscCallThrow(...) \
867:     do { \
868:       PetscStackUpdateLine; \
869:       PetscErrorCode ierr_petsc_call_throw_ = __VA_ARGS__; \
870:       if (PetscUnlikely(ierr_petsc_call_throw_ != PETSC_SUCCESS)) PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_petsc_call_throw_, PETSC_ERROR_IN_CXX, PETSC_NULLPTR); \
871:     } while (0)

873:   /*MC
874:   CHKERRXX - Checks error code, if non-zero it calls the C++ error handler which throws an exception

876:   Synopsis:
877: #include <petscerror.h>
878:   void CHKERRXX(PetscErrorCode ierr)

880:   Not Collective

882:   Input Parameter:
883: . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h

885:   Level: deprecated

887:   Note:
888:   Deprecated in favor of `PetscCallThrow()`. This routine behaves identically to it.

890: .seealso: `PetscCallThrow()`
891: M*/
892:   #define CHKERRXX(...) PetscCallThrow(__VA_ARGS__)
893: #endif

895: #define PetscCallCXX_Private(__SETERR_FUNC__, __COMM__, ...) \
896:   do { \
897:     PetscStackUpdateLine; \
898:     try { \
899:       __VA_ARGS__; \
900:     } catch (const std::exception &e) { \
901:       __SETERR_FUNC__(__COMM__, PETSC_ERR_LIB, "%s", e.what()); \
902:     } \
903:   } while (0)

905: /*MC
906:   PetscCallCXX - Checks C++ function calls and if they throw an exception, catch it and then
907:   return a PETSc error code

909:   Synopsis:
910: #include <petscerror.h>
911:   void PetscCallCXX(...) noexcept;

913:   Not Collective

915:   Input Parameter:
916: . __VA_ARGS__ - An arbitrary expression

918:   Level: beginner

920:   Notes:
921:   `PetscCallCXX(...)` is a macro replacement for
922: .vb
923:   try {
924:     __VA_ARGS__;
925:   } catch (const std::exception& e) {
926:     return ConvertToPetscErrorCode(e);
927:   }
928: .ve
929:   Due to the fact that it catches any (reasonable) exception, it is essentially noexcept.

931:   If you cannot return a `PetscErrorCode` use `PetscCallCXXAbort()` instead.

933:   Example Usage:
934: .vb
935:   void foo(void) { throw std::runtime_error("error"); }

937:   void bar()
938:   {
939:     PetscCallCXX(foo()); // ERROR bar() does not return PetscErrorCode
940:   }

942:   PetscErrorCode baz()
943:   {
944:     PetscCallCXX(foo()); // OK

946:     PetscCallCXX(
947:       bar();
948:       foo(); // OK multiple statements allowed
949:     );
950:   }

952:   struct bop
953:   {
954:     bop()
955:     {
956:       PetscCallCXX(foo()); // ERROR returns PetscErrorCode, cannot be used in constructors
957:     }
958:   };

960:   // ERROR contains do-while, cannot be used as function-try block
961:   PetscErrorCode qux() PetscCallCXX(
962:     bar();
963:     baz();
964:     foo();
965:     return 0;
966:   )
967: .ve

969: .seealso: `PetscCallCXXAbort()`, `PetscCallThrow()`, `SETERRQ()`, `PetscCall()`,
970:           `SETERRABORT()`, `PetscCallAbort()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`,
971:           `PetscError()`, `CHKMEMQ`
972: M*/
973: #define PetscCallCXX(...) PetscCallCXX_Private(SETERRQ, PETSC_COMM_SELF, __VA_ARGS__)

975: /*MC
976:   PetscCallCXXAbort - Like `PetscCallCXX()` but calls `MPI_Abort()` instead of returning an
977:   error-code

979:   Synopsis:
980: #include <petscerror.h>
981:   void PetscCallCXXAbort(MPI_Comm comm, ...) noexcept;

983:   Collective; No Fortran Support

985:   Input Parameters:
986: + comm        - The MPI communicator to abort on
987: - __VA_ARGS__ - An arbitrary expression

989:   Level: beginner

991:   Notes:
992:   This macro may be used to check C++ expressions for exceptions in cases where you cannot
993:   return an error code. This includes constructors, destructors, copy/move assignment functions
994:   or constructors among others.

996:   If an exception is caught, the macro calls `SETERRABORT()` on `comm`. The exception must
997:   derive from `std::exception` in order to be caught.

999:   If the routine _can_ return an error-code it is highly advised to use `PetscCallCXX()`
1000:   instead.

1002:   See `PetscCallCXX()` for additional discussion.

1004:   Example Usage:
1005: .vb
1006:   class Foo
1007:   {
1008:     std::vector<int> data_;

1010:   public:
1011:     // normally std::vector::reserve() may raise an exception, but since we handle it with
1012:     // PetscCallCXXAbort() we may mark this routine as noexcept!
1013:     Foo() noexcept
1014:     {
1015:       PetscCallCXXAbort(PETSC_COMM_SELF, data_.reserve(10));
1016:     }
1017:   };

1019:   std::vector<int> bar()
1020:   {
1021:     std::vector<int> v;

1023:     PetscFunctionBegin;
1024:     // OK!
1025:     PetscCallCXXAbort(PETSC_COMM_SELF, v.emplace_back(1));
1026:     PetscFunctionReturn(v);
1027:   }

1029:   PetscErrorCode baz()
1030:   {
1031:     std::vector<int> v;

1033:     PetscFunctionBegin;
1034:     // WRONG! baz() returns a PetscErrorCode, prefer PetscCallCXX() instead
1035:     PetscCallCXXAbort(PETSC_COMM_SELF, v.emplace_back(1));
1036:     PetscFunctionReturn(PETSC_SUCCESS);
1037:   }
1038: .ve

1040: .seealso: `PetscCallCXX()`, `SETERRABORT()`, `PetscCallAbort()`
1041: M*/
1042: #define PetscCallCXXAbort(comm, ...) PetscCallCXX_Private(SETERRABORT, comm, __VA_ARGS__)

1044: /*MC
1045:   CHKERRCXX - Checks C++ function calls and if they throw an exception, catch it and then
1046:   return a PETSc error code

1048:   Synopsis:
1049: #include <petscerror.h>
1050:   void CHKERRCXX(func) noexcept;

1052:   Not Collective

1054:   Input Parameter:
1055: . func - C++ function calls

1057:   Level: deprecated

1059:   Note:
1060:   Deprecated in favor of `PetscCallCXX()`. This routine behaves identically to it.

1062: .seealso: `PetscCallCXX()`
1063: M*/
1064: #define CHKERRCXX(...) PetscCallCXX(__VA_ARGS__)

1066: /*MC
1067:    CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected

1069:    Synopsis:
1070: #include <petscsys.h>
1071:    CHKMEMQ;

1073:    Not Collective

1075:    Level: beginner

1077:    Notes:
1078:    We recommend using Valgrind <https://petsc.org/release/faq/#valgrind> or for NVIDIA CUDA systems
1079:    <https://docs.nvidia.com/cuda/cuda-memcheck/index.html> for finding memory problems. The ``CHKMEMQ`` macro is useful on systems that
1080:    do not have valgrind, but is not as good as valgrind or cuda-memcheck.

1082:    Must run with the option `-malloc_debug` (`-malloc_test` in debug mode; or if `PetscMallocSetDebug()` called) to enable this option

1084:    Once the error handler is called the calling function is then returned from with the given error code.

1086:    By defaults prints location where memory that is corrupted was allocated.

1088:    Use `CHKMEMA` for functions that return void

1090: .seealso: `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, `SETERRQ()`, `PetscMallocValidate()`
1091: M*/
1092: #if defined(PETSC_CLANG_STATIC_ANALYZER)
1093:   #define CHKMEMQ
1094:   #define CHKMEMA
1095: #else
1096:   #define CHKMEMQ \
1097:     do { \
1098:       PetscErrorCode ierr_petsc_memq_ = PetscMallocValidate(__LINE__, PETSC_FUNCTION_NAME, __FILE__); \
1099:       if (PetscUnlikely(ierr_petsc_memq_ != PETSC_SUCCESS)) return PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_petsc_memq_, PETSC_ERROR_REPEAT, " "); \
1100:     } while (0)
1101:   #define CHKMEMA PetscMallocValidate(__LINE__, PETSC_FUNCTION_NAME, __FILE__)
1102: #endif

1104: /*E
1105:   PetscErrorType - passed to the PETSc error handling routines indicating if this is the first or a later call to the error handlers

1107:   Level: advanced

1109:   Note:
1110:   `PETSC_ERROR_IN_CXX` indicates the error was detected in C++ and an exception should be generated

1112:   Developer Note:
1113:   This is currently used to decide when to print the detailed information about the run in `PetscTraceBackErrorHandler()`

1115: .seealso: `PetscError()`, `SETERRQ()`
1116: E*/
1117: typedef enum {
1118:   PETSC_ERROR_INITIAL = 0,
1119:   PETSC_ERROR_REPEAT  = 1,
1120:   PETSC_ERROR_IN_CXX  = 2
1121: } PetscErrorType;

1123: #if defined(__clang_analyzer__)
1124: __attribute__((analyzer_noreturn))
1125: #endif
1126: PETSC_EXTERN PetscErrorCode
1127: PetscError(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, ...) PETSC_ATTRIBUTE_COLD PETSC_ATTRIBUTE_FORMAT(7, 8);

1129: PETSC_EXTERN PetscErrorCode PetscErrorPrintfInitialize(void);
1130: PETSC_EXTERN PetscErrorCode PetscErrorMessage(PetscErrorCode, const char *[], char **);
1131: PETSC_EXTERN PetscErrorCode PetscTraceBackErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD;
1132: PETSC_EXTERN PetscErrorCode PetscIgnoreErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD;
1133: PETSC_EXTERN PetscErrorCode PetscEmacsClientErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD;
1134: PETSC_EXTERN PetscErrorCode PetscMPIAbortErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD;
1135: PETSC_EXTERN PetscErrorCode PetscAbortErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD;
1136: PETSC_EXTERN PetscErrorCode PetscAttachDebuggerErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD;
1137: PETSC_EXTERN PetscErrorCode PetscReturnErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD;
1138: PETSC_EXTERN PetscErrorCode PetscPushErrorHandler(PetscErrorCode (*handler)(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *), void *);
1139: PETSC_EXTERN PetscErrorCode PetscPopErrorHandler(void);
1140: PETSC_EXTERN PetscErrorCode PetscSignalHandlerDefault(int, void *);
1141: PETSC_EXTERN PetscErrorCode PetscPushSignalHandler(PetscErrorCode (*)(int, void *), void *);
1142: PETSC_EXTERN PetscErrorCode PetscPopSignalHandler(void);
1143: PETSC_EXTERN PetscErrorCode PetscCheckPointerSetIntensity(PetscInt);
1144: PETSC_EXTERN void           PetscSignalSegvCheckPointerOrMpi(void);
1145: PETSC_DEPRECATED_FUNCTION(3, 13, 0, "PetscSignalSegvCheckPointerOrMpi()", ) static inline void PetscSignalSegvCheckPointer(void)
1146: {
1147:   PetscSignalSegvCheckPointerOrMpi();
1148: }

1150: /*MC
1151:     PetscErrorPrintf - Prints error messages.

1153:    Synopsis:
1154: #include <petscsys.h>
1155:      PetscErrorCode (*PetscErrorPrintf)(const char format[],...);

1157:     Not Collective; No Fortran Support

1159:     Input Parameter:
1160: .   format - the usual `printf()` format string

1162:    Options Database Keys:
1163: +  -error_output_stdout - cause error messages to be printed to stdout instead of the (default) stderr
1164: -  -error_output_none   - to turn off all printing of error messages (does not change the way the error is handled.)

1166:    Level: developer

1168:    Notes:
1169:    Use
1170: .vb
1171:      PetscErrorPrintf = PetscErrorPrintfNone; to turn off all printing of error messages (does not change the way the error is handled) and
1172:      PetscErrorPrintf = PetscErrorPrintfDefault; to turn it back on or you can use your own function
1173: .ve
1174:    Use
1175: .vb
1176:      `PETSC_STDERR` = FILE* obtained from a file open etc. to have stderr printed to the file.
1177:      `PETSC_STDOUT` = FILE* obtained from a file open etc. to have stdout printed to the file.
1178: .ve
1179:    Use
1180: .vb
1181:       `PetscPushErrorHandler()` to provide your own error handler that determines what kind of messages to print
1182: .ve

1184: .seealso: `PetscFPrintf()`, `PetscSynchronizedPrintf()`, `PetscHelpPrintf()`, `PetscPrintf()`, `PetscPushErrorHandler()`, `PetscVFPrintf()`, `PetscHelpPrintf()`
1185: M*/
1186: PETSC_EXTERN PetscErrorCode (*PetscErrorPrintf)(const char[], ...) PETSC_ATTRIBUTE_FORMAT(1, 2);

1188: /*E
1189:      PetscFPTrap - types of floating point exceptions that may be trapped

1191:      Currently only `PETSC_FP_TRAP_OFF` and `PETSC_FP_TRAP_ON` are handled. All others are treated as `PETSC_FP_TRAP_ON`.

1193:      Level: intermediate

1195: .seealso: `PetscSetFPTrap()`, `PetscFPTrapPush()`
1196:  E*/
1197: typedef enum {
1198:   PETSC_FP_TRAP_OFF      = 0,
1199:   PETSC_FP_TRAP_INDIV    = 1,
1200:   PETSC_FP_TRAP_FLTOPERR = 2,
1201:   PETSC_FP_TRAP_FLTOVF   = 4,
1202:   PETSC_FP_TRAP_FLTUND   = 8,
1203:   PETSC_FP_TRAP_FLTDIV   = 16,
1204:   PETSC_FP_TRAP_FLTINEX  = 32
1205: } PetscFPTrap;
1206: #define PETSC_FP_TRAP_ON (PetscFPTrap)(PETSC_FP_TRAP_INDIV | PETSC_FP_TRAP_FLTOPERR | PETSC_FP_TRAP_FLTOVF | PETSC_FP_TRAP_FLTDIV | PETSC_FP_TRAP_FLTINEX)
1207: PETSC_EXTERN PetscErrorCode PetscSetFPTrap(PetscFPTrap);
1208: PETSC_EXTERN PetscErrorCode PetscFPTrapPush(PetscFPTrap);
1209: PETSC_EXTERN PetscErrorCode PetscFPTrapPop(void);
1210: PETSC_EXTERN PetscErrorCode PetscDetermineInitialFPTrap(void);

1212: /*
1213:       Allows the code to build a stack frame as it runs
1214: */

1216: #define PETSCSTACKSIZE 64
1217: typedef struct {
1218:   const char *function[PETSCSTACKSIZE];
1219:   const char *file[PETSCSTACKSIZE];
1220:   int         line[PETSCSTACKSIZE];
1221:   int         petscroutine[PETSCSTACKSIZE]; /* 0 external called from petsc, 1 petsc functions, 2 petsc user functions */
1222:   int         currentsize;
1223:   int         hotdepth;
1224:   PetscBool   check; /* option to check for correct Push/Pop semantics, true for default petscstack but not other stacks */
1225: } PetscStack;
1226: #if defined(PETSC_USE_DEBUG) && !defined(PETSC_HAVE_THREADSAFETY)
1227: PETSC_EXTERN PetscStack petscstack;
1228: #endif

1230: #if defined(PETSC_SERIALIZE_FUNCTIONS)
1231: #include <petsc/private/petscfptimpl.h>
1232:   /*
1233:    Registers the current function into the global function pointer to function name table

1235:    Have to fix this to handle errors but cannot return error since used in PETSC_VIEWER_DRAW_() etc
1236: */
1237:   #define PetscRegister__FUNCT__() \
1238:     do { \
1239:       static PetscBool __chked = PETSC_FALSE; \
1240:       if (!__chked) { \
1241:         void *ptr; \
1242:         PetscCallAbort(PETSC_COMM_SELF, PetscDLSym(NULL, PETSC_FUNCTION_NAME, &ptr)); \
1243:         __chked = PETSC_TRUE; \
1244:       } \
1245:     } while (0)
1246: #else
1247:   #define PetscRegister__FUNCT__()
1248: #endif

1250: #if defined(PETSC_CLANG_STATIC_ANALYZER) || defined(__clang_analyzer__)
1251:   #define PetscStackPushNoCheck(funct, petsc_routine, hot)
1252:   #define PetscStackUpdateLine
1253:   #define PetscStackPushExternal(funct)
1254:   #define PetscStackPopNoCheck
1255:   #define PetscStackClearTop
1256:   #define PetscFunctionBegin
1257:   #define PetscFunctionBeginUser
1258:   #define PetscFunctionBeginHot
1259:   #define PetscFunctionReturn(...)  return __VA_ARGS__
1260:   #define PetscFunctionReturnVoid() return
1261:   #define PetscStackPop
1262:   #define PetscStackPush(f)
1263: #elif defined(PETSC_USE_DEBUG) && !defined(PETSC_HAVE_THREADSAFETY)

1265:   #define PetscStackPush_Private(stack__, file__, func__, line__, petsc_routine__, hot__) \
1266:     do { \
1267:       if (stack__.currentsize < PETSCSTACKSIZE) { \
1268:         stack__.function[stack__.currentsize] = func__; \
1269:         if (petsc_routine__) { \
1270:           stack__.file[stack__.currentsize] = file__; \
1271:           stack__.line[stack__.currentsize] = line__; \
1272:         } else { \
1273:           stack__.file[stack__.currentsize] = PETSC_NULLPTR; \
1274:           stack__.line[stack__.currentsize] = 0; \
1275:         } \
1276:         stack__.petscroutine[stack__.currentsize] = petsc_routine__; \
1277:       } \
1278:       ++stack__.currentsize; \
1279:       stack__.hotdepth += (hot__ || stack__.hotdepth); \
1280:     } while (0)

1282:   /* uses PetscCheckAbort() because may be used in a function that does not return an error code */
1283:   #define PetscStackPop_Private(stack__, func__) \
1284:     do { \
1285:       PetscCheckAbort(!stack__.check || stack__.currentsize > 0, PETSC_COMM_SELF, PETSC_ERR_PLIB, "Invalid stack size %d, pop %s %s:%d.\n", stack__.currentsize, func__, __FILE__, __LINE__); \
1286:       if (--stack__.currentsize < PETSCSTACKSIZE) { \
1287:         PetscCheckAbort(!stack__.check || stack__.petscroutine[stack__.currentsize] != 1 || stack__.function[stack__.currentsize] == (const char *)(func__), PETSC_COMM_SELF, PETSC_ERR_PLIB, "Invalid stack: push from %s %s:%d. Pop from %s %s:%d.\n", \
1288:                         stack__.function[stack__.currentsize], stack__.file[stack__.currentsize], stack__.line[stack__.currentsize], func__, __FILE__, __LINE__); \
1289:         stack__.function[stack__.currentsize]     = PETSC_NULLPTR; \
1290:         stack__.file[stack__.currentsize]         = PETSC_NULLPTR; \
1291:         stack__.line[stack__.currentsize]         = 0; \
1292:         stack__.petscroutine[stack__.currentsize] = 0; \
1293:       } \
1294:       stack__.hotdepth = PetscMax(stack__.hotdepth - 1, 0); \
1295:     } while (0)

1297:   /*MC
1298:    PetscStackPushNoCheck - Pushes a new function name and line number onto the PETSc default stack that tracks where the running program is
1299:    currently in the source code.

1301:    Synopsis:
1302: #include <petscsys.h>
1303:    void PetscStackPushNoCheck(char *funct,int petsc_routine,PetscBool hot);

1305:    Not Collective

1307:    Input Parameters:
1308: +  funct - the function name
1309: .  petsc_routine - 2 user function, 1 PETSc function, 0 some other function
1310: -  hot - indicates that the function may be called often so expensive error checking should be turned off inside the function

1312:    Level: developer

1314:    Notes:
1315:    In debug mode PETSc maintains a stack of the current function calls that can be used to help to quickly see where a problem has
1316:    occurred, for example, when a signal is received without running in the debugger. It is recommended to use the debugger if extensive information is needed to
1317:    help debug the problem.

1319:    This version does not check the memory corruption (an expensive operation), use `PetscStackPush()` to check the memory.

1321:    Use `PetscStackPushExternal()` for a function call that is about to be made to a non-PETSc or user function (such as BLAS etc).

1323:    The default stack is a global variable called `petscstack`.

1325: .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPopNoCheck()`, `PetscCall()`, `PetscFunctionBegin()`,
1326:           `PetscFunctionReturn()`, `PetscFunctionBeginHot()`, `PetscFunctionBeginUser()`, `PetscStackPush()`, `PetscStackPop`,
1327:           `PetscStackPushExternal()`
1328: M*/
1329:   #define PetscStackPushNoCheck(funct, petsc_routine, hot) \
1330:     do { \
1331:       PetscStackSAWsTakeAccess(); \
1332:       PetscStackPush_Private(petscstack, __FILE__, funct, __LINE__, petsc_routine, hot); \
1333:       PetscStackSAWsGrantAccess(); \
1334:     } while (0)

1336:   /*MC
1337:    PetscStackUpdateLine - in a function that has a `PetscFunctionBegin` or `PetscFunctionBeginUser` updates the stack line number to the
1338:    current line number.

1340:    Synopsis:
1341: #include <petscsys.h>
1342:    void PetscStackUpdateLine

1344:    Not Collective

1346:    Level: developer

1348:    Notes:
1349:    Using `PetscCall()` and friends automatically handles this process

1351:    In debug mode PETSc maintains a stack of the current function calls that can be used to help to quickly see where a problem has
1352:    occurred, for example, when a signal is received. It is recommended to use the debugger if extensive information is needed to
1353:    help debug the problem.

1355:    The default stack is a global variable called `petscstack`.

1357:    This is used by `PetscCall()` and is otherwise not like to be needed

1359: .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPushNoCheck()`, `PetscStackPop`, `PetscCall()`
1360: M*/
1361:   #define PetscStackUpdateLine \
1362:     do { \
1363:       if (petscstack.currentsize > 0 && petscstack.function[petscstack.currentsize - 1] == PETSC_FUNCTION_NAME) { petscstack.line[petscstack.currentsize - 1] = __LINE__; } \
1364:     } while (0)

1366:   /*MC
1367:    PetscStackPushExternal - Pushes a new function name onto the PETSc default stack that tracks where the running program is
1368:    currently in the source code. Does not include the filename or line number since this is called by the calling routine
1369:    for non-PETSc or user functions.

1371:    Synopsis:
1372: #include <petscsys.h>
1373:    void PetscStackPushExternal(char *funct);

1375:    Not Collective

1377:    Input Parameter:
1378: .  funct - the function name

1380:    Level: developer

1382:    Notes:
1383:    Using `PetscCallExternal()` and friends automatically handles this process

1385:    In debug mode PETSc maintains a stack of the current function calls that can be used to help to quickly see where a problem has
1386:    occurred, for example, when a signal is received. It is recommended to use the debugger if extensive information is needed to
1387:    help debug the problem.

1389:    The default stack is a global variable called `petscstack`.

1391:    This is to be used when calling an external package function such as a BLAS function.

1393:    This also updates the stack line number for the current stack function.

1395: .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPopNoCheck()`, `PetscCall()`, `PetscFunctionBegin()`,
1396:           `PetscFunctionReturn()`, `PetscFunctionBeginHot()`, `PetscFunctionBeginUser()`, `PetscStackPushNoCheck()`, `PetscStackPop`
1397: M*/
1398:   #define PetscStackPushExternal(funct) \
1399:     do { \
1400:       PetscStackUpdateLine; \
1401:       PetscStackPushNoCheck(funct, 0, PETSC_TRUE); \
1402:     } while (0)

1404:   /*MC
1405:    PetscStackPopNoCheck - Pops a function name from the PETSc default stack that tracks where the running program is
1406:    currently in the source code.

1408:    Synopsis:
1409: #include <petscsys.h>
1410:    void PetscStackPopNoCheck(char *funct);

1412:    Not Collective

1414:    Input Parameter:
1415: .   funct - the function name

1417:    Level: developer

1419:    Notes:
1420:    Using `PetscCall()`, `PetscCallExternal()`, `PetscCallBack()` and friends negates the need to call this

1422:    In debug mode PETSc maintains a stack of the current function calls that can be used to help to quickly see where a problem has
1423:    occurred, for example, when a signal is received. It is recommended to use the debugger if extensive information is needed to
1424:    help debug the problem.

1426:    The default stack is a global variable called `petscstack`.

1428:    Developer Note:
1429:    `PetscStackPopNoCheck()` takes a function argument while  `PetscStackPop` does not, this difference is likely just historical.

1431: .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPushNoCheck()`, `PetscStackPop`
1432: M*/
1433:   #define PetscStackPopNoCheck(funct) \
1434:     do { \
1435:       PetscStackSAWsTakeAccess(); \
1436:       PetscStackPop_Private(petscstack, funct); \
1437:       PetscStackSAWsGrantAccess(); \
1438:     } while (0)

1440:   #define PetscStackClearTop \
1441:     do { \
1442:       PetscStackSAWsTakeAccess(); \
1443:       if (petscstack.currentsize > 0 && --petscstack.currentsize < PETSCSTACKSIZE) { \
1444:         petscstack.function[petscstack.currentsize]     = PETSC_NULLPTR; \
1445:         petscstack.file[petscstack.currentsize]         = PETSC_NULLPTR; \
1446:         petscstack.line[petscstack.currentsize]         = 0; \
1447:         petscstack.petscroutine[petscstack.currentsize] = 0; \
1448:       } \
1449:       petscstack.hotdepth = PetscMax(petscstack.hotdepth - 1, 0); \
1450:       PetscStackSAWsGrantAccess(); \
1451:     } while (0)

1453:   /*MC
1454:    PetscFunctionBegin - First executable line of each PETSc function,  used for error handling. Final
1455:    line of PETSc functions should be `PetscFunctionReturn`(0);

1457:    Synopsis:
1458: #include <petscsys.h>
1459:    void PetscFunctionBegin;

1461:    Not Collective; No Fortran Support

1463:    Usage:
1464: .vb
1465:      int something;

1467:      PetscFunctionBegin;
1468: .ve

1470:    Level: developer

1472:    Note:
1473:    Use `PetscFunctionBeginUser` for application codes.

1475: .seealso: `PetscFunctionReturn()`, `PetscFunctionBeginHot()`, `PetscFunctionBeginUser()`, `PetscStackPushNoCheck()`

1477: M*/
1478:   #define PetscFunctionBegin \
1479:     do { \
1480:       PetscStackPushNoCheck(PETSC_FUNCTION_NAME, 1, PETSC_FALSE); \
1481:       PetscRegister__FUNCT__(); \
1482:     } while (0)

1484:   /*MC
1485:    PetscFunctionBeginHot - Substitute for `PetscFunctionBegin` to be used in functions that are called in
1486:    performance-critical circumstances.  Use of this function allows for lighter profiling by default.

1488:    Synopsis:
1489: #include <petscsys.h>
1490:    void PetscFunctionBeginHot;

1492:    Not Collective; No Fortran Support

1494:    Usage:
1495: .vb
1496:      int something;

1498:      PetscFunctionBeginHot;
1499: .ve

1501:    Level: developer

1503: .seealso: `PetscFunctionBegin`, `PetscFunctionReturn()`, `PetscStackPushNoCheck()`

1505: M*/
1506:   #define PetscFunctionBeginHot \
1507:     do { \
1508:       PetscStackPushNoCheck(PETSC_FUNCTION_NAME, 1, PETSC_TRUE); \
1509:       PetscRegister__FUNCT__(); \
1510:     } while (0)

1512:   /*MC
1513:    PetscFunctionBeginUser - First executable line of user provided routines

1515:    Synopsis:
1516: #include <petscsys.h>
1517:    void PetscFunctionBeginUser;

1519:    Not Collective; No Fortran Support

1521:    Usage:
1522: .vb
1523:      int something;

1525:      PetscFunctionBeginUser;
1526: .ve

1528:    Level: intermediate

1530:    Notes:
1531:    Functions that incorporate this must call `PetscFunctionReturn()` instead of return except for main().

1533:    May be used before `PetscInitialize()`

1535:    This is identical to `PetscFunctionBegin` except it labels the routine as a user
1536:    routine instead of as a PETSc library routine.

1538: .seealso: `PetscFunctionReturn()`, `PetscFunctionBegin`, `PetscFunctionBeginHot`, `PetscStackPushNoCheck()`
1539: M*/
1540:   #define PetscFunctionBeginUser \
1541:     do { \
1542:       PetscStackPushNoCheck(PETSC_FUNCTION_NAME, 2, PETSC_FALSE); \
1543:       PetscRegister__FUNCT__(); \
1544:     } while (0)

1546:   /*MC
1547:    PetscStackPush - Pushes a new function name and line number onto the PETSc default stack that tracks where the running program is
1548:    currently in the source code and verifies the memory is not corrupted.

1550:    Synopsis:
1551: #include <petscsys.h>
1552:    void PetscStackPush(char *funct)

1554:    Not Collective

1556:    Input Parameter:
1557: .  funct - the function name

1559:    Level: developer

1561:    Notes:
1562:    In debug mode PETSc maintains a stack of the current function calls that can be used to help to quickly see where a problem has
1563:    occurred, for example, when a signal is received. It is recommended to use the debugger if extensive information is needed to
1564:    help debug the problem.

1566:    The default stack is a global variable called `petscstack`.

1568: .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPopNoCheck()`, `PetscCall()`, `PetscFunctionBegin()`,
1569:           `PetscFunctionReturn()`, `PetscFunctionBeginHot()`, `PetscFunctionBeginUser()`, `PetscStackPushNoCheck()`, `PetscStackPop`
1570: M*/
1571:   #define PetscStackPush(n) \
1572:     do { \
1573:       PetscStackPushNoCheck(n, 0, PETSC_FALSE); \
1574:       CHKMEMQ; \
1575:     } while (0)

1577:   /*MC
1578:    PetscStackPop - Pops a function name from the PETSc default stack that tracks where the running program is
1579:    currently in the source code and verifies the memory is not corrupted.

1581:    Synopsis:
1582: #include <petscsys.h>
1583:    void PetscStackPop

1585:    Not Collective

1587:    Level: developer

1589:    Notes:
1590:    In debug mode PETSc maintains a stack of the current function calls that can be used to help to quickly see where a problem has
1591:    occurred, for example, when a signal is received. It is recommended to use the debugger if extensive information is needed to
1592:    help debug the problem.

1594:    The default stack is a global variable called `petscstack`.

1596: .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPushNoCheck()`, `PetscStackPopNoCheck()`, `PetscStackPush()`
1597: M*/
1598:   #define PetscStackPop \
1599:     do { \
1600:       CHKMEMQ; \
1601:       PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \
1602:     } while (0)

1604:   /*MC
1605:    PetscFunctionReturn - Last executable line of each PETSc function used for error
1606:    handling. Replaces `return()`.

1608:    Synopsis:
1609: #include <petscerror.h>
1610:    void PetscFunctionReturn(...)

1612:    Not Collective; No Fortran Support

1614:    Level: beginner

1616:    Notes:
1617:    This routine is a macro, so while it does not "return" anything itself, it does return from
1618:    the function in the literal sense.

1620:    Usually the return value is the integer literal `0` (for example in any function returning
1621:    `PetscErrorCode`), however it is possible to return any arbitrary type. The arguments of
1622:    this macro are placed before the `return` statement as-is.

1624:    Any routine which returns via `PetscFunctionReturn()` must begin with a corresponding
1625:    `PetscFunctionBegin`.

1627:    For routines which return `void` use `PetscFunctionReturnVoid()` instead.

1629:    Example Usage:
1630: .vb
1631:    PetscErrorCode foo(int *x)
1632:    {
1633:      PetscFunctionBegin; // don't forget the begin!
1634:      *x = 10;
1635:      PetscFunctionReturn(PETSC_SUCCESS);
1636:    }
1637: .ve

1639:    May return any arbitrary type\:
1640: .vb
1641:   struct Foo
1642:   {
1643:     int x;
1644:   };

1646:   struct Foo make_foo(int value)
1647:   {
1648:     struct Foo f;

1650:     PetscFunctionBegin;
1651:     f.x = value;
1652:     PetscFunctionReturn(f);
1653:   }
1654: .ve

1656: .seealso: `PetscFunctionBegin`, `PetscFunctionBeginUser`, `PetscFunctionReturnVoid()`,
1657:           `PetscStackPopNoCheck()`
1658: M*/
1659:   #define PetscFunctionReturn(...) \
1660:     do { \
1661:       PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \
1662:       return __VA_ARGS__; \
1663:     } while (0)

1665:   /*MC
1666:   PetscFunctionReturnVoid - Like `PetscFunctionReturn()` but returns `void`

1668:   Synopsis:
1669: #include <petscerror.h>
1670:   void PetscFunctionReturnVoid()

1672:   Not Collective

1674:   Level: beginner

1676:   Note:
1677:   Behaves identically to `PetscFunctionReturn()` except that it returns `void`. That is, this
1678:   macro culminates with `return`.

1680:   Example Usage:
1681: .vb
1682:   void foo()
1683:   {
1684:     PetscFunctionBegin; // must start with PetscFunctionBegin!
1685:     bar();
1686:     baz();
1687:     PetscFunctionReturnVoid();
1688:   }
1689: .ve

1691: .seealso: `PetscFunctionReturn()`, `PetscFunctionBegin`, PetscFunctionBeginUser`
1692: M*/
1693:   #define PetscFunctionReturnVoid() \
1694:     do { \
1695:       PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \
1696:       return; \
1697:     } while (0)
1698: #else /* PETSC_USE_DEBUG */
1699:   #define PetscStackPushNoCheck(funct, petsc_routine, hot)
1700:   #define PetscStackUpdateLine
1701:   #define PetscStackPushExternal(funct)
1702:   #define PetscStackPopNoCheck(...)
1703:   #define PetscStackClearTop
1704:   #define PetscFunctionBegin
1705:   #define PetscFunctionBeginUser
1706:   #define PetscFunctionBeginHot
1707:   #define PetscFunctionReturn(...)  return __VA_ARGS__
1708:   #define PetscFunctionReturnVoid() return
1709:   #define PetscStackPop             CHKMEMQ
1710:   #define PetscStackPush(f)         CHKMEMQ
1711: #endif /* PETSC_USE_DEBUG */

1713: #if defined(PETSC_CLANG_STATIC_ANALYZER)
1714:   #define PetscStackCallExternalVoid(...)
1715: template <typename F, typename... Args>
1716: void PetscCallExternal(F, Args...);
1717: #else
1718:   /*MC
1719:     PetscStackCallExternalVoid - Calls an external library routine or user function after pushing the name of the routine on the stack.

1721:    Input Parameters:
1722: +   name    - string that gives the name of the function being called
1723: -   routine - actual call to the routine, for example, functionname(a,b)

1725:    Level: developer

1727:    Notes:
1728:    Often one should use `PetscCallExternal()` instead. This routine is intended for external library routines that DO NOT return error codes

1730:    In debug mode this also checks the memory for corruption at the end of the function call.

1732:    Certain external packages, such as BLAS/LAPACK may have their own macros, `PetscCallBLAS()` for managing the call, error checking, etc.

1734:    Developer Note:
1735:    This is so that when a user or external library routine results in a crash or corrupts memory, they get blamed instead of PETSc.

1737: .seealso: `PetscCall()`, `PetscStackPushNoCheck()`, `PetscStackPush()`, `PetscCallExternal()`, `PetscCallBLAS()`
1738: @*/
1739:   #define PetscStackCallExternalVoid(name, ...) \
1740:     do { \
1741:       PetscStackPushExternal(name); \
1742:       __VA_ARGS__; \
1743:       PetscStackPop; \
1744:     } while (0)

1746:   /*MC
1747:     PetscCallExternal - Calls an external library routine that returns an error code after pushing the name of the routine on the stack.

1749:    Input Parameters:
1750: +  func - name of the routine
1751: -  args - arguments to the routine

1753:    Level: developer

1755:    Notes:
1756:    This is intended for external package routines that return error codes. Use `PetscStackCallExternalVoid()` for those that do not.

1758:    In debug mode this also checks the memory for corruption at the end of the function call.

1760:    Assumes the error return code of the function is an integer and that a value of 0 indicates success

1762:    Developer Note:
1763:    This is so that when an external package routine results in a crash or corrupts memory, they get blamed instead of PETSc.

1765: .seealso: `PetscCall()`, `PetscStackPushNoCheck()`, `PetscStackPush()`, `PetscStackCallExternalVoid()`
1766: M*/
1767:   #define PetscCallExternal(func, ...) \
1768:     do { \
1769:       PetscStackPush(PetscStringize(func)); \
1770:       int ierr_petsc_call_external_ = func(__VA_ARGS__); \
1771:       PetscStackPop; \
1772:       PetscCheck(ierr_petsc_call_external_ == 0, PETSC_COMM_SELF, PETSC_ERR_LIB, "Error in %s(): error code %d", PetscStringize(func), ierr_petsc_call_external_); \
1773:     } while (0)
1774: #endif /* PETSC_CLANG_STATIC_ANALYZER */