PageRenderTime 7ms CodeModel.GetById 4ms app.highlight 9ms RepoModel.GetById 1ms app.codeStats 0ms

/include/petscerror.h

https://bitbucket.org/petsc/petsc
C Header | 910 lines | 211 code | 60 blank | 639 comment | 27 complexity | ed7538d315b52b8a5232f25c6424cbfe MD5 | raw file
  1/*
  2    Contains all error handling interfaces for PETSc.
  3*/
  4#if !defined(PETSCERROR_H)
  5#define PETSCERROR_H
  6
  7/*
  8     These are the generic error codes. These error codes are used
  9     many different places in the PETSc source code. The string versions are
 10     at src/sys/error/err.c any changes here must also be made there
 11     These are also define in include/petsc/finclude/petscerror.h any CHANGES here
 12     must be also made there.
 13
 14*/
 15#define PETSC_ERR_MIN_VALUE        54   /* should always be one less then the smallest value */
 16
 17#define PETSC_ERR_MEM              55   /* unable to allocate requested memory */
 18#define PETSC_ERR_SUP              56   /* no support for requested operation */
 19#define PETSC_ERR_SUP_SYS          57   /* no support for requested operation on this computer system */
 20#define PETSC_ERR_ORDER            58   /* operation done in wrong order */
 21#define PETSC_ERR_SIG              59   /* signal received */
 22#define PETSC_ERR_FP               72   /* floating point exception */
 23#define PETSC_ERR_COR              74   /* corrupted PETSc object */
 24#define PETSC_ERR_LIB              76   /* error in library called by PETSc */
 25#define PETSC_ERR_PLIB             77   /* PETSc library generated inconsistent data */
 26#define PETSC_ERR_MEMC             78   /* memory corruption */
 27#define PETSC_ERR_CONV_FAILED      82   /* iterative method (KSP or SNES) failed */
 28#define PETSC_ERR_USER             83   /* user has not provided needed function */
 29#define PETSC_ERR_SYS              88   /* error in system call */
 30#define PETSC_ERR_POINTER          70   /* pointer does not point to valid address */
 31#define PETSC_ERR_MPI_LIB_INCOMP   87   /* MPI library at runtime is not compatible with MPI user compiled with */
 32
 33#define PETSC_ERR_ARG_SIZ          60   /* nonconforming object sizes used in operation */
 34#define PETSC_ERR_ARG_IDN          61   /* two arguments not allowed to be the same */
 35#define PETSC_ERR_ARG_WRONG        62   /* wrong argument (but object probably ok) */
 36#define PETSC_ERR_ARG_CORRUPT      64   /* null or corrupted PETSc object as argument */
 37#define PETSC_ERR_ARG_OUTOFRANGE   63   /* input argument, out of range */
 38#define PETSC_ERR_ARG_BADPTR       68   /* invalid pointer argument */
 39#define PETSC_ERR_ARG_NOTSAMETYPE  69   /* two args must be same object type */
 40#define PETSC_ERR_ARG_NOTSAMECOMM  80   /* two args must be same communicators */
 41#define PETSC_ERR_ARG_WRONGSTATE   73   /* object in argument is in wrong state, e.g. unassembled mat */
 42#define PETSC_ERR_ARG_TYPENOTSET   89   /* the type of the object has not yet been set */
 43#define PETSC_ERR_ARG_INCOMP       75   /* two arguments are incompatible */
 44#define PETSC_ERR_ARG_NULL         85   /* argument is null that should not be */
 45#define PETSC_ERR_ARG_UNKNOWN_TYPE 86   /* type name doesn't match any registered type */
 46
 47#define PETSC_ERR_FILE_OPEN        65   /* unable to open file */
 48#define PETSC_ERR_FILE_READ        66   /* unable to read from file */
 49#define PETSC_ERR_FILE_WRITE       67   /* unable to write to file */
 50#define PETSC_ERR_FILE_UNEXPECTED  79   /* unexpected data in file */
 51
 52#define PETSC_ERR_MAT_LU_ZRPVT     71   /* detected a zero pivot during LU factorization */
 53#define PETSC_ERR_MAT_CH_ZRPVT     81   /* detected a zero pivot during Cholesky factorization */
 54
 55#define PETSC_ERR_INT_OVERFLOW     84
 56
 57#define PETSC_ERR_FLOP_COUNT       90
 58#define PETSC_ERR_NOT_CONVERGED    91  /* solver did not converge */
 59#define PETSC_ERR_MISSING_FACTOR   92  /* MatGetFactor() failed */
 60#define PETSC_ERR_OPT_OVERWRITE    93  /* attempted to over wrote options which should not be changed */
 61
 62#define PETSC_ERR_MAX_VALUE        94  /* this is always the one more than the largest error code */
 63
 64#define PetscStringizeArg(a) #a
 65#define PetscStringize(a) PetscStringizeArg(a)
 66
 67
 68/*MC
 69   SETERRQ - Macro to be called when an error has been detected,
 70
 71   Synopsis:
 72   #include <petscsys.h>
 73   PetscErrorCode SETERRQ(MPI_Comm comm,PetscErrorCode ierr,char *message)
 74
 75   Collective
 76
 77   Input Parameters:
 78+  comm - A communicator, use PETSC_COMM_SELF unless you know all ranks of another communicator will detect the error
 79.  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
 80-  message - error message
 81
 82  Level: beginner
 83
 84   Notes:
 85    Once the error handler is called the calling function is then returned from with the given error code.
 86
 87    See SETERRQ1(), SETERRQ2(), SETERRQ3() for versions that take arguments
 88
 89    Experienced users can set the error handler with PetscPushErrorHandler().
 90
 91.seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3()
 92M*/
 93#define SETERRQ(comm,ierr,s) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s)
 94
 95/*MC
 96   SETERRMPI - Macro to be called when an error has been detected within an MPI callback function
 97
 98   Synopsis:
 99   #include <petscsys.h>
100   PetscErrorCode SETERRMPI(MPI_Comm comm,PetscErrorCode ierr,char *message)
101
102   Collective
103
104   Input Parameters:
105+  comm - A communicator, use PETSC_COMM_SELF unless you know all ranks of another communicator will detect the error
106.  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
107-  message - error message
108
109  Level: developer
110
111   Notes:
112    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
113    which is registered with MPI_Add_error_code() when PETSc is initialized.
114
115.seealso: SETERRQ(), CHKERRQ(), CHKERRMPI(), PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3()
116M*/
117#define SETERRMPI(comm,ierr,s) return (PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s),PETSC_MPI_ERROR_CODE)
118
119/*MC
120   SETERRQ1 - Macro that is called when an error has been detected,
121
122   Synopsis:
123   #include <petscsys.h>
124   PetscErrorCode SETERRQ1(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg)
125
126   Collective
127
128   Input Parameters:
129+  comm - A 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
132-  arg - argument (for example an integer, string or double)
133
134  Level: beginner
135
136   Notes:
137    Once the error handler is called the calling function is then returned from with the given error code.
138
139   Experienced users can set the error handler with PetscPushErrorHandler().
140
141.seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ(), SETERRQ2(), SETERRQ3()
142M*/
143#define SETERRQ1(comm,ierr,s,a1) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1)
144
145/*MC
146   SETERRQ2 - Macro that is called when an error has been detected,
147
148   Synopsis:
149   #include <petscsys.h>
150   PetscErrorCode SETERRQ2(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2)
151
152   Collective
153
154   Input Parameters:
155+  comm - A communicator, so that the error can be collective
156.  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
157.  message - error message in the printf format
158.  arg1 - argument (for example an integer, string or double)
159-  arg2 - argument (for example an integer, string or double)
160
161  Level: beginner
162
163   Notes:
164    Once the error handler is called the calling function is then returned from with the given error code.
165
166   Experienced users can set the error handler with PetscPushErrorHandler().
167
168.seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ3()
169M*/
170#define SETERRQ2(comm,ierr,s,a1,a2) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1,a2)
171
172/*MC
173   SETERRQ3 - Macro that is called when an error has been detected,
174
175   Synopsis:
176   #include <petscsys.h>
177   PetscErrorCode SETERRQ3(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2,arg3)
178
179   Collective
180
181   Input Parameters:
182+  comm - A communicator, so that the error can be collective
183.  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
184.  message - error message in the printf format
185.  arg1 - argument (for example an integer, string or double)
186.  arg2 - argument (for example an integer, string or double)
187-  arg3 - argument (for example an integer, string or double)
188
189  Level: beginner
190
191   Notes:
192    Once the error handler is called the calling function is then returned from with the given error code.
193
194    There are also versions for 4, 5, 6 and 7 arguments.
195
196   Experienced users can set the error handler with PetscPushErrorHandler().
197
198.seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
199M*/
200#define SETERRQ3(comm,ierr,s,a1,a2,a3) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1,a2,a3)
201
202/*MC
203   SETERRQ4 - Macro that is called when an error has been detected,
204
205   Synopsis:
206   #include <petscsys.h>
207   PetscErrorCode SETERRQ4(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2,arg3)
208
209   Collective
210
211   Input Parameters:
212+  comm - A communicator, so that the error can be collective
213.  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
214.  message - error message in the printf format
215.  arg1 - argument (for example an integer, string or double)
216.  arg2 - argument (for example an integer, string or double)
217.  arg3 - argument (for example an integer, string or double)
218-  arg4 - argument (for example an integer, string or double)
219
220  Level: beginner
221
222   Notes:
223    Once the error handler is called the calling function is then returned from with the given error code.
224
225    There are also versions for 4, 5, 6 and 7 arguments.
226
227   Experienced users can set the error handler with PetscPushErrorHandler().
228
229.seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
230M*/
231#define SETERRQ4(comm,ierr,s,a1,a2,a3,a4) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4)
232
233/*MC
234   SETERRQ5 - Macro that is called when an error has been detected,
235
236   Synopsis:
237   #include <petscsys.h>
238   PetscErrorCode SETERRQ5(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2,arg3)
239
240   Collective
241
242   Input Parameters:
243+  comm - A communicator, so that the error can be collective
244.  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
245.  message - error message in the printf format
246.  arg1 - argument (for example an integer, string or double)
247.  arg2 - argument (for example an integer, string or double)
248.  arg3 - argument (for example an integer, string or double)
249.  arg4 - argument (for example an integer, string or double)
250-  arg5 - argument (for example an integer, string or double)
251
252  Level: beginner
253
254   Notes:
255    Once the error handler is called the calling function is then returned from with the given error code.
256
257    There are also versions for 4, 5, 6 and 7 arguments.
258
259   Experienced users can set the error handler with PetscPushErrorHandler().
260
261.seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
262M*/
263#define SETERRQ5(comm,ierr,s,a1,a2,a3,a4,a5) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5)
264
265/*MC
266   SETERRQ6 - Macro that is called when an error has been detected,
267
268   Synopsis:
269   #include <petscsys.h>
270   PetscErrorCode SETERRQ6(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2,arg3)
271
272   Collective
273
274   Input Parameters:
275+  comm - A communicator, so that the error can be collective
276.  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
277.  message - error message in the printf format
278.  arg1 - argument (for example an integer, string or double)
279.  arg2 - argument (for example an integer, string or double)
280.  arg3 - argument (for example an integer, string or double)
281.  arg4 - argument (for example an integer, string or double)
282.  arg5 - argument (for example an integer, string or double)
283-  arg6 - argument (for example an integer, string or double)
284
285  Level: beginner
286
287   Notes:
288    Once the error handler is called the calling function is then returned from with the given error code.
289
290    There are also versions for 4, 5, 6 and 7 arguments.
291
292   Experienced users can set the error handler with PetscPushErrorHandler().
293
294.seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
295M*/
296#define SETERRQ6(comm,ierr,s,a1,a2,a3,a4,a5,a6) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6)
297
298/*MC
299   SETERRQ7 - Macro that is called when an error has been detected,
300
301   Synopsis:
302   #include <petscsys.h>
303   PetscErrorCode SETERRQ7(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2,arg3)
304
305   Collective
306
307   Input Parameters:
308+  comm - A communicator, so that the error can be collective
309.  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
310.  message - error message in the printf format
311.  arg1 - argument (for example an integer, string or double)
312.  arg2 - argument (for example an integer, string or double)
313.  arg3 - argument (for example an integer, string or double)
314.  arg4 - argument (for example an integer, string or double)
315.  arg5 - argument (for example an integer, string or double)
316.  arg6 - argument (for example an integer, string or double)
317-  arg7 - argument (for example an integer, string or double)
318
319  Level: beginner
320
321   Notes:
322    Once the error handler is called the calling function is then returned from with the given error code.
323
324    There are also versions for 4, 5, 6 and 7 arguments.
325
326   Experienced users can set the error handler with PetscPushErrorHandler().
327
328.seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
329M*/
330#define SETERRQ7(comm,ierr,s,a1,a2,a3,a4,a5,a6,a7) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6,a7)
331
332/*MC
333   SETERRQ8 - Macro that is called when an error has been detected,
334
335   Synopsis:
336   #include <petscsys.h>
337   PetscErrorCode SETERRQ8(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2,arg3)
338
339   Collective
340
341   Input Parameters:
342+  comm - A communicator, so that the error can be collective
343.  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
344.  message - error message in the printf format
345.  arg1 - argument (for example an integer, string or double)
346.  arg2 - argument (for example an integer, string or double)
347.  arg3 - argument (for example an integer, string or double)
348.  arg4 - argument (for example an integer, string or double)
349.  arg5 - argument (for example an integer, string or double)
350.  arg6 - argument (for example an integer, string or double)
351.  arg7 - argument (for example an integer, string or double)
352-  arg8 - argument (for example an integer, string or double)
353
354  Level: beginner
355
356   Notes:
357    Once the error handler is called the calling function is then returned from with the given error code.
358
359    There are also versions for 4, 5, 6 and 7 arguments.
360
361   Experienced users can set the error handler with PetscPushErrorHandler().
362
363.seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
364M*/
365#define SETERRQ8(comm,ierr,s,a1,a2,a3,a4,a5,a6,a7,a8) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6,a7,a8)
366
367/*MC
368   SETERRQ9 - Macro that is called when an error has been detected,
369
370   Synopsis:
371   #include <petscsys.h>
372   PetscErrorCode SETERRQ9(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2,arg3)
373
374   Collective
375
376   Input Parameters:
377+  comm - A communicator, so that the error can be collective
378.  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
379.  message - error message in the printf format
380.  arg1 - argument (for example an integer, string or double)
381.  arg2 - argument (for example an integer, string or double)
382.  arg3 - argument (for example an integer, string or double)
383.  arg4 - argument (for example an integer, string or double)
384.  arg5 - argument (for example an integer, string or double)
385.  arg6 - argument (for example an integer, string or double)
386.  arg7 - argument (for example an integer, string or double)
387.  arg8 - argument (for example an integer, string or double)
388-  arg9 - argument (for example an integer, string or double)
389
390  Level: beginner
391
392   Notes:
393    Once the error handler is called the calling function is then returned from with the given error code.
394
395    There are also versions for 0 to 9 arguments.
396
397   Experienced users can set the error handler with PetscPushErrorHandler().
398
399.seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
400M*/
401#define SETERRQ9(comm,ierr,s,a1,a2,a3,a4,a5,a6,a7,a8,a9) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6,a7,a8,a9)
402
403/*MC
404   SETERRABORT - Macro that can be called when an error has been detected,
405
406   Synopsis:
407   #include <petscsys.h>
408   PetscErrorCode SETERRABORT(MPI_Comm comm,PetscErrorCode ierr,char *message)
409
410   Collective
411
412   Input Parameters:
413+  comm - A communicator, so that the error can be collective
414.  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
415-  message - error message in the printf format
416
417  Level: beginner
418
419   Notes:
420    This function just calls MPI_Abort().
421
422.seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
423M*/
424#define SETERRABORT(comm,ierr,s) do {PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s);MPI_Abort(comm,ierr);} while (0)
425
426/*MC
427   CHKERRQ - Checks error code, if non-zero it calls the error handler and then returns
428
429   Synopsis:
430   #include <petscsys.h>
431   PetscErrorCode CHKERRQ(PetscErrorCode ierr)
432
433   Not Collective
434
435   Input Parameters:
436.  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
437
438  Level: beginner
439
440   Notes:
441    Once the error handler is called the calling function is then returned from with the given error code.
442
443    Experienced users can set the error handler with PetscPushErrorHandler().
444
445    CHKERRQ(ierr) is fundamentally a macro replacement for
446         if (ierr) return(PetscError(...,ierr,...));
447
448    Although typical usage resembles "void CHKERRQ(PetscErrorCode)" as described above, for certain uses it is
449    highly inappropriate to use it in this manner as it invokes return(PetscErrorCode). In particular,
450    it cannot be used in functions which return(void) or any other datatype.  In these types of functions,
451    you can use CHKERRV() which returns without an error code (bad idea since the error is ignored or
452         if (ierr) {PetscError(....); return(YourReturnType);}
453    where you may pass back a NULL to indicate an error. You can also call CHKERRABORT(comm,n) to have
454    MPI_Abort() returned immediately.
455
456.seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2()
457M*/
458#define CHKERRQ(ierr)          do {if (PetscUnlikely(ierr)) return PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_REPEAT," ");} while (0)
459#define CHKERRV(ierr)          do {if (PetscUnlikely(ierr)) {ierr = PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_REPEAT," ");return;}} while(0)
460#define CHKERRABORT(comm,ierr) do {if (PetscUnlikely(ierr)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_REPEAT," ");MPI_Abort(comm,ierr);}} while (0)
461#define CHKERRCONTINUE(ierr)   do {if (PetscUnlikely(ierr)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_REPEAT," ");}} while (0)
462
463
464/*MC
465   CHKERRMPI - Checks error code, if non-zero it calls the error handler and then returns
466
467   Synopsis:
468   #include <petscsys.h>
469   PetscErrorCode CHKERRMPI(PetscErrorCode ierr)
470
471   Not Collective
472
473   Input Parameters:
474.  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
475
476  Level: developer
477
478   Notes:
479    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
480    which is registered with MPI_Add_error_code() when PETSc is initialized.
481
482.seealso: CHKERRQ(), PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2()
483M*/
484#define CHKERRMPI(ierr)        do {if (PetscUnlikely(ierr)) return (PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_REPEAT," "),PETSC_MPI_ERROR_CODE);} while (0)
485
486#ifdef PETSC_CLANGUAGE_CXX
487
488/*MC
489   CHKERRXX - Checks error code, if non-zero it calls the C++ error handler which throws an exception
490
491   Synopsis:
492   #include <petscsys.h>
493   void CHKERRXX(PetscErrorCode ierr)
494
495   Not Collective
496
497   Input Parameters:
498.  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
499
500  Level: beginner
501
502   Notes:
503    Once the error handler throws a ??? exception.
504
505    You can use CHKERRV() which returns without an error code (bad idea since the error is ignored)
506    or CHKERRABORT(comm,n) to have MPI_Abort() returned immediately.
507
508.seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKERRQ(), CHKMEMQ
509M*/
510#define CHKERRXX(ierr)  do {if (PetscUnlikely(ierr)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_IN_CXX,0);}} while(0)
511
512#endif
513
514#if defined(PETSC_HAVE_CUDA)
515#define CHKERRCUDA(err)   do {if (PetscUnlikely(err)) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_LIB,"CUDA error %d",err);} while(0)
516#define CHKERRCUBLAS(err) do {if (PetscUnlikely(err)) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_LIB,"CUBLAS error %d",err);} while(0)
517#define CHKERRCUSOLVER(err) do {if (PetscUnlikely(err)) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_LIB,"CUSOLVER error %d",err);} while(0)
518#endif
519
520/*MC
521   CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected
522
523   Synopsis:
524   #include <petscsys.h>
525   CHKMEMQ;
526
527   Not Collective
528
529  Level: beginner
530
531   Notes:
532    We highly recommend using valgrind https://www.mcs.anl.gov/petsc/documentation/faq.html#valgrind for finding memory problems. This is useful
533    on systems that do not have valgrind, but much much less useful.
534
535    Must run with the option -malloc_debug (-malloc_test in debug mode; or if PetscMallocSetDebug() called) to enable this option
536
537    Once the error handler is called the calling function is then returned from with the given error code.
538
539    By defaults prints location where memory that is corrupted was allocated.
540
541    Use CHKMEMA for functions that return void
542
543.seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
544          PetscMallocValidate()
545M*/
546#define CHKMEMQ do {PetscErrorCode _7_ierr = PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__);CHKERRQ(_7_ierr);} while(0)
547
548#define CHKMEMA PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__)
549
550/*E
551  PetscErrorType - passed to the PETSc error handling routines indicating if this is the first or a later call to the error handlers
552
553  Level: advanced
554
555  PETSC_ERROR_IN_CXX indicates the error was detected in C++ and an exception should be generated
556
557  Developer Notes:
558    This is currently used to decide when to print the detailed information about the run in PetscTraceBackErrorHandler()
559
560.seealso: PetscError(), SETERRXX()
561E*/
562typedef enum {PETSC_ERROR_INITIAL=0,PETSC_ERROR_REPEAT=1,PETSC_ERROR_IN_CXX = 2} PetscErrorType;
563
564#if defined(__clang_analyzer__)
565__attribute__((analyzer_noreturn))
566#endif
567PETSC_EXTERN PetscErrorCode PetscError(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,...);
568
569PETSC_EXTERN PetscErrorCode PetscErrorPrintfInitialize(void);
570PETSC_EXTERN PetscErrorCode PetscErrorMessage(int,const char*[],char **);
571PETSC_EXTERN PetscErrorCode PetscTraceBackErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
572PETSC_EXTERN PetscErrorCode PetscIgnoreErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
573PETSC_EXTERN PetscErrorCode PetscEmacsClientErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
574PETSC_EXTERN PetscErrorCode PetscMPIAbortErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
575PETSC_EXTERN PetscErrorCode PetscAbortErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
576PETSC_EXTERN PetscErrorCode PetscAttachDebuggerErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
577PETSC_EXTERN PetscErrorCode PetscReturnErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
578PETSC_EXTERN PetscErrorCode PetscPushErrorHandler(PetscErrorCode (*handler)(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*),void*);
579PETSC_EXTERN PetscErrorCode PetscPopErrorHandler(void);
580PETSC_EXTERN PetscErrorCode PetscSignalHandlerDefault(int,void*);
581PETSC_EXTERN PetscErrorCode PetscPushSignalHandler(PetscErrorCode (*)(int,void *),void*);
582PETSC_EXTERN PetscErrorCode PetscPopSignalHandler(void);
583PETSC_EXTERN PetscErrorCode PetscCheckPointerSetIntensity(PetscInt);
584PETSC_EXTERN void PetscSignalSegvCheckPointer(void);
585
586/*MC
587    PetscErrorPrintf - Prints error messages.
588
589   Synopsis:
590    #include <petscsys.h>
591     PetscErrorCode (*PetscErrorPrintf)(const char format[],...);
592
593    Not Collective
594
595    Input Parameters:
596.   format - the usual printf() format string
597
598   Options Database Keys:
599+    -error_output_stdout - cause error messages to be printed to stdout instead of the  (default) stderr
600-    -error_output_none - to turn off all printing of error messages (does not change the way the error is handled.)
601
602   Notes:
603    Use
604$     PetscErrorPrintf = PetscErrorPrintfNone; to turn off all printing of error messages (does not change the way the
605$                        error is handled.) and
606$     PetscErrorPrintf = PetscErrorPrintfDefault; to turn it back on or you can use your own function
607
608          Use
609     PETSC_STDERR = FILE* obtained from a file open etc. to have stderr printed to the file.
610     PETSC_STDOUT = FILE* obtained from a file open etc. to have stdout printed to the file.
611
612          Use
613      PetscPushErrorHandler() to provide your own error handler that determines what kind of messages to print
614
615   Level: developer
616
617    Fortran Note:
618    This routine is not supported in Fortran.
619
620
621.seealso: PetscFPrintf(), PetscSynchronizedPrintf(), PetscHelpPrintf(), PetscPrintf(), PetscPushErrorHandler(), PetscVFPrintf(), PetscHelpPrintf()
622M*/
623PETSC_EXTERN PetscErrorCode (*PetscErrorPrintf)(const char[],...);
624
625typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap;
626PETSC_EXTERN PetscErrorCode PetscSetFPTrap(PetscFPTrap);
627PETSC_EXTERN PetscErrorCode PetscFPTrapPush(PetscFPTrap);
628PETSC_EXTERN PetscErrorCode PetscFPTrapPop(void);
629
630/*
631      Allows the code to build a stack frame as it runs
632*/
633
634#define PETSCSTACKSIZE 64
635
636typedef struct  {
637  const char      *function[PETSCSTACKSIZE];
638  const char      *file[PETSCSTACKSIZE];
639        int       line[PETSCSTACKSIZE];
640        PetscBool petscroutine[PETSCSTACKSIZE];
641        int       currentsize;
642        int       hotdepth;
643} PetscStack;
644
645PETSC_EXTERN PetscStack *petscstack;
646
647PetscErrorCode  PetscStackCopy(PetscStack*,PetscStack*);
648PetscErrorCode  PetscStackPrint(PetscStack *,FILE*);
649#if defined(PETSC_SERIALIZE_FUNCTIONS)
650#include <petsc/private/petscfptimpl.h>
651/*
652   Registers the current function into the global function pointer to function name table
653
654   Have to fix this to handle errors but cannot return error since used in PETSC_VIEWER_DRAW_() etc
655*/
656#define PetscRegister__FUNCT__() do { \
657  static PetscBool __chked = PETSC_FALSE; \
658  if (!__chked) {\
659  void *ptr; PetscDLSym(NULL,PETSC_FUNCTION_NAME,&ptr);\
660  __chked = PETSC_TRUE;\
661  }} while (0)
662#else
663#define PetscRegister__FUNCT__()
664#endif
665
666#if defined(PETSC_USE_DEBUG)
667PETSC_STATIC_INLINE PetscBool PetscStackActive(void)
668{
669  return(petscstack ? PETSC_TRUE : PETSC_FALSE);
670}
671
672/* Stack handling is based on the following two "NoCheck" macros.  These should only be called directly by other error
673 * handling macros.  We record the line of the call, which may or may not be the location of the definition.  But is at
674 * least more useful than "unknown" because it can distinguish multiple calls from the same function.
675 */
676
677#define PetscStackPushNoCheck(funct,petsc_routine,hot)                        \
678  do {                                                                        \
679    PetscStackSAWsTakeAccess();                                                \
680    if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) {         \
681      petscstack->function[petscstack->currentsize]  = funct;               \
682      petscstack->file[petscstack->currentsize]      = __FILE__;            \
683      petscstack->line[petscstack->currentsize]      = __LINE__;            \
684      petscstack->petscroutine[petscstack->currentsize] = petsc_routine;    \
685      petscstack->currentsize++;                                             \
686    }                                                                         \
687    if (petscstack) {                                                        \
688      petscstack->hotdepth += (hot || petscstack->hotdepth);                \
689    }                                                                         \
690    PetscStackSAWsGrantAccess();                                               \
691  } while (0)
692
693#define PetscStackPopNoCheck                                            \
694  do {                                                                  \
695    PetscStackSAWsTakeAccess();                                          \
696    if (petscstack && petscstack->currentsize > 0) {                  \
697      petscstack->currentsize--;                                       \
698      petscstack->function[petscstack->currentsize]  = 0;             \
699      petscstack->file[petscstack->currentsize]      = 0;             \
700      petscstack->line[petscstack->currentsize]      = 0;             \
701      petscstack->petscroutine[petscstack->currentsize] = PETSC_FALSE;\
702    }                                                                   \
703    if (petscstack) {                                                  \
704      petscstack->hotdepth = PetscMax(petscstack->hotdepth-1,0);      \
705    }                                                                   \
706    PetscStackSAWsGrantAccess();                                         \
707  } while (0)
708
709/*MC
710   PetscFunctionBegin - First executable line of each PETSc function,  used for error handling. Final
711      line of PETSc functions should be PetscFunctionReturn(0);
712
713   Synopsis:
714   #include <petscsys.h>
715   void PetscFunctionBegin;
716
717   Not Collective
718
719   Usage:
720.vb
721     int something;
722
723     PetscFunctionBegin;
724.ve
725
726   Notes:
727     Use PetscFunctionBeginUser for application codes.
728
729     Not available in Fortran
730
731   Level: developer
732
733.seealso: PetscFunctionReturn(), PetscFunctionBeginHot(), PetscFunctionBeginUser()
734
735M*/
736#define PetscFunctionBegin do {                                        \
737    PetscStackPushNoCheck(PETSC_FUNCTION_NAME,PETSC_TRUE,PETSC_FALSE); \
738    PetscRegister__FUNCT__();                                          \
739  } while (0)
740
741/*MC
742   PetscFunctionBeginHot - Substitute for PetscFunctionBegin to be used in functions that are called in
743   performance-critical circumstances.  Use of this function allows for lighter profiling by default.
744
745   Synopsis:
746   #include <petscsys.h>
747   void PetscFunctionBeginHot;
748
749   Not Collective
750
751   Usage:
752.vb
753     int something;
754
755     PetscFunctionBeginHot;
756.ve
757
758   Notes:
759     Not available in Fortran
760
761   Level: developer
762
763.seealso: PetscFunctionBegin, PetscFunctionReturn()
764
765M*/
766#define PetscFunctionBeginHot do {                                     \
767    PetscStackPushNoCheck(PETSC_FUNCTION_NAME,PETSC_TRUE,PETSC_TRUE);  \
768    PetscRegister__FUNCT__();                                          \
769  } while (0)
770
771/*MC
772   PetscFunctionBeginUser - First executable line of user provided PETSc routine
773
774   Synopsis:
775   #include <petscsys.h>
776   void PetscFunctionBeginUser;
777
778   Not Collective
779
780   Usage:
781.vb
782     int something;
783
784     PetscFunctionBeginUser;
785.ve
786
787   Notes:
788      Final line of PETSc functions should be PetscFunctionReturn(0) except for main().
789
790      Not available in Fortran
791
792      This is identical to PetscFunctionBegin except it labels the routine as a user
793      routine instead of as a PETSc library routine.
794
795   Level: intermediate
796
797.seealso: PetscFunctionReturn(), PetscFunctionBegin, PetscFunctionBeginHot
798
799M*/
800#define PetscFunctionBeginUser                                          \
801  do {                                                                  \
802    PetscStackPushNoCheck(PETSC_FUNCTION_NAME,PETSC_FALSE,PETSC_FALSE); \
803    PetscRegister__FUNCT__();                                           \
804  } while (0)
805
806
807#define PetscStackPush(n) \
808  do {                                                                  \
809    PetscStackPushNoCheck(n,PETSC_FALSE,PETSC_FALSE);                   \
810    CHKMEMQ;                                                            \
811  } while (0)
812
813#define PetscStackPop                           \
814    do {                                        \
815      CHKMEMQ;                                  \
816      PetscStackPopNoCheck;                     \
817    } while (0)
818
819/*MC
820   PetscFunctionReturn - Last executable line of each PETSc function
821        used for error handling. Replaces return()
822
823   Synopsis:
824   #include <petscsys.h>
825   void PetscFunctionReturn(0);
826
827   Not Collective
828
829   Usage:
830.vb
831    ....
832     PetscFunctionReturn(0);
833   }
834.ve
835
836   Notes:
837     Not available in Fortran
838
839   Level: developer
840
841.seealso: PetscFunctionBegin()
842
843M*/
844#define PetscFunctionReturn(a) \
845  do {                                                                \
846    PetscStackPopNoCheck;                                             \
847    return(a);} while (0)
848
849#define PetscFunctionReturnVoid() \
850  do {                                                                \
851    PetscStackPopNoCheck;                                             \
852    return;} while (0)
853
854#else
855
856PETSC_STATIC_INLINE PetscBool PetscStackActive(void) {return PETSC_FALSE;}
857#define PetscStackPushNoCheck(funct,petsc_routine,hot) do {} while (0)
858#define PetscStackPopNoCheck                           do {} while (0)
859#define PetscFunctionBegin
860#define PetscFunctionBeginUser
861#define PetscFunctionBeginHot
862#define PetscFunctionReturn(a)    return(a)
863#define PetscFunctionReturnVoid() return
864#define PetscStackPop             CHKMEMQ
865#define PetscStackPush(f)         CHKMEMQ
866
867#endif
868
869/*
870    PetscStackCall - Calls an external library routine or user function after pushing the name of the routine on the stack.
871
872   Input Parameters:
873+   name - string that gives the name of the function being called
874-   routine - actual call to the routine, including ierr = and CHKERRQ(ierr);
875
876   Note: Often one should use PetscStackCallStandard() instead. This routine is intended for external library routines that DO NOT return error codes
877
878   Developer Note: this is so that when a user or external library routine results in a crash or corrupts memory, they get blamed instead of PETSc.
879
880
881
882*/
883#define PetscStackCall(name,routine) do { PetscStackPush(name);routine;PetscStackPop; } while(0)
884
885/*
886    PetscStackCallStandard - Calls an external library routine after pushing the name of the routine on the stack.
887
888   Input Parameters:
889+   func-  name of the routine
890-   args - arguments to the routine surrounded by ()
891
892   Notes:
893    This is intended for external package routines that return error codes. Use PetscStackCall() for those that do not.
894
895   Developer Note: this is so that when an external packge routine results in a crash or corrupts memory, they get blamed instead of PETSc.
896
897*/
898#define PetscStackCallStandard(func,args) do {                                                            \
899    PetscErrorCode __ierr;                                                                                \
900    PetscStackPush(#func);                                                                                \
901    __ierr = func args;                                                                                   \
902    PetscStackPop;                                                                                        \
903    if (__ierr) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_LIB,"Error in %s(): error code %d",#func,(int)__ierr); \
904  } while (0)
905
906PETSC_EXTERN PetscErrorCode PetscStackCreate(void);
907PETSC_EXTERN PetscErrorCode PetscStackView(FILE*);
908PETSC_EXTERN PetscErrorCode PetscStackDestroy(void);
909
910#endif