1 /*
2 Contains all error handling interfaces for PETSc.
3 */
4 #pragma once
5 // IWYU pragma: private, include "petscsys.h"
6
7 #include <petscmacros.h>
8 #include <petscsystypes.h>
9
10 #if defined(__cplusplus)
11 #include <exception> // std::exception
12 #endif
13
14 /* SUBMANSEC = Sys */
15
16 #define SETERRQ1(...) PETSC_DEPRECATED_MACRO(3, 17, 0, "SETERRQ", ) SETERRQ(__VA_ARGS__)
17 #define SETERRQ2(...) PETSC_DEPRECATED_MACRO(3, 17, 0, "SETERRQ", ) SETERRQ(__VA_ARGS__)
18 #define SETERRQ3(...) PETSC_DEPRECATED_MACRO(3, 17, 0, "SETERRQ", ) SETERRQ(__VA_ARGS__)
19 #define SETERRQ4(...) PETSC_DEPRECATED_MACRO(3, 17, 0, "SETERRQ", ) SETERRQ(__VA_ARGS__)
20 #define SETERRQ5(...) PETSC_DEPRECATED_MACRO(3, 17, 0, "SETERRQ", ) SETERRQ(__VA_ARGS__)
21 #define SETERRQ6(...) PETSC_DEPRECATED_MACRO(3, 17, 0, "SETERRQ", ) SETERRQ(__VA_ARGS__)
22 #define SETERRQ7(...) PETSC_DEPRECATED_MACRO(3, 17, 0, "SETERRQ", ) SETERRQ(__VA_ARGS__)
23 #define SETERRQ8(...) PETSC_DEPRECATED_MACRO(3, 17, 0, "SETERRQ", ) SETERRQ(__VA_ARGS__)
24 #define SETERRQ9(...) PETSC_DEPRECATED_MACRO(3, 17, 0, "SETERRQ", ) SETERRQ(__VA_ARGS__)
25
26 /*MC
27 SETERRQ - Macro to be called when an error has been detected,
28
29 Synopsis:
30 #include <petscsys.h>
31 PetscErrorCode SETERRQ(MPI_Comm comm, PetscErrorCode ierr, char *message, ...)
32
33 Collective
34
35 Input Parameters:
36 + comm - An MPI communicator, use `PETSC_COMM_SELF` unless you know all ranks of another communicator will detect the error
37 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
38 - message - error message
39
40 Level: beginner
41
42 Notes:
43 This is rarely needed, one should use `PetscCheck()` and `PetscCall()` and friends to automatically handle error conditions.
44 Once the error handler is called the calling function is then returned from with the given error code.
45
46 Experienced users can set the error handler with `PetscPushErrorHandler()`.
47
48 Fortran Note:
49 `SETERRQ()` may be called from Fortran subroutines but `SETERRA()` must be called from the
50 Fortran main program.
51
52 .seealso: `PetscCheck()`, `PetscAssert()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`,
53 `PetscError()`, `PetscCall()`, `CHKMEMQ`, `CHKERRA()`, `PetscCallMPI()`, `PetscErrorCode`
54 M*/
55 #define SETERRQ(comm, ierr, ...) \
56 do { \
57 PetscErrorCode ierr_seterrq_petsc_ = PetscError(comm, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr, PETSC_ERROR_INITIAL, __VA_ARGS__); \
58 return ierr_seterrq_petsc_ ? ierr_seterrq_petsc_ : PETSC_ERR_RETURN; \
59 } while (0)
60
61 #define SETERRQNULL(comm, ierr, ...) \
62 do { \
63 (void)PetscError(comm, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr, PETSC_ERROR_INITIAL, __VA_ARGS__); \
64 return NULL; \
65 } while (0)
66
67 /*
68 Returned from PETSc functions that are called from MPI, such as related to attributes
69 Do not confuse PETSC_MPI_ERROR_CODE and PETSC_ERR_MPI, the first is registered with MPI and returned to MPI as
70 an error code, the latter is a regular PETSc error code passed within PETSc code indicating an error was detected in an MPI call.
71 */
72 PETSC_EXTERN PetscMPIInt PETSC_MPI_ERROR_CLASS;
73 PETSC_EXTERN PetscMPIInt PETSC_MPI_ERROR_CODE;
74
75 /*MC
76 SETERRMPI - Macro to be called when an error has been detected within an MPI callback function
77
78 No Fortran Support
79
80 Synopsis:
81 #include <petscsys.h>
82 PetscErrorCode SETERRMPI(MPI_Comm comm, PetscErrorCode ierr, char *message, ...)
83
84 Collective
85
86 Input Parameters:
87 + comm - An MPI communicator, use `PETSC_COMM_SELF` unless you know all ranks of another communicator will detect the error
88 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
89 - message - error message
90
91 Level: developer
92
93 Note:
94 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`
95 which is registered with `MPI_Add_error_code()` when PETSc is initialized.
96
97 .seealso: `SETERRQ()`, `PetscCall()`, `PetscCallMPI()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ`, `PetscErrorCode`
98 M*/
99 #define SETERRMPI(comm, ierr, ...) return ((void)PetscError(comm, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr, PETSC_ERROR_INITIAL, __VA_ARGS__), PETSC_MPI_ERROR_CODE)
100
101 /*MC
102 SETERRA - Fortran-only macro that can be called when an error has been detected from the main program
103
104 Synopsis:
105 #include <petscsys.h>
106 PetscErrorCode SETERRA(MPI_Comm comm, PetscErrorCode ierr, char *message)
107
108 Collective
109
110 Input Parameters:
111 + comm - An MPI communicator, so that the error can be collective
112 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
113 - message - error message in the `printf()` format
114
115 Level: beginner
116
117 Notes:
118 This should only be used with Fortran. With C/C++, use `SETERRQ()`.
119
120 `SETERRQ()` may be called from Fortran subroutines but `SETERRA()` must be called from the
121 Fortran main program.
122
123 .seealso: `SETERRQ()`, `SETERRABORT()`, `PetscCall()`, `CHKERRA()`, `PetscCallAbort()`, `PetscErrorCode`
124 M*/
125
126 /*MC
127 SETERRABORT - Macro that can be called when an error has been detected,
128
129 Synopsis:
130 #include <petscsys.h>
131 PetscErrorCode SETERRABORT(MPI_Comm comm, PetscErrorCode ierr, char *message, ...)
132
133 Collective
134
135 Input Parameters:
136 + comm - An MPI communicator, so that the error can be collective
137 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
138 - message - error message in the `printf()` format
139
140 Level: beginner
141
142 Notes:
143 This function just calls `MPI_Abort()`.
144
145 This should only be called in routines that cannot return an error code, such as in C++ constructors.
146
147 Fortran Note:
148 Use `SETERRA()` in Fortran main program and `SETERRQ()` in Fortran subroutines
149
150 Developer Note:
151 In Fortran `SETERRA()` could be called `SETERRABORT()` since they serve the same purpose
152
153 .seealso: `SETERRQ()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, `PetscCall()`, `CHKMEMQ`, `PetscErrorCode`
154 M*/
155 #define SETERRABORT(comm, ierr, ...) \
156 do { \
157 (void)PetscError(comm, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr, PETSC_ERROR_INITIAL, __VA_ARGS__); \
158 (void)MPI_Abort(comm, ierr); \
159 } while (0)
160
161 /*MC
162 PetscCheck - Checks that a particular condition is true; if not true, then returns the provided error code
163
164 Synopsis:
165 #include <petscsys.h>
166 void PetscCheck(bool cond, MPI_Comm comm, PetscErrorCode ierr, const char *message, ...)
167
168 Collective; No Fortran Support
169
170 Input Parameters:
171 + cond - The boolean condition
172 . comm - The communicator on which the check can be collective on
173 . ierr - A nonzero error code, see include/petscerror.h for the complete list
174 - message - Error message in the `printf()` format
175
176 Level: beginner
177
178 Notes:
179 Enabled in both optimized and debug builds.
180
181 As a general rule, `PetscCheck()` is used to check "usage error" (for example, passing an incorrect value as a function argument),
182 `PetscAssert()` is used to "check for bugs in PETSc" (for example, is a value in a PETSc data structure nonsensical).
183 However, for functions that are called in a "hot spot", for example, thousands of times in a loop, `PetscAssert()` should be used instead
184 of `PetscCheck()` since the former is compiled out in PETSc's optimization code.
185
186 Calls `SETERRQ()` if the assertion fails, so can only be called from functions returning a
187 `PetscErrorCode` (or equivalent type after conversion).
188
189 .seealso: `PetscAssert()`, `PetscCheckReturnMPI()`, `SETERRQ()`, `PetscError()`, `PetscCall()`, `PetscCheckAbort()`, `PetscErrorCode`
190 M*/
191 #define PetscCheck(cond, comm, ierr, ...) \
192 do { \
193 if (PetscUnlikely(!(cond))) SETERRQ(comm, ierr, __VA_ARGS__); \
194 } while (0)
195
196 /*MC
197 PetscCheckReturnMPI - Checks that a particular condition is true; if not true, then returns an MPI error code.
198 To check for errors in PETSc-provided MPI callbacks.
199
200 Synopsis:
201 #include <petscsys.h>
202 void PetscCheckReturnMPI(bool cond, MPI_Comm comm, PetscErrorCode ierr, const char *message, ...)
203
204 Collective; No Fortran Support
205
206 Input Parameters:
207 + cond - The boolean condition
208 . comm - The communicator on which the check can be collective on
209 . ierr - A nonzero error code, see include/petscerror.h for the complete list
210 - message - Error message in the `printf()` format
211
212 Level: beginner
213
214 Note:
215 Enabled in both optimized and debug builds.
216
217 .seealso: `PetscCheck()`, `PetscAssert()`, `SETERRQ()`, `PetscError()`, `PetscCall()`, `PetscCheckAbort()`, `PetscErrorCode`
218 M*/
219 #define PetscCheckReturnMPI(cond, comm, ierr, ...) \
220 do { \
221 if (PetscUnlikely(!(cond))) SETERRMPI(comm, ierr, __VA_ARGS__); \
222 } while (0)
223
224 /*MC
225 PetscCheckAbort - Check that a particular condition is true, otherwise prints error and aborts
226
227 Synopsis:
228 #include <petscsys.h>
229 void PetscCheckAbort(bool cond, MPI_Comm comm, PetscErrorCode ierr, const char *message, ...)
230
231 Collective; No Fortran Support
232
233 Input Parameters:
234 + cond - The boolean condition
235 . comm - The communicator on which the check can be collective on
236 . ierr - A nonzero error code, see include/petscerror.h for the complete list
237 - message - Error message in the `printf()` format
238
239 Level: developer
240
241 Notes:
242 Enabled in both optimized and debug builds.
243
244 Calls `SETERRABORT()` if the assertion fails, can be called from a function that does not return an
245 error code, such as a C++ constructor. usually `PetscCheck()` should be used.
246
247 .seealso: `PetscAssertAbort()`, `PetscAssert()`, `SETERRQ()`, `PetscError()`, `PetscCall()`, `PetscCheck()`, `SETERRABORT()`, `PetscErrorCode`
248 M*/
249 #define PetscCheckAbort(cond, comm, ierr, ...) \
250 do { \
251 if (PetscUnlikely(!(cond))) SETERRABORT(comm, ierr, __VA_ARGS__); \
252 } while (0)
253
254 /*MC
255 PetscAssert - Assert that a particular condition is true
256
257 Synopsis:
258 #include <petscsys.h>
259 void PetscAssert(bool cond, MPI_Comm comm, PetscErrorCode ierr, const char *message, ...)
260
261 Collective; No Fortran Support
262
263 Input Parameters:
264 + cond - The boolean condition
265 . comm - The communicator on which the check can be collective on
266 . ierr - A nonzero error code, see include/petscerror.h for the complete list
267 - message - Error message in `printf()` format
268
269 Level: beginner
270
271 Notes:
272 Equivalent to `PetscCheck()` if debugging is enabled, and `PetscAssume(cond)` otherwise.
273
274 See `PetscCheck()` for usage and behaviour.
275
276 This is needed instead of simply using `assert()` because this correctly handles the collective nature of errors under MPI
277
278 .seealso: `PetscCheck()`, `SETERRQ()`, `PetscError()`, `PetscAssertAbort()`, `PetscErrorCode`
279 M*/
280 #if PetscDefined(USE_DEBUG)
281 #define PetscAssert(cond, comm, ierr, ...) PetscCheck(cond, comm, ierr, __VA_ARGS__)
282 #else
283 #define PetscAssert(cond, ...) PetscAssume(cond)
284 #endif
285
286 /*MC
287 PetscAssertAbort - Assert that a particular condition is true, otherwise prints error and aborts
288
289 Synopsis:
290 #include <petscsys.h>
291 void PetscAssertAbort(bool cond, MPI_Comm comm, PetscErrorCode ierr, const char *message, ...)
292
293 Collective; No Fortran Support
294
295 Input Parameters:
296 + cond - The boolean condition
297 . comm - The communicator on which the check can be collective on
298 . ierr - A nonzero error code, see include/petscerror.h for the complete list
299 - message - Error message in the `printf()` format
300
301 Level: beginner
302
303 Note:
304 Enabled only in debug builds. See `PetscCheckAbort()` for usage.
305
306 .seealso: `PetscCheckAbort()`, `PetscAssert()`, `PetscCheck()`, `SETERRABORT()`, `PetscError()`
307 M*/
308 #if PetscDefined(USE_DEBUG)
309 #define PetscAssertAbort(cond, comm, ierr, ...) PetscCheckAbort(cond, comm, ierr, __VA_ARGS__)
310 #else
311 #define PetscAssertAbort(cond, comm, ierr, ...) PetscAssume(cond)
312 #endif
313
314 /*MC
315 PetscCall - Calls a PETSc function and then checks the resulting error code, if it is
316 non-zero it calls the error handler and returns from the current function with the error
317 code.
318
319 Synopsis:
320 #include <petscsys.h>
321 void PetscCall(PetscFunction(args))
322
323 Not Collective
324
325 Input Parameter:
326 . PetscFunction - any PETSc function that returns an error code
327
328 Level: beginner
329
330 Notes:
331 Once the error handler is called the calling function is then returned from with the given
332 error code. Experienced users can set the error handler with `PetscPushErrorHandler()`.
333
334 `PetscCall()` cannot be used in functions returning a datatype not convertible to
335 `PetscErrorCode`. For example, `PetscCall()` may not be used in functions returning `void`, use
336 `PetscCallAbort()` or `PetscCallVoid()` in this case.
337
338 Example Usage:
339 .vb
340 PetscCall(PetscInitiailize(...)); // OK to call even when PETSc is not yet initialized!
341
342 struct my_struct
343 {
344 void *data;
345 } my_complex_type;
346
347 struct my_struct bar(void)
348 {
349 PetscCall(foo(15)); // ERROR PetscErrorCode not convertible to struct my_struct!
350 }
351
352 PetscCall(bar()) // ERROR input not convertible to PetscErrorCode
353 .ve
354
355 It is also possible to call this directly on a `PetscErrorCode` variable
356 .vb
357 PetscCall(ierr); // check if ierr is nonzero
358 .ve
359
360 Should not be used to call callback functions provided by users, `PetscCallBack()` should be used in that situation.
361
362 `PetscUseTypeMethod()` or `PetscTryTypeMethod()` should be used when calling functions pointers contained in a PETSc object's `ops` array
363
364 Fortran Notes:
365 The Fortran function in which this is used must declare a `PetscErrorCode` variable necessarily named `ierr`, and `ierr` must be
366 the final argument to the PETSc function being called.
367
368 In the main program and in Fortran subroutines that do not have `ierr` as the final return parameter, one
369 should use `PetscCallA()`
370
371 Example Fortran Usage:
372 .vb
373 PetscErrorCode ierr
374 Vec v
375
376 ...
377 PetscCall(VecShift(v, 1.0, ierr))
378 PetscCallA(VecShift(v, 1.0, ierr))
379 .ve
380
381 .seealso: `SETERRQ()`, `PetscCheck()`, `PetscAssert()`, `PetscTraceBackErrorHandler()`, `PetscCallMPI()`,
382 `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ`, `CHKERRA()`,
383 `CHKERRMPI()`, `PetscCallBack()`, `PetscCallAbort()`, `PetscCallVoid()`, `PetscCallNull()`
384 M*/
385
386 /*MC
387 PetscCallNull - Calls a PETSc function and then checks the resulting error code, if it is
388 non-zero it calls the error handler and returns a `NULL`
389
390 Synopsis:
391 #include <petscsys.h>
392 void PetscCallNull(PetscFunction(args))
393
394 Not Collective; No Fortran Support
395
396 Input Parameter:
397 . PetscFunction - any PETSc function that returns something that can be returned as a `NULL`
398
399 Level: developer
400
401 .seealso: `PetscCall()`, `SETERRQ()`, `PetscCheck()`, `PetscAssert()`, `PetscTraceBackErrorHandler()`, `PetscCallMPI()`,
402 `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ`, `CHKERRA()`,
403 `CHKERRMPI()`, `PetscCallBack()`, `PetscCallAbort()`, `PetscCallVoid()`, `PetscCall()`
404 M*/
405
406 /*MC
407 PetscCallA - Fortran-only macro that should be used in the main program and subroutines that do not have `ierr` as the final return parameter, to call PETSc functions instead of using
408 `PetscCall()` which should be used in other Fortran subroutines
409
410 Synopsis:
411 #include <petscsys.h>
412 PetscErrorCode PetscCallA(PetscFunction(arguments, ierr))
413
414 Collective
415
416 Input Parameter:
417 . PetscFunction(arguments,ierr) - the call to the function
418
419 Level: beginner
420
421 Notes:
422 This should only be used with Fortran. With C/C++, use `PetscCall()` always.
423
424 The Fortran function in which this is used must declare a `PetscErrorCode` variable necessarily named `ierr`
425 Use `SETERRA()` to set an error in a Fortran main program and `SETERRQ()` in Fortran subroutines
426
427 .seealso: `SETERRQ()`, `SETERRA()`, `SETERRABORT()`, `PetscCall()`, `CHKERRA()`, `PetscCallAbort()`
428 M*/
429
430 /*MC
431 PetscCallBack - Calls a user provided PETSc callback function and then checks the resulting error code, if it is non-zero it calls the error
432 handler and returns from the current function with the error code.
433
434 Synopsis:
435 #include <petscsys.h>
436 void PetscCallBack(const char *functionname, PetscFunction(args))
437
438 Not Collective; No Fortran Support
439
440 Input Parameters:
441 + functionname - the name of the function being called, this can be a string with spaces that describes the meaning of the callback
442 - PetscFunction - user provided callback function that returns an error code
443
444 Example Usage:
445 .vb
446 PetscCallBack("XXX callback to do something", a->callback(...));
447 .ve
448
449 Level: developer
450
451 Notes:
452 `PetscUseTypeMethod()` and ` PetscTryTypeMethod()` are the preferred API for this functionality. But when the callback functions are associated with a
453 `DMSNES` or `DMTS` this API must be used.
454
455 Once the error handler is called the calling function is then returned from with the given
456 error code. Experienced users can set the error handler with `PetscPushErrorHandler()`.
457
458 `PetscCallBack()` should only be called in PETSc when a call is being made to a user provided call-back routine.
459
460 Developer Note:
461 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
462
463 .seealso: `SETERRQ()`, `PetscCheck()`, `PetscCall()`, `PetscAssert()`, `PetscTraceBackErrorHandler()`, `PetscCallMPI()`
464 `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ`, `CHKERRA()`, `CHKERRMPI()`, `PetscCall()`, `PetscUseTypeMethod()`, `PetscTryTypeMethod()`
465 M*/
466
467 /*MC
468 PetscCallVoid - Like `PetscCall()` but for use in functions that return `void`
469
470 Synopsis:
471 #include <petscsys.h>
472 void PetscCallVoid(PetscFunction(args))
473
474 Not Collective; No Fortran Support
475
476 Input Parameter:
477 . PetscFunction - any PETSc function that returns an error code
478
479 Example Usage:
480 .vb
481 void foo()
482 {
483 KSP ksp;
484
485 PetscFunctionBeginUser;
486 // OK, properly handles PETSc error codes
487 PetscCallVoid(KSPCreate(PETSC_COMM_WORLD, &ksp));
488 PetscFunctionReturnVoid();
489 }
490
491 PetscErrorCode bar()
492 {
493 KSP ksp;
494
495 PetscFunctionBeginUser;
496 // ERROR, Non-void function 'bar' should return a value
497 PetscCallVoid(KSPCreate(PETSC_COMM_WORLD, &ksp));
498 // OK, returning PetscErrorCode
499 PetscCall(KSPCreate(PETSC_COMM_WORLD, &ksp));
500 PetscFunctionReturn(PETSC_SUCCESS);
501 }
502 .ve
503
504 Level: beginner
505
506 Notes:
507 Has identical usage to `PetscCall()`, except that it returns `void` on error instead of a
508 `PetscErrorCode`. See `PetscCall()` for more detailed discussion.
509
510 Note that users should prefer `PetscCallAbort()` to this routine. While this routine does
511 "handle" errors by returning from the enclosing function, it effectively gobbles the
512 error. Since the enclosing function itself returns `void`, its callers have no way of knowing
513 that the routine returned early due to an error. `PetscCallAbort()` at least ensures that the
514 program crashes gracefully.
515
516 .seealso: `PetscCall()`, `PetscErrorCode`, `PetscCallAbort()`, `PetscCallNull()`
517 M*/
518
519 /*MC
520 PetscCallReturnMPI - Calls a PETSc function and then checks the resulting error code, if it is
521 non-zero it calls the error handler and returns from the current function with an MPI error code.
522 To check for errors in PETSc provided MPI callbacks.
523
524 Synopsis:
525 #include <petscsys.h>
526 void PetscCallReturnMPI(PetscFunction(args))
527
528 Not Collective
529
530 Input Parameter:
531 . PetscFunction - any PETSc function that returns an error code
532
533 Level: advanced
534
535 Notes:
536 Note to be confused with `PetscCallMPI()`.
537
538 This is be used in a PETSc-provided MPI callback function, such as `MPI_Comm_delete_attr_function function()`.
539
540 Currently, it always returns `MPI_ERR_OTHER` on failure
541
542 .seealso: `PetscCall()`, `PetscCallMPI()`, `SETERRQ()`, `PetscCheck()`, `PetscAssert()`, `PetscTraceBackErrorHandler()`, `PetscCallMPI()`,
543 `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ`, `CHKERRA()`,
544 `CHKERRMPI()`, `PetscCallBack()`, `PetscCallAbort()`, `PetscCallVoid()`, `PetscCallNull()`
545 M*/
546
547 #if defined(PETSC_CLANG_STATIC_ANALYZER)
548 void PetscCall(PetscErrorCode);
549 void PetscCallBack(const char *, PetscErrorCode);
550 void PetscCallVoid(PetscErrorCode);
551 void PetscCallNull(PetscErrorCode);
552 void PetscCallReturnMPI(PetscErrorCode);
553 #else
554 #define PetscCall(...) \
555 do { \
556 PetscErrorCode ierr_petsc_call_q_; \
557 PetscStackUpdateLine; \
558 ierr_petsc_call_q_ = __VA_ARGS__; \
559 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, " "); \
560 } while (0)
561 #define PetscCallNull(...) \
562 do { \
563 PetscErrorCode ierr_petsc_call_q_; \
564 PetscStackUpdateLine; \
565 ierr_petsc_call_q_ = __VA_ARGS__; \
566 if (PetscUnlikely(ierr_petsc_call_q_ != PETSC_SUCCESS)) { \
567 (void)PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, PETSC_ERR_PLIB, PETSC_ERROR_INITIAL, " "); \
568 PetscFunctionReturn(NULL); \
569 } \
570 } while (0)
571 #define PetscCallBack(function, ...) \
572 do { \
573 PetscErrorCode ierr_petsc_call_q_; \
574 PetscStackUpdateLine; \
575 PetscStackPushExternal(function); \
576 ierr_petsc_call_q_ = __VA_ARGS__; \
577 PetscStackPop; \
578 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, " "); \
579 } while (0)
580 #define PetscCallVoid(...) \
581 do { \
582 PetscErrorCode ierr_petsc_call_void_; \
583 PetscStackUpdateLine; \
584 ierr_petsc_call_void_ = __VA_ARGS__; \
585 if (PetscUnlikely(ierr_petsc_call_void_ != PETSC_SUCCESS)) { \
586 (void)PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_petsc_call_void_, PETSC_ERROR_REPEAT, " "); \
587 return; \
588 } \
589 } while (0)
590 #define PetscCallReturnMPI(...) \
591 do { \
592 PetscErrorCode ierr_petsc_call_q_; \
593 PetscStackUpdateLine; \
594 ierr_petsc_call_q_ = __VA_ARGS__; \
595 if (PetscUnlikely(ierr_petsc_call_q_ != PETSC_SUCCESS)) { \
596 (void)PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_petsc_call_q_, PETSC_ERROR_REPEAT, " "); \
597 return MPI_ERR_OTHER; \
598 } \
599 } while (0)
600 #endif
601
602 /*MC
603 CHKERRQ - Checks error code returned from PETSc function
604
605 Synopsis:
606 #include <petscsys.h>
607 void CHKERRQ(PetscErrorCode ierr)
608
609 Not Collective
610
611 Input Parameter:
612 . ierr - nonzero error code
613
614 Level: deprecated
615
616 Note:
617 Deprecated in favor of `PetscCall()`. This routine behaves identically to it.
618
619 .seealso: `PetscCall()`
620 M*/
621 #define CHKERRQ(...) PetscCall(__VA_ARGS__)
622 #define CHKERRV(...) PetscCallVoid(__VA_ARGS__)
623
624 PETSC_EXTERN void PetscMPIErrorString(PetscMPIInt, size_t, char *);
625
626 /*MC
627 PetscCallMPI - Checks error code returned from MPI calls, if non-zero it calls the error
628 handler and then returns a `PetscErrorCode`
629
630 Synopsis:
631 #include <petscsys.h>
632 void PetscCallMPI(MPI_Function(args))
633
634 Not Collective
635
636 Input Parameter:
637 . MPI_Function - an MPI function that returns an MPI error code
638
639 Level: beginner
640
641 Notes:
642 Always returns the error code `PETSC_ERR_MPI`; the MPI error code and string are embedded in
643 the string error message. Do not use this to call any other routines (for example PETSc
644 routines), it should only be used for direct MPI calls. The user may configure PETSc with the
645 `--with-strict-petscerrorcode` option to check this at compile-time, otherwise they must
646 check this themselves.
647
648 This routine can only be used in functions returning `PetscErrorCode` themselves. If the
649 calling function returns a different type, use `PetscCallMPIAbort()` instead.
650
651 Example Usage:
652 .vb
653 PetscCallMPI(MPI_Comm_size(...)); // OK, calling MPI function
654
655 PetscCallMPI(PetscFunction(...)); // ERROR, use PetscCall() instead!
656 .ve
657
658 Fortran Notes:
659 The Fortran function from which this is used must declare a variable `PetscErrorCode` ierr and ierr must be
660 the final argument to the MPI function being called.
661
662 In the main program and in Fortran subroutines that do not have ierr as the final return parameter one
663 should use `PetscCallMPIA()`
664
665 Fortran Usage:
666 .vb
667 PetscErrorCode ierr or integer ierr
668 ...
669 PetscCallMPI(MPI_Comm_size(...,ierr))
670 PetscCallMPIA(MPI_Comm_size(...,ierr)) ! Will abort after calling error handler
671
672 PetscCallMPI(MPI_Comm_size(...,eflag)) ! ERROR, final argument must be ierr
673 .ve
674
675 .seealso: `SETERRMPI()`, `PetscCall()`, `PetscCallReturnMPI()`, `SETERRQ()`, `SETERRABORT()`, `PetscCallAbort()`,
676 `PetscCallMPIAbort()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`,
677 `PetscError()`, `CHKMEMQ`, `PetscCallMPINull()`
678 M*/
679
680 /*MC
681 PetscCallMPIReturnMPI - Checks error code returned from MPI calls, if non-zero it calls the error
682 handler and then returns an MPI error code. To check for errors in PETSc-provided MPI callbacks.
683
684 Synopsis:
685 #include <petscsys.h>
686 void PetscCallMPIReturnMPI(MPI_Function(args))
687
688 Not Collective
689
690 Input Parameter:
691 . MPI_Function - an MPI function that returns an MPI error code
692
693 Level: advanced
694
695 .seealso: `SETERRMPI()`, `PetscCall()`, `PetscCallMPI()`, `PetscCallReturnMPI()`, `SETERRQ()`, `SETERRABORT()`, `PetscCallAbort()`,
696 `PetscCallMPIAbort()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`,
697 `PetscError()`, `CHKMEMQ`, `PetscCallMPINull()`
698 M*/
699
700 /*MC
701 PetscCallMPINull - Checks error code returned from MPI calls, if non-zero it calls the error
702 handler and then returns a `NULL`
703
704 Synopsis:
705 #include <petscsys.h>
706 void PetscCallMPINull(MPI_Function(args))
707
708 Not Collective; No Fortran Support
709
710 Input Parameter:
711 . MPI_Function - an MPI function that returns an MPI error code
712
713 Level: beginner
714
715 Notes:
716 Always passes the error code `PETSC_ERR_MPI` to the error handler `PetscError()`; the MPI error code and string are embedded in
717 the string error message. Do not use this to call any other routines (for example PETSc
718 routines), it should only be used for direct MPI calls.
719
720 This routine can only be used in functions returning anything that can be returned as a `NULL` themselves. If the
721 calling function returns a different type, use `PetscCallMPIAbort()` instead.
722
723 Example Usage:
724 .vb
725 PetscCallMPINull(MPI_Comm_size(...)); // OK, calling MPI function
726
727 PetscCallMPI(PetscFunction(...)); // ERROR, use PetscCall() instead!
728 .ve
729
730 .seealso: `SETERRMPI()`, `PetscCall()`, `SETERRQ()`, `SETERRABORT()`, `PetscCallAbort()`,
731 `PetscCallMPIAbort()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`,
732 `PetscError()`, `CHKMEMQ`, `PetscCallMPI()`
733 M*/
734
735 /*MC
736 PetscCallMPIAbort - Like `PetscCallMPI()` but calls `MPI_Abort()` on error
737
738 Synopsis:
739 #include <petscsys.h>
740 void PetscCallMPIAbort(MPI_Comm comm, MPI_Function(args))
741
742 Not Collective
743
744 Input Parameters:
745 + comm - the MPI communicator to abort on
746 - MPI_Function - an MPI function that returns an MPI error code
747
748 Level: beginner
749
750 Notes:
751 Usage is identical to `PetscCallMPI()`. See `PetscCallMPI()` for detailed discussion.
752
753 This routine may be used in functions returning `void` or other non-`PetscErrorCode` types.
754
755 Fortran Note:
756 In Fortran this is called `PetscCallMPIA()` and is intended to be used in the main program while `PetscCallMPI()` is
757 used in Fortran subroutines.
758
759 Developer Note:
760 This should have the same name in Fortran.
761
762 .seealso: `PetscCallMPI()`, `PetscCallAbort()`, `SETERRABORT()`
763 M*/
764 #if defined(PETSC_CLANG_STATIC_ANALYZER)
765 void PetscCallMPI(PetscMPIInt);
766 void PetscCallMPIAbort(MPI_Comm, PetscMPIInt);
767 void PetscCallMPINull(PetscMPIInt);
768 #else
769 #define PetscCallMPI_Private(__PETSC_STACK_POP_FUNC__, __SETERR_FUNC__, __COMM__, ...) \
770 do { \
771 PetscMPIInt ierr_petsc_call_mpi_; \
772 PetscStackUpdateLine; \
773 PetscStackPushExternal("MPI function"); \
774 { \
775 ierr_petsc_call_mpi_ = __VA_ARGS__; \
776 } \
777 __PETSC_STACK_POP_FUNC__; \
778 if (PetscUnlikely(ierr_petsc_call_mpi_ != MPI_SUCCESS)) { \
779 char petsc_mpi_7_errorstring[2 * MPI_MAX_ERROR_STRING]; \
780 PetscMPIErrorString(ierr_petsc_call_mpi_, 2 * MPI_MAX_ERROR_STRING, (char *)petsc_mpi_7_errorstring); \
781 __SETERR_FUNC__(__COMM__, PETSC_ERR_MPI, "MPI error %d %s", ierr_petsc_call_mpi_, petsc_mpi_7_errorstring); \
782 } \
783 } while (0)
784
785 #define PetscCallMPI(...) PetscCallMPI_Private(PetscStackPop, SETERRQ, PETSC_COMM_SELF, __VA_ARGS__)
786 #define PetscCallMPIReturnMPI(...) PetscCallMPI_Private(PetscStackPopNoCheck(PETSC_FUNCTION_NAME), SETERRMPI, PETSC_COMM_SELF, __VA_ARGS__)
787 #define PetscCallMPIAbort(comm, ...) PetscCallMPI_Private(PetscStackPopNoCheck(PETSC_FUNCTION_NAME), SETERRABORT, comm, __VA_ARGS__)
788 #define PetscCallMPINull(...) PetscCallMPI_Private(PetscStackPopNoCheck(PETSC_FUNCTION_NAME), SETERRQNULL, PETSC_COMM_SELF, __VA_ARGS__)
789 #endif
790
791 /*MC
792 CHKERRMPI - Checks the error code returned from MPI calls, if different from `MPI_SUCCESS` it calls the error handler and then returns
793
794 Synopsis:
795 #include <petscsys.h>
796 void CHKERRMPI(PetscMPIInt ierr)
797
798 Not Collective
799
800 Input Parameter:
801 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
802
803 Level: deprecated
804
805 Note:
806 Deprecated in favor of `PetscCallMPI()`. This routine behaves identically to it.
807
808 .seealso: `PetscCallMPI()`
809 M*/
810 #define CHKERRMPI(...) PetscCallMPI(__VA_ARGS__)
811
812 /*MC
813 PetscCallAbort - Checks error code returned from PETSc function, if non-zero it aborts immediately by calling `MPI_Abort()`
814
815 Synopsis:
816 #include <petscsys.h>
817 void PetscCallAbort(MPI_Comm comm, PetscErrorCode ierr)
818
819 Collective
820
821 Input Parameters:
822 + comm - the MPI communicator on which to abort
823 - ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
824
825 Level: intermediate
826
827 Notes:
828 This macro has identical type and usage semantics to `PetscCall()` with the important caveat
829 that this macro does not return. Instead, if ierr is nonzero it calls the PETSc error handler
830 and then immediately calls `MPI_Abort()`. It can therefore be used anywhere.
831
832 As per `MPI_Abort()` semantics the communicator passed must be valid, although there is currently
833 no attempt made at handling any potential errors from `MPI_Abort()`. Note that while
834 `MPI_Abort()` is required to terminate only those processes which reside on comm, it is often
835 the case that `MPI_Abort()` terminates *all* processes.
836
837 Example Usage:
838 .vb
839 PetscErrorCode boom(void) { return PETSC_ERR_MEM; }
840
841 void foo(void)
842 {
843 PetscCallAbort(PETSC_COMM_WORLD,boom()); // OK, does not return a type
844 }
845
846 double bar(void)
847 {
848 PetscCallAbort(PETSC_COMM_WORLD,boom()); // OK, does not return a type
849 }
850
851 PetscCallAbort(MPI_COMM_NULL,boom()); // ERROR, communicator should be valid
852
853 struct baz
854 {
855 baz()
856 {
857 PetscCallAbort(PETSC_COMM_SELF,boom()); // OK
858 }
859
860 ~baz()
861 {
862 PetscCallAbort(PETSC_COMM_SELF,boom()); // OK (in fact the only way to handle PETSc errors)
863 }
864 };
865 .ve
866
867 Fortran Note:
868 Use `PetscCallA()`.
869
870 Developer Note:
871 This should have the same name in Fortran as in C.
872
873 .seealso: `SETERRABORT()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`,
874 `SETERRQ()`, `CHKMEMQ`, `PetscCallMPI()`, `PetscCallCXXAbort()`
875 M*/
876 #if defined(PETSC_CLANG_STATIC_ANALYZER)
877 void PetscCallAbort(MPI_Comm, PetscErrorCode);
878 void PetscCallContinue(PetscErrorCode);
879 #else
880 #define PetscCallAbort(comm, ...) \
881 do { \
882 PetscErrorCode ierr_petsc_call_abort_; \
883 PetscStackUpdateLine; \
884 ierr_petsc_call_abort_ = __VA_ARGS__; \
885 if (PetscUnlikely(ierr_petsc_call_abort_ != PETSC_SUCCESS)) { \
886 ierr_petsc_call_abort_ = PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_petsc_call_abort_, PETSC_ERROR_REPEAT, " "); \
887 (void)MPI_Abort(comm, (PetscMPIInt)ierr_petsc_call_abort_); \
888 } \
889 } while (0)
890 #define PetscCallContinue(...) \
891 do { \
892 PetscErrorCode ierr_petsc_call_continue_; \
893 PetscStackUpdateLine; \
894 ierr_petsc_call_continue_ = __VA_ARGS__; \
895 if (PetscUnlikely(ierr_petsc_call_continue_ != PETSC_SUCCESS)) { \
896 ierr_petsc_call_continue_ = PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_petsc_call_continue_, PETSC_ERROR_REPEAT, " "); \
897 (void)ierr_petsc_call_continue_; \
898 } \
899 } while (0)
900 #endif
901
902 /*MC
903 CHKERRABORT - Checks error code returned from PETSc function. If non-zero it aborts immediately.
904
905 Synopsis:
906 #include <petscsys.h>
907 void CHKERRABORT(MPI_Comm comm, PetscErrorCode ierr)
908
909 Not Collective
910
911 Input Parameters:
912 + comm - the MPI communicator
913 - ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
914
915 Level: deprecated
916
917 Note:
918 Deprecated in favor of `PetscCallAbort()`. This routine behaves identically to it.
919
920 .seealso: `PetscCallAbort()`, `PetscErrorCode`
921 M*/
922 #define CHKERRABORT(comm, ...) PetscCallAbort(comm, __VA_ARGS__)
923 #define CHKERRCONTINUE(...) PetscCallContinue(__VA_ARGS__)
924
925 /*MC
926 CHKERRA - Fortran-only replacement for use of `CHKERRQ()` in the main program, which aborts immediately
927
928 Synopsis:
929 #include <petscsys.h>
930 PetscErrorCode CHKERRA(PetscErrorCode ierr)
931
932 Not Collective
933
934 Input Parameter:
935 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
936
937 Level: deprecated
938
939 Note:
940 This macro is rarely needed, normal usage is `PetscCallA()` in the main Fortran program.
941
942 Developer Note:
943 Why isn't this named `CHKERRABORT()` in Fortran?
944
945 .seealso: `PetscCall()`, `PetscCallA()`, `PetscCallAbort()`, `CHKERRQ()`, `SETERRA()`, `SETERRQ()`, `SETERRABORT()`
946 M*/
947
948 PETSC_EXTERN PetscBool petscwaitonerrorflg;
949 PETSC_EXTERN PetscBool petscindebugger;
950 PETSC_EXTERN PetscBool petscabortmpifinalize;
951
952 #if defined(PETSC_CLANG_STATIC_ANALYZER)
953 void PETSCABORTWITHERR_Private(MPI_Comm, PetscErrorCode);
954 #else
955 #define PETSCABORTWITHIERR_Private(comm, ierr) \
956 do { \
957 PetscMPIInt size_; \
958 (void)MPI_Comm_size(comm, &size_); \
959 if (PetscCIEnabledPortableErrorOutput && (size_ == PetscGlobalSize || petscabortmpifinalize) && ierr != PETSC_ERR_SIG) { \
960 (void)MPI_Finalize(); \
961 exit(0); \
962 } else if (PetscCIEnabledPortableErrorOutput && PetscGlobalSize == 1) { \
963 exit(0); \
964 } else { \
965 (void)MPI_Abort(comm, (PetscMPIInt)ierr); \
966 } \
967 } while (0)
968 #endif
969
970 /*MC
971 PETSCABORT - Call `MPI_Abort()` with an informative error code
972
973 Synopsis:
974 #include <petscsys.h>
975 PETSCABORT(MPI_Comm comm, PetscErrorCode ierr)
976
977 Collective; No Fortran Support
978
979 Input Parameters:
980 + comm - An MPI communicator, so that the error can be collective
981 - ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
982
983 Level: advanced
984
985 Notes:
986 If the option `-start_in_debugger` was used then this calls `abort()` to stop the program in the debugger.
987
988 if `PetscCIEnabledPortableErrorOutput` is set, which means the code is running in the PETSc test harness (make test),
989 and `comm` is `MPI_COMM_WORLD` it strives to exit cleanly without calling `MPI_Abort()` and instead calling `MPI_Finalize()`.
990
991 This is currently only used when an error propagates up to the C `main()` program and is detected by a `PetscCall()`, `PetscCallMPI()`,
992 or is set in `main()` with `SETERRQ()`. Abort calls such as `SETERRABORT()`,
993 `PetscCheckAbort()`, `PetscCallMPIAbort()`, and `PetscCallAbort()` always call `MPI_Abort()` and do not have any special
994 handling for the test harness.
995
996 Developer Note:
997 Should the other abort calls also pass through this call instead of calling `MPI_Abort()` directly?
998
999 .seealso: `PetscError()`, `PetscCall()`, `SETERRABORT()`, `PetscCheckAbort()`, `PetscCallMPIAbort()`, `PetscCall()`, `PetscCallMPI()`,
1000 `PetscCallAbort()`, `MPI_Abort()`, `PetscErrorCode`
1001 M*/
1002 #if defined(PETSC_CLANG_STATIC_ANALYZER)
1003 void PETSCABORT(MPI_Comm, PetscErrorCode);
1004 #else
1005 #define PETSCABORT(comm, ...) \
1006 do { \
1007 PetscErrorCode ierr_petsc_abort_; \
1008 if (petscwaitonerrorflg) ierr_petsc_abort_ = PetscSleep(1000); \
1009 if (petscindebugger) abort(); \
1010 else { \
1011 ierr_petsc_abort_ = __VA_ARGS__; \
1012 PETSCABORTWITHIERR_Private(comm, ierr_petsc_abort_); \
1013 } \
1014 } while (0)
1015 #endif
1016
1017 #ifdef PETSC_CLANGUAGE_CXX
1018 /*MC
1019 PetscCallThrow - Checks error code, if non-zero it calls the C++ error handler which throws
1020 an exception
1021
1022 Synopsis:
1023 #include <petscsys.h>
1024 void PetscCallThrow(PetscErrorCode ierr)
1025
1026 Not Collective
1027
1028 Input Parameter:
1029 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
1030
1031 Level: beginner
1032
1033 Notes:
1034 Requires PETSc to be configured with clanguage of c++. Throws a std::runtime_error() on error.
1035
1036 Once the error handler throws the exception you can use `PetscCallVoid()` which returns without
1037 an error code (bad idea since the error is ignored) or `PetscCallAbort()` to have `MPI_Abort()`
1038 called immediately.
1039
1040 .seealso: `SETERRQ()`, `PetscCall()`, `SETERRABORT()`, `PetscCallAbort()`, `PetscTraceBackErrorHandler()`,
1041 `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ`
1042 M*/
1043 #define PetscCallThrow(...) \
1044 do { \
1045 PetscStackUpdateLine; \
1046 PetscErrorCode ierr_petsc_call_throw_ = __VA_ARGS__; \
1047 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); \
1048 } while (0)
1049
1050 /*MC
1051 CHKERRXX - Checks error code, if non-zero it calls the C++ error handler which throws an exception
1052
1053 Synopsis:
1054 #include <petscsys.h>
1055 void CHKERRXX(PetscErrorCode ierr)
1056
1057 Not Collective
1058
1059 Input Parameter:
1060 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
1061
1062 Level: deprecated
1063
1064 Note:
1065 Deprecated in favor of `PetscCallThrow()`. This routine behaves identically to it.
1066
1067 .seealso: `PetscCallThrow()`
1068 M*/
1069 #define CHKERRXX(...) PetscCallThrow(__VA_ARGS__)
1070 #endif
1071
1072 #define PetscCallCXX_Private(__SETERR_FUNC__, __COMM__, ...) \
1073 do { \
1074 PetscStackUpdateLine; \
1075 try { \
1076 __VA_ARGS__; \
1077 } catch (const std::exception &e) { \
1078 __SETERR_FUNC__(__COMM__, PETSC_ERR_LIB, "%s", e.what()); \
1079 } \
1080 } while (0)
1081
1082 /*MC
1083 PetscCallCXX - Checks C++ function calls and if they throw an exception, catch it and then
1084 return a PETSc error code
1085
1086 Synopsis:
1087 #include <petscsys.h>
1088 void PetscCallCXX(...) noexcept;
1089
1090 Not Collective
1091
1092 Input Parameter:
1093 . __VA_ARGS__ - An arbitrary expression
1094
1095 Level: beginner
1096
1097 Notes:
1098 `PetscCallCXX(...)` is a macro replacement for
1099 .vb
1100 try {
1101 __VA_ARGS__;
1102 } catch (const std::exception& e) {
1103 return ConvertToPetscErrorCode(e);
1104 }
1105 .ve
1106 Due to the fact that it catches any (reasonable) exception, it is essentially noexcept.
1107
1108 If you cannot return a `PetscErrorCode` use `PetscCallCXXAbort()` instead.
1109
1110 Example Usage:
1111 .vb
1112 void foo(void) { throw std::runtime_error("error"); }
1113
1114 void bar()
1115 {
1116 PetscCallCXX(foo()); // ERROR bar() does not return PetscErrorCode
1117 }
1118
1119 PetscErrorCode baz()
1120 {
1121 PetscCallCXX(foo()); // OK
1122
1123 PetscCallCXX(
1124 bar();
1125 foo(); // OK multiple statements allowed
1126 );
1127 }
1128
1129 struct bop
1130 {
1131 bop()
1132 {
1133 PetscCallCXX(foo()); // ERROR returns PetscErrorCode, cannot be used in constructors
1134 }
1135 };
1136
1137 // ERROR contains do-while, cannot be used as function-try block
1138 PetscErrorCode qux() PetscCallCXX(
1139 bar();
1140 baz();
1141 foo();
1142 return 0;
1143 )
1144 .ve
1145
1146 .seealso: `PetscCallCXXAbort()`, `PetscCallThrow()`, `SETERRQ()`, `PetscCall()`,
1147 `SETERRABORT()`, `PetscCallAbort()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`,
1148 `PetscError()`, `CHKMEMQ`
1149 M*/
1150 #define PetscCallCXX(...) PetscCallCXX_Private(SETERRQ, PETSC_COMM_SELF, __VA_ARGS__)
1151
1152 /*MC
1153 PetscCallCXXAbort - Like `PetscCallCXX()` but calls `MPI_Abort()` instead of returning an
1154 error-code
1155
1156 Synopsis:
1157 #include <petscsys.h>
1158 void PetscCallCXXAbort(MPI_Comm comm, ...) noexcept;
1159
1160 Collective; No Fortran Support
1161
1162 Input Parameters:
1163 + comm - The MPI communicator to abort on
1164 - __VA_ARGS__ - An arbitrary expression
1165
1166 Level: beginner
1167
1168 Notes:
1169 This macro may be used to check C++ expressions for exceptions in cases where you cannot
1170 return an error code. This includes constructors, destructors, copy/move assignment functions
1171 or constructors among others.
1172
1173 If an exception is caught, the macro calls `SETERRABORT()` on `comm`. The exception must
1174 derive from `std::exception` in order to be caught.
1175
1176 If the routine _can_ return an error-code it is highly advised to use `PetscCallCXX()`
1177 instead.
1178
1179 See `PetscCallCXX()` for additional discussion.
1180
1181 Example Usage:
1182 .vb
1183 class Foo
1184 {
1185 std::vector<int> data_;
1186
1187 public:
1188 // normally std::vector::reserve() may raise an exception, but since we handle it with
1189 // PetscCallCXXAbort() we may mark this routine as noexcept!
1190 Foo() noexcept
1191 {
1192 PetscCallCXXAbort(PETSC_COMM_SELF, data_.reserve(10));
1193 }
1194 };
1195
1196 std::vector<int> bar()
1197 {
1198 std::vector<int> v;
1199
1200 PetscFunctionBegin;
1201 // OK!
1202 PetscCallCXXAbort(PETSC_COMM_SELF, v.emplace_back(1));
1203 PetscFunctionReturn(v);
1204 }
1205
1206 PetscErrorCode baz()
1207 {
1208 std::vector<int> v;
1209
1210 PetscFunctionBegin;
1211 // WRONG! baz() returns a PetscErrorCode, prefer PetscCallCXX() instead
1212 PetscCallCXXAbort(PETSC_COMM_SELF, v.emplace_back(1));
1213 PetscFunctionReturn(PETSC_SUCCESS);
1214 }
1215 .ve
1216
1217 .seealso: `PetscCallCXX()`, `SETERRABORT()`, `PetscCallAbort()`
1218 M*/
1219 #define PetscCallCXXAbort(comm, ...) PetscCallCXX_Private(SETERRABORT, comm, __VA_ARGS__)
1220
1221 /*MC
1222 CHKERRCXX - Checks C++ function calls and if they throw an exception, catch it and then
1223 return a PETSc error code
1224
1225 Synopsis:
1226 #include <petscsys.h>
1227 void CHKERRCXX(func) noexcept;
1228
1229 Not Collective
1230
1231 Input Parameter:
1232 . func - C++ function calls
1233
1234 Level: deprecated
1235
1236 Note:
1237 Deprecated in favor of `PetscCallCXX()`. This routine behaves identically to it.
1238
1239 .seealso: `PetscCallCXX()`
1240 M*/
1241 #define CHKERRCXX(...) PetscCallCXX(__VA_ARGS__)
1242
1243 /*MC
1244 CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected
1245
1246 Synopsis:
1247 #include <petscsys.h>
1248 CHKMEMQ;
1249
1250 Not Collective
1251
1252 Level: beginner
1253
1254 Notes:
1255 We recommend using Valgrind <https://petsc.org/release/faq/#valgrind> or Compute Sanitizer
1256 <https://developer.nvidia.com/compute-sanitizer> on NVIDIA CUDA systems for finding memory problems. The ``CHKMEMQ``
1257 macro is useful on systems that do not have `valgrind`, but is not as good as `valgrind` or `compute-sanitizer`.
1258
1259 Must run with the option `-malloc_debug` (`-malloc_test` in debug mode; or if `PetscMallocSetDebug()` called) to enable this option
1260
1261 Once the error handler is called the calling function is then returned from with the given error code.
1262
1263 By defaults prints location where memory that is corrupted was allocated.
1264
1265 Use `CHKMEMA` for functions that return `void`
1266
1267 .seealso: `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, `SETERRQ()`, `PetscMallocValidate()`
1268 M*/
1269 #if defined(PETSC_CLANG_STATIC_ANALYZER)
1270 #define CHKMEMQ
1271 #define CHKMEMA
1272 #else
1273 #define CHKMEMQ \
1274 do { \
1275 PetscErrorCode ierr_petsc_memq_ = PetscMallocValidate(__LINE__, PETSC_FUNCTION_NAME, __FILE__); \
1276 if (PetscUnlikely(ierr_petsc_memq_ != PETSC_SUCCESS)) return PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_petsc_memq_, PETSC_ERROR_REPEAT, " "); \
1277 } while (0)
1278 #define CHKMEMA PetscMallocValidate(__LINE__, PETSC_FUNCTION_NAME, __FILE__)
1279 #endif
1280
1281 /*E
1282 PetscErrorType - passed to the PETSc error handling routines indicating if this is the first or a later call to the error handlers
1283
1284 Level: advanced
1285
1286 Note:
1287 `PETSC_ERROR_IN_CXX` indicates the error was detected in C++ and an exception should be generated
1288
1289 Developer Note:
1290 This is currently used to decide when to print the detailed information about the run in `PetscTraceBackErrorHandler()`
1291
1292 .seealso: `PetscError()`, `SETERRQ()`
1293 E*/
1294 typedef enum {
1295 PETSC_ERROR_INITIAL = 0,
1296 PETSC_ERROR_REPEAT = 1,
1297 PETSC_ERROR_IN_CXX = 2
1298 } PetscErrorType;
1299
1300 #if defined(__clang_analyzer__)
1301 __attribute__((analyzer_noreturn))
1302 #endif
1303 PETSC_EXTERN PetscErrorCode PetscError(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, ...) PETSC_ATTRIBUTE_COLD PETSC_ATTRIBUTE_FORMAT(7, 8);
1304
1305 PETSC_EXTERN PetscErrorCode PetscErrorPrintfInitialize(void);
1306 PETSC_EXTERN PetscErrorCode PetscErrorMessage(PetscErrorCode, const char *[], char **);
1307 PETSC_EXTERN PetscErrorCode PetscTraceBackErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD;
1308 PETSC_EXTERN PetscErrorCode PetscIgnoreErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD;
1309 PETSC_EXTERN PetscErrorCode PetscEmacsClientErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD;
1310 PETSC_EXTERN PetscErrorCode PetscMPIAbortErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD;
1311 PETSC_EXTERN PetscErrorCode PetscAbortErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD;
1312 PETSC_EXTERN PetscErrorCode PetscAttachDebuggerErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD;
1313 PETSC_EXTERN PetscErrorCode PetscReturnErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD;
1314 PETSC_EXTERN PetscErrorCode PetscPushErrorHandler(PetscErrorCode (*handler)(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *), void *);
1315 PETSC_EXTERN PetscErrorCode PetscPopErrorHandler(void);
1316 PETSC_EXTERN PetscErrorCode PetscSignalHandlerDefault(int, void *);
1317 PETSC_EXTERN PetscErrorCode PetscPushSignalHandler(PetscErrorCode (*)(int, void *), void *);
1318 PETSC_EXTERN PetscErrorCode PetscPopSignalHandler(void);
1319 PETSC_EXTERN PetscErrorCode PetscCheckPointerSetIntensity(PetscInt);
1320 PETSC_EXTERN void PetscSignalSegvCheckPointerOrMpi(void);
PetscSignalSegvCheckPointer(void)1321 PETSC_DEPRECATED_FUNCTION(3, 13, 0, "PetscSignalSegvCheckPointerOrMpi()", ) static inline void PetscSignalSegvCheckPointer(void)
1322 {
1323 PetscSignalSegvCheckPointerOrMpi();
1324 }
1325
1326 /*MC
1327 PetscErrorPrintf - Prints error messages.
1328
1329 Synopsis:
1330 #include <petscsys.h>
1331 PetscErrorCode (*PetscErrorPrintf)(const char format[], ...);
1332
1333 Not Collective; No Fortran Support
1334
1335 Input Parameter:
1336 . format - the usual `printf()` format string
1337
1338 Options Database Keys:
1339 + -error_output_stdout - cause error messages to be printed to stdout instead of the (default) stderr
1340 - -error_output_none - to turn off all printing of error messages (does not change the way the error is handled.)
1341
1342 Level: developer
1343
1344 Notes:
1345 Use
1346 .vb
1347 PetscErrorPrintf = PetscErrorPrintfNone; to turn off all printing of error messages (does not change the way the error is handled) and
1348 PetscErrorPrintf = PetscErrorPrintfDefault; to turn it back on or you can use your own function
1349 .ve
1350 Use
1351 .vb
1352 `PETSC_STDERR` = FILE* obtained from a file open etc. to have stderr printed to the file.
1353 `PETSC_STDOUT` = FILE* obtained from a file open etc. to have stdout printed to the file.
1354 .ve
1355 Use
1356 .vb
1357 `PetscPushErrorHandler()` to provide your own error handler that determines what kind of messages to print
1358 .ve
1359
1360 .seealso: `PetscFPrintf()`, `PetscSynchronizedPrintf()`, `PetscHelpPrintf()`, `PetscPrintf()`, `PetscPushErrorHandler()`, `PetscVFPrintf()`, `PetscHelpPrintf()`
1361 M*/
1362 PETSC_EXTERN PetscErrorCode (*PetscErrorPrintf)(const char[], ...) PETSC_ATTRIBUTE_FORMAT(1, 2);
1363
1364 /*E
1365 PetscFPTrap - types of floating point exceptions that may be trapped
1366
1367 Currently only `PETSC_FP_TRAP_OFF` and `PETSC_FP_TRAP_ON` are handled. All others are treated as `PETSC_FP_TRAP_ON`.
1368
1369 Level: intermediate
1370
1371 .seealso: `PetscSetFPTrap()`, `PetscFPTrapPush()`
1372 E*/
1373 typedef enum {
1374 PETSC_FP_TRAP_OFF = 0,
1375 PETSC_FP_TRAP_INDIV = 1,
1376 PETSC_FP_TRAP_FLTOPERR = 2,
1377 PETSC_FP_TRAP_FLTOVF = 4,
1378 PETSC_FP_TRAP_FLTUND = 8,
1379 PETSC_FP_TRAP_FLTDIV = 16,
1380 PETSC_FP_TRAP_FLTINEX = 32,
1381 PETSC_FP_TRAP_ON = 63
1382 } PetscFPTrap;
1383
1384 PETSC_EXTERN PetscErrorCode PetscSetFPTrap(PetscFPTrap);
1385 PETSC_EXTERN PetscErrorCode PetscFPTrapPush(PetscFPTrap);
1386 PETSC_EXTERN PetscErrorCode PetscFPTrapPop(void);
1387 PETSC_EXTERN PetscErrorCode PetscDetermineInitialFPTrap(void);
1388
1389 /*
1390 Allows the code to build a stack frame as it runs
1391 */
1392
1393 #define PETSCSTACKSIZE 64
1394 typedef struct {
1395 const char *function[PETSCSTACKSIZE];
1396 const char *file[PETSCSTACKSIZE];
1397 int line[PETSCSTACKSIZE];
1398 int petscroutine[PETSCSTACKSIZE]; /* 0 external called from PETSc, 1 PETSc functions, 2 PETSc user functions */
1399 int currentsize;
1400 int hotdepth;
1401 PetscBool check; /* option to check for correct Push/Pop semantics, true for default petscstack but not other stacks */
1402 } PetscStack;
1403 #if defined(PETSC_USE_DEBUG) && !defined(PETSC_HAVE_THREADSAFETY)
1404 PETSC_EXTERN PetscStack petscstack;
1405 #endif
1406
1407 #if defined(PETSC_SERIALIZE_FUNCTIONS)
1408 #include <petsc/private/petscfptimpl.h>
1409 /*
1410 Registers the current function into the global function pointer to function name table
1411
1412 Have to fix this to handle errors but cannot return error since used in PETSC_VIEWER_DRAW_() etc
1413 */
1414 #define PetscRegister__FUNCT__() \
1415 do { \
1416 static PetscBool __chked = PETSC_FALSE; \
1417 if (!__chked) { \
1418 void *ptr; \
1419 PetscCallAbort(PETSC_COMM_SELF, PetscDLSym(NULL, PETSC_FUNCTION_NAME, &ptr)); \
1420 __chked = PETSC_TRUE; \
1421 } \
1422 } while (0)
1423 #else
1424 #define PetscRegister__FUNCT__()
1425 #endif
1426
1427 #if defined(PETSC_CLANG_STATIC_ANALYZER) || defined(__clang_analyzer__)
1428 #define PetscStackPushNoCheck(funct, petsc_routine, hot)
1429 #define PetscStackUpdateLine
1430 #define PetscStackPushExternal(funct)
1431 #define PetscStackPopNoCheck(funct)
1432 #define PetscStackClearTop
1433 #define PetscFunctionBegin
1434 #define PetscFunctionBeginUser
1435 #define PetscFunctionBeginHot
1436 #define PetscFunctionReturn(...) return __VA_ARGS__
1437 #define PetscFunctionReturnVoid() return
1438 #define PetscStackPop
1439 #define PetscStackPush(f)
1440 #define PetscStackPush_Private(stack__, file__, func__, line__, petsc_routine__, hot__) \
1441 (void)file__; \
1442 (void)func__; \
1443 (void)line__
1444 #define PetscStackPop_Private(stack__, func__) (void)func__
1445 #elif defined(PETSC_USE_DEBUG) && !defined(PETSC_HAVE_THREADSAFETY)
1446
1447 #define PetscStackPush_Private(stack__, file__, func__, line__, petsc_routine__, hot__) \
1448 do { \
1449 if (stack__.currentsize < PETSCSTACKSIZE) { \
1450 stack__.function[stack__.currentsize] = func__; \
1451 if (petsc_routine__) { \
1452 stack__.file[stack__.currentsize] = file__; \
1453 stack__.line[stack__.currentsize] = line__; \
1454 } else { \
1455 stack__.file[stack__.currentsize] = PETSC_NULLPTR; \
1456 stack__.line[stack__.currentsize] = 0; \
1457 } \
1458 stack__.petscroutine[stack__.currentsize] = petsc_routine__; \
1459 } \
1460 ++stack__.currentsize; \
1461 stack__.hotdepth += (hot__ || stack__.hotdepth); \
1462 } while (0)
1463
1464 /* uses PetscCheckAbort() because may be used in a function that does not return an error code */
1465 #define PetscStackPop_Private(stack__, func__) \
1466 do { \
1467 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__); \
1468 if (--stack__.currentsize < PETSCSTACKSIZE) { \
1469 PetscCheckAbort(!stack__.check || stack__.petscroutine[stack__.currentsize] != 1 || stack__.function[stack__.currentsize] == func__, PETSC_COMM_SELF, PETSC_ERR_PLIB, "Invalid stack: push from %s %s:%d. Pop from %s %s:%d.\n", \
1470 stack__.function[stack__.currentsize], stack__.file[stack__.currentsize], stack__.line[stack__.currentsize], func__, __FILE__, __LINE__); \
1471 stack__.function[stack__.currentsize] = PETSC_NULLPTR; \
1472 stack__.file[stack__.currentsize] = PETSC_NULLPTR; \
1473 stack__.line[stack__.currentsize] = 0; \
1474 stack__.petscroutine[stack__.currentsize] = 0; \
1475 } \
1476 stack__.hotdepth = PetscMax(stack__.hotdepth - 1, 0); \
1477 } while (0)
1478
1479 /*MC
1480 PetscStackPushNoCheck - Pushes a new function name and line number onto the PETSc default stack that tracks where the running program is
1481 currently in the source code.
1482
1483 Synopsis:
1484 #include <petscsys.h>
1485 void PetscStackPushNoCheck(char *funct,int petsc_routine,PetscBool hot);
1486
1487 Not Collective
1488
1489 Input Parameters:
1490 + funct - the function name
1491 . petsc_routine - 2 user function, 1 PETSc function, 0 some other function
1492 - hot - indicates that the function may be called often so expensive error checking should be turned off inside the function
1493
1494 Level: developer
1495
1496 Notes:
1497 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
1498 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
1499 help debug the problem.
1500
1501 This version does not check the memory corruption (an expensive operation), use `PetscStackPush()` to check the memory.
1502
1503 Use `PetscStackPushExternal()` for a function call that is about to be made to a non-PETSc or user function (such as BLAS etc).
1504
1505 The default stack is a global variable called `petscstack`.
1506
1507 .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPopNoCheck()`, `PetscCall()`, `PetscFunctionBegin()`,
1508 `PetscFunctionReturn()`, `PetscFunctionBeginHot()`, `PetscFunctionBeginUser()`, `PetscStackPush()`, `PetscStackPop`,
1509 `PetscStackPushExternal()`
1510 M*/
1511 #define PetscStackPushNoCheck(funct, petsc_routine, hot) \
1512 do { \
1513 PetscStackSAWsTakeAccess(); \
1514 PetscStackPush_Private(petscstack, __FILE__, funct, __LINE__, petsc_routine, hot); \
1515 PetscStackSAWsGrantAccess(); \
1516 } while (0)
1517
1518 /*MC
1519 PetscStackUpdateLine - in a function that has a `PetscFunctionBegin` or `PetscFunctionBeginUser` updates the stack line number to the
1520 current line number.
1521
1522 Synopsis:
1523 #include <petscsys.h>
1524 void PetscStackUpdateLine
1525
1526 Not Collective
1527
1528 Level: developer
1529
1530 Notes:
1531 Using `PetscCall()` and friends automatically handles this process
1532
1533 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
1534 occurred, for example, when a signal is received. It is recommended to use the debugger if extensive information is needed to
1535 help debug the problem.
1536
1537 The default stack is a global variable called `petscstack`.
1538
1539 This is used by `PetscCall()` and is otherwise not like to be needed
1540
1541 .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPushNoCheck()`, `PetscStackPop`, `PetscCall()`
1542 M*/
1543 #define PetscStackUpdateLine \
1544 do { \
1545 if (petscstack.currentsize > 0 && petscstack.currentsize < PETSCSTACKSIZE && petscstack.function[petscstack.currentsize - 1] == PETSC_FUNCTION_NAME) petscstack.line[petscstack.currentsize - 1] = __LINE__; \
1546 } while (0)
1547
1548 /*MC
1549 PetscStackPushExternal - Pushes a new function name onto the PETSc default stack that tracks where the running program is
1550 currently in the source code. Does not include the filename or line number since this is called by the calling routine
1551 for non-PETSc or user functions.
1552
1553 Synopsis:
1554 #include <petscsys.h>
1555 void PetscStackPushExternal(char *funct);
1556
1557 Not Collective
1558
1559 Input Parameter:
1560 . funct - the function name
1561
1562 Level: developer
1563
1564 Notes:
1565 Using `PetscCallExternal()` and friends automatically handles this process
1566
1567 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
1568 occurred, for example, when a signal is received. It is recommended to use the debugger if extensive information is needed to
1569 help debug the problem.
1570
1571 The default stack is a global variable called `petscstack`.
1572
1573 This is to be used when calling an external package function such as a BLAS function.
1574
1575 This also updates the stack line number for the current stack function.
1576
1577 .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPopNoCheck()`, `PetscCall()`, `PetscFunctionBegin()`,
1578 `PetscFunctionReturn()`, `PetscFunctionBeginHot()`, `PetscFunctionBeginUser()`, `PetscStackPushNoCheck()`, `PetscStackPop`
1579 M*/
1580 #define PetscStackPushExternal(funct) \
1581 do { \
1582 PetscStackUpdateLine; \
1583 PetscStackPushNoCheck(funct, 0, PETSC_TRUE); \
1584 } while (0)
1585
1586 /*MC
1587 PetscStackPopNoCheck - Pops a function name from the PETSc default stack that tracks where the running program is
1588 currently in the source code.
1589
1590 Synopsis:
1591 #include <petscsys.h>
1592 void PetscStackPopNoCheck(char *funct);
1593
1594 Not Collective
1595
1596 Input Parameter:
1597 . funct - the function name
1598
1599 Level: developer
1600
1601 Notes:
1602 Using `PetscCall()`, `PetscCallExternal()`, `PetscCallBack()` and friends negates the need to call this
1603
1604 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
1605 occurred, for example, when a signal is received. It is recommended to use the debugger if extensive information is needed to
1606 help debug the problem.
1607
1608 The default stack is a global variable called `petscstack`.
1609
1610 Developer Note:
1611 `PetscStackPopNoCheck()` takes a function argument while `PetscStackPop` does not, this difference is likely just historical.
1612
1613 .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPushNoCheck()`, `PetscStackPop`
1614 M*/
1615 #define PetscStackPopNoCheck(funct) \
1616 do { \
1617 PetscStackSAWsTakeAccess(); \
1618 PetscStackPop_Private(petscstack, funct); \
1619 PetscStackSAWsGrantAccess(); \
1620 } while (0)
1621
1622 #define PetscStackClearTop \
1623 do { \
1624 PetscStackSAWsTakeAccess(); \
1625 if (petscstack.currentsize > 0 && --petscstack.currentsize < PETSCSTACKSIZE) { \
1626 petscstack.function[petscstack.currentsize] = PETSC_NULLPTR; \
1627 petscstack.file[petscstack.currentsize] = PETSC_NULLPTR; \
1628 petscstack.line[petscstack.currentsize] = 0; \
1629 petscstack.petscroutine[petscstack.currentsize] = 0; \
1630 } \
1631 petscstack.hotdepth = PetscMax(petscstack.hotdepth - 1, 0); \
1632 PetscStackSAWsGrantAccess(); \
1633 } while (0)
1634
1635 /*MC
1636 PetscFunctionBegin - First executable line of each PETSc function, used for error handling. Final
1637 line of PETSc functions should be `PetscFunctionReturn`(0);
1638
1639 Synopsis:
1640 #include <petscsys.h>
1641 void PetscFunctionBegin;
1642
1643 Not Collective; No Fortran Support
1644
1645 Usage:
1646 .vb
1647 int something;
1648
1649 PetscFunctionBegin;
1650 .ve
1651
1652 Level: developer
1653
1654 Note:
1655 Use `PetscFunctionBeginUser` for application codes.
1656
1657 .seealso: `PetscFunctionReturn()`, `PetscFunctionBeginHot()`, `PetscFunctionBeginUser()`, `PetscStackPushNoCheck()`
1658
1659 M*/
1660 #define PetscFunctionBegin \
1661 do { \
1662 PetscStackPushNoCheck(PETSC_FUNCTION_NAME, 1, PETSC_FALSE); \
1663 PetscRegister__FUNCT__(); \
1664 } while (0)
1665
1666 /*MC
1667 PetscFunctionBeginHot - Substitute for `PetscFunctionBegin` to be used in functions that are called in
1668 performance-critical circumstances. Use of this function allows for lighter profiling by default.
1669
1670 Synopsis:
1671 #include <petscsys.h>
1672 void PetscFunctionBeginHot;
1673
1674 Not Collective; No Fortran Support
1675
1676 Usage:
1677 .vb
1678 int something;
1679
1680 PetscFunctionBeginHot;
1681 .ve
1682
1683 Level: developer
1684
1685 .seealso: `PetscFunctionBegin`, `PetscFunctionReturn()`, `PetscStackPushNoCheck()`
1686
1687 M*/
1688 #define PetscFunctionBeginHot \
1689 do { \
1690 PetscStackPushNoCheck(PETSC_FUNCTION_NAME, 1, PETSC_TRUE); \
1691 PetscRegister__FUNCT__(); \
1692 } while (0)
1693
1694 /*MC
1695 PetscFunctionBeginUser - First executable line of user provided routines
1696
1697 Synopsis:
1698 #include <petscsys.h>
1699 void PetscFunctionBeginUser;
1700
1701 Not Collective; No Fortran Support
1702
1703 Usage:
1704 .vb
1705 int something;
1706
1707 PetscFunctionBeginUser;
1708 .ve
1709
1710 Level: intermediate
1711
1712 Notes:
1713 Functions that incorporate this must call `PetscFunctionReturn()` instead of return except for main().
1714
1715 May be used before `PetscInitialize()`
1716
1717 This is identical to `PetscFunctionBegin` except it labels the routine as a user
1718 routine instead of as a PETSc library routine.
1719
1720 .seealso: `PetscFunctionReturn()`, `PetscFunctionBegin`, `PetscFunctionBeginHot`, `PetscStackPushNoCheck()`
1721 M*/
1722 #define PetscFunctionBeginUser \
1723 do { \
1724 PetscStackPushNoCheck(PETSC_FUNCTION_NAME, 2, PETSC_FALSE); \
1725 PetscRegister__FUNCT__(); \
1726 } while (0)
1727
1728 /*MC
1729 PetscStackPush - Pushes a new function name and line number onto the PETSc default stack that tracks where the running program is
1730 currently in the source code and verifies the memory is not corrupted.
1731
1732 Synopsis:
1733 #include <petscsys.h>
1734 void PetscStackPush(char *funct)
1735
1736 Not Collective
1737
1738 Input Parameter:
1739 . funct - the function name
1740
1741 Level: developer
1742
1743 Notes:
1744 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
1745 occurred, for example, when a signal is received. It is recommended to use the debugger if extensive information is needed to
1746 help debug the problem.
1747
1748 The default stack is a global variable called `petscstack`.
1749
1750 .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPopNoCheck()`, `PetscCall()`, `PetscFunctionBegin()`,
1751 `PetscFunctionReturn()`, `PetscFunctionBeginHot()`, `PetscFunctionBeginUser()`, `PetscStackPushNoCheck()`, `PetscStackPop`
1752 M*/
1753 #define PetscStackPush(n) \
1754 do { \
1755 PetscStackPushNoCheck(n, 0, PETSC_FALSE); \
1756 CHKMEMQ; \
1757 } while (0)
1758
1759 /*MC
1760 PetscStackPop - Pops a function name from the PETSc default stack that tracks where the running program is
1761 currently in the source code and verifies the memory is not corrupted.
1762
1763 Synopsis:
1764 #include <petscsys.h>
1765 void PetscStackPop
1766
1767 Not Collective
1768
1769 Level: developer
1770
1771 Notes:
1772 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
1773 occurred, for example, when a signal is received. It is recommended to use the debugger if extensive information is needed to
1774 help debug the problem.
1775
1776 The default stack is a global variable called `petscstack`.
1777
1778 .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPushNoCheck()`, `PetscStackPopNoCheck()`, `PetscStackPush()`
1779 M*/
1780 #define PetscStackPop \
1781 do { \
1782 CHKMEMQ; \
1783 PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \
1784 } while (0)
1785
1786 /*MC
1787 PetscFunctionReturn - Last executable line of each PETSc function used for error
1788 handling. Replaces `return()`.
1789
1790 Synopsis:
1791 #include <petscsys.h>
1792 void PetscFunctionReturn(...)
1793
1794 Not Collective; No Fortran Support
1795
1796 Level: beginner
1797
1798 Notes:
1799 This routine is a macro, so while it does not "return" anything itself, it does return from
1800 the function in the literal sense.
1801
1802 Usually the return value is the integer literal `0` (for example in any function returning
1803 `PetscErrorCode`), however it is possible to return any arbitrary type. The arguments of
1804 this macro are placed before the `return` statement as-is.
1805
1806 Any routine which returns via `PetscFunctionReturn()` must begin with a corresponding
1807 `PetscFunctionBegin`.
1808
1809 For routines which return `void` use `PetscFunctionReturnVoid()` instead.
1810
1811 Example Usage:
1812 .vb
1813 PetscErrorCode foo(int *x)
1814 {
1815 PetscFunctionBegin; // don't forget the begin!
1816 *x = 10;
1817 PetscFunctionReturn(PETSC_SUCCESS);
1818 }
1819 .ve
1820
1821 May return any arbitrary type\:
1822 .vb
1823 struct Foo
1824 {
1825 int x;
1826 };
1827
1828 struct Foo make_foo(int value)
1829 {
1830 struct Foo f;
1831
1832 PetscFunctionBegin;
1833 f.x = value;
1834 PetscFunctionReturn(f);
1835 }
1836 .ve
1837
1838 .seealso: `PetscFunctionBegin`, `PetscFunctionBeginUser`, `PetscFunctionReturnVoid()`,
1839 `PetscStackPopNoCheck()`
1840 M*/
1841 #define PetscFunctionReturn(...) \
1842 do { \
1843 PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \
1844 return __VA_ARGS__; \
1845 } while (0)
1846
1847 /*MC
1848 PetscFunctionReturnVoid - Like `PetscFunctionReturn()` but returns `void`
1849
1850 Synopsis:
1851 #include <petscsys.h>
1852 void PetscFunctionReturnVoid()
1853
1854 Not Collective
1855
1856 Level: beginner
1857
1858 Note:
1859 Behaves identically to `PetscFunctionReturn()` except that it returns `void`. That is, this
1860 macro culminates with `return`.
1861
1862 Example Usage:
1863 .vb
1864 void foo()
1865 {
1866 PetscFunctionBegin; // must start with PetscFunctionBegin!
1867 bar();
1868 baz();
1869 PetscFunctionReturnVoid();
1870 }
1871 .ve
1872
1873 .seealso: `PetscFunctionReturn()`, `PetscFunctionBegin`, PetscFunctionBeginUser`
1874 M*/
1875 #define PetscFunctionReturnVoid() \
1876 do { \
1877 PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \
1878 return; \
1879 } while (0)
1880 #else /* PETSC_USE_DEBUG */
1881 #define PetscStackPushNoCheck(funct, petsc_routine, hot)
1882 #define PetscStackUpdateLine
1883 #define PetscStackPushExternal(funct)
1884 #define PetscStackPopNoCheck(...)
1885 #define PetscStackClearTop
1886 #define PetscFunctionBegin
1887 #define PetscFunctionBeginUser
1888 #define PetscFunctionBeginHot
1889 #define PetscFunctionReturn(...) return __VA_ARGS__
1890 #define PetscFunctionReturnVoid() return
1891 #define PetscStackPop CHKMEMQ
1892 #define PetscStackPush(f) CHKMEMQ
1893 #endif /* PETSC_USE_DEBUG */
1894
1895 #if defined(PETSC_CLANG_STATIC_ANALYZER)
1896 #define PetscStackCallExternalVoid(...)
1897 template <typename F, typename... Args>
1898 void PetscCallExternal(F, Args...);
1899 template <typename F, typename... Args>
1900 void PetscCallExternalAbort(F, Args...);
1901 #else
1902 /*MC
1903 PetscStackCallExternalVoid - Calls an external library routine or user function after pushing the name of the routine on the stack.
1904
1905 Input Parameters:
1906 + name - string that gives the name of the function being called
1907 - routine - actual call to the routine, for example, functionname(a,b)
1908
1909 Level: developer
1910
1911 Notes:
1912 Often one should use `PetscCallExternal()` instead. This routine is intended for external library routines that DO NOT return error codes
1913
1914 In debug mode this also checks the memory for corruption at the end of the function call.
1915
1916 Certain external packages, such as BLAS/LAPACK may have their own macros, `PetscCallBLAS()` for managing the call, error checking, etc.
1917
1918 Developer Note:
1919 This is so that when a user or external library routine results in a crash or corrupts memory, they get blamed instead of PETSc.
1920
1921 .seealso: `PetscCall()`, `PetscStackPushNoCheck()`, `PetscStackPush()`, `PetscCallExternal()`, `PetscCallBLAS()`
1922 @*/
1923 #define PetscStackCallExternalVoid(name, ...) \
1924 do { \
1925 PetscStackPushExternal(name); \
1926 __VA_ARGS__; \
1927 PetscStackPop; \
1928 } while (0)
1929
1930 /*MC
1931 PetscCallExternal - Calls an external library routine that returns an error code after pushing the name of the routine on the stack.
1932
1933 Input Parameters:
1934 + func - name of the routine
1935 - args - arguments to the routine
1936
1937 Level: developer
1938
1939 Notes:
1940 This is intended for external package routines that return error codes. Use `PetscStackCallExternalVoid()` for those that do not.
1941
1942 In debug mode this also checks the memory for corruption at the end of the function call.
1943
1944 Assumes the error return code of the function is an integer and that a value of 0 indicates success
1945
1946 Developer Note:
1947 This is so that when an external package routine results in a crash or corrupts memory, they get blamed instead of PETSc.
1948
1949 .seealso: `PetscCall()`, `PetscStackPushNoCheck()`, `PetscStackPush()`, `PetscStackCallExternalVoid()`, `PetscCallExternalAbort()`
1950 M*/
1951 #define PetscCallExternal(func, ...) \
1952 do { \
1953 PetscStackPush(PetscStringize(func)); \
1954 int ierr_petsc_call_external_ = (int)func(__VA_ARGS__); \
1955 PetscStackPop; \
1956 PetscCheck(ierr_petsc_call_external_ == 0, PETSC_COMM_SELF, PETSC_ERR_LIB, "Error in %s(): error code %d", PetscStringize(func), ierr_petsc_call_external_); \
1957 } while (0)
1958
1959 /*MC
1960 PetscCallExternalAbort - Calls an external library routine that returns an error code after pushing the name of the routine on the stack. If the external library function return code indicates an error, this prints the error and aborts
1961
1962 Input Parameters:
1963 + func - name of the routine
1964 - args - arguments to the routine
1965
1966 Level: developer
1967
1968 Notes:
1969 This is intended for external package routines that return error codes. Use `PetscStackCallExternalVoid()` for those that do not.
1970
1971 In debug mode this also checks the memory for corruption at the end of the function call.
1972
1973 Assumes the error return code of the function is an integer and that a value of 0 indicates success
1974
1975 Developer Note:
1976 This is so that when an external package routine results in a crash or corrupts memory, they get blamed instead of PETSc.
1977
1978 .seealso: `PetscCall()`, `PetscStackPushNoCheck()`, `PetscStackPush()`, `PetscStackCallExternalVoid()`, `PetscCallExternal()`
1979 M*/
1980 #define PetscCallExternalAbort(func, ...) \
1981 do { \
1982 PetscStackUpdateLine; \
1983 int ierr_petsc_call_external_ = func(__VA_ARGS__); \
1984 if (PetscUnlikely(ierr_petsc_call_external_ != 0)) { \
1985 (void)PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, PETSC_ERR_LIB, PETSC_ERROR_INITIAL, "Error in %s(): error code %d", PetscStringize(func), ierr_petsc_call_external_); \
1986 PETSCABORTWITHIERR_Private(PETSC_COMM_SELF, PETSC_ERR_LIB); \
1987 } \
1988 } while (0)
1989 #endif /* PETSC_CLANG_STATIC_ANALYZER */
1990